First Visualization

First Visualization#

This tutorial walks through creating your first ARGscape visualization, covering all the key options for customizing the appearance of your ARG.

Setup#

First, let’s import the required libraries and create a sample tree sequence.

import msprime
import argscape

# Simulate a tree sequence with recombination
ts = msprime.sim_ancestry(
    samples=10,
    sequence_length=1200,
    recombination_rate=1e-8,
    population_size=10_000,
    random_seed=43555
)

# Add mutations for context
ts = msprime.sim_mutations(ts, rate=1e-8, random_seed=45)

print(f"Samples: {ts.num_samples}")
print(f"Trees: {ts.num_trees}")
print(f"Nodes: {ts.num_nodes}")
print(f"Edges: {ts.num_edges}")
print(f"Mutations: {ts.num_mutations}")

Samples: 20
Trees: 5
Nodes: 42
Edges: 48
Mutations: 3

Basic 2D Visualization#

The simplest way to visualize a tree sequence is with default settings. This creates a force-directed graph layout.

# Create and display a basic visualization
viz = argscape.visualize(ts)
viz.display()

<argscape.visualize.VizResult at 0x10b205e80>

Display Modes and Interactive Controls#

ARGscape visualizations can be displayed in two ways:

  • .display() - Renders inline in Jupyter notebooks (compact view by default)

  • .show() - Opens in a new browser tab with full interactive controls

Browser Mode (.show())#

When you use .show(), the visualization opens in your browser with a quick actions bar on the right side. This bar provides access to:

Button

Shortcut

Description

Nodes

N

Adjust node sizes and toggle ID labels

Edges

E

Change edge width and opacity

Mutations

M

Toggle mutation markers and adjust size

Layout

L

Change sample ordering, temporal spacing, and spacing percentages

Theme

T

Switch between themes

Stats

I

View statistics about the visualization (node counts, edge counts, etc.)

Export

X

Export the visualization as PNG, SVG, or PDF

Interactive Features#

All visualizations support:

  • Drag nodes - Click and drag any node to reposition it

  • Pan and zoom - Use mouse scroll to zoom, drag background to pan

  • Hover tooltips - Hover over nodes to see ID and time; hover over edges to see genomic span

  • Filter sliders - Use the genomic and temporal range sliders (collapsed by default in notebooks) to filter the view

Enabling Controls in Notebooks#

By default, .display() shows a minimal view without the quick actions bar. To enable the full control panel in notebooks, use show_controls=True:

# Enable interactive controls in notebook
viz = argscape.visualize(ts, show_controls=True)
viz.display()

<argscape.visualize.VizResult at 0x11f95d950>

With show_controls=True, you can access all the interactive panels directly in your notebook. Click the Stats button (or press I) to see:

  • Number of samples, internal nodes, and root nodes

  • Total edges and their genomic span statistics

  • Mutation counts (if shown)

  • Time range of the ARG

Tip

Use .show() when you want the full browser experience with keyboard shortcuts. Use .display(show_controls=True) when you want interactive controls without leaving your notebook.

Choosing a Theme#

ARGscape provides four built-in themes:

  • "liquid" (default) - Light theme with Apple-inspired glassmorphism

  • "tskit" - Dark theme with cyan/green accents

  • "grayscale" - Black and white for publications

  • "paper" - Optimized for print figures

# Dark theme
viz = argscape.visualize(ts, theme="tskit")
viz.display()

<argscape.visualize.VizResult at 0x10b19b110>

# Grayscale for publications
viz = argscape.visualize(ts, theme="grayscale", width=900, height=500)
viz.display()

<argscape.visualize.VizResult at 0x11f97c9d0>

Custom Colors#

You can override specific colors from any theme using color parameters. This is useful when you want to match your publication’s color scheme or highlight specific elements.

# Paper theme with custom sample and edge colors
viz = argscape.visualize(
    ts,
    theme="paper",
    sample_color="#e63946",   # Red samples
    edge_color="#457b9d",     # Blue-gray edges
    show_sample_ids=True,
)
viz.display()

<argscape.visualize.VizResult at 0x11f97cd60>

Available color parameters: sample_color, internal_color, root_color, edge_color, background_color, mutation_color, text_color. All colors should be hex strings (e.g., "#ff0000").

See also

See Themes for a complete guide to themes and custom color palettes.

Customizing Node Appearance#

You can customize the size of different node types and optionally show their IDs.

viz = argscape.visualize(
    ts,
    sample_node_size=12,      # Larger sample nodes
    internal_node_size=5,     # Medium internal nodes  
    root_node_size=8,         # Visible root nodes
    show_sample_ids=True,     # Show sample IDs
)
viz.display()

<argscape.visualize.VizResult at 0x11f94a210>

Customizing Edge Appearance#

Edges can be styled with different widths and opacity levels.

viz = argscape.visualize(
    ts,
    edge_width=4.0,           # Thicker edges
    edge_opacity=0.9,         # More visible
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x11f995480>

Showing Mutations#

Mutations can be displayed as markers along the edges where they occurred. Hover over mutation markers to view more information on them.

viz = argscape.visualize(
    ts,
    show_mutations=True,
    mutation_size=8,
    width=900,
    height=600
)
viz.display()

<argscape.visualize.VizResult at 0x11f994e20>

Layout Options#

The 2D visualization provides several options for controlling the layout:

Sample Ordering#

The sample_order parameter controls how samples are arranged horizontally:

Algorithm

Description

"consensus_minlex"

Default. Consensus ordering from multiple trees - usually produces clean layouts

"dagre"

Minimizes edge crossings - often the best choice for publication figures

"numeric"

Simple numeric order (0, 1, 2, …)

"first_minlex" / "center_minlex"

Minlex postorder of first/center tree

Temporal Spacing#

The temporal_spacing parameter controls vertical spacing between time layers:

  • "equal" - Equal spacing between time points (default)

  • "linear" - Proportional to actual time differences

  • "log" - Logarithmic scaling, emphasizes recent history

# Dagre layout - minimizes edge crossings
viz = argscape.visualize(
    ts,
    sample_order="dagre",
    show_sample_ids=True
)
viz.display()

<argscape.visualize.VizResult at 0x11f9b0950>

# Log temporal spacing - emphasizes recent history
viz = argscape.visualize(
    ts,
    temporal_spacing="log",
    vertical_spacing=80,
    show_sample_ids=True
)
viz.display()

<argscape.visualize.VizResult at 0x11f9b0a50>

3D Spatial Visualization#

If your tree sequence has spatial location data, you can visualize it in 3D with mode="spatial_3d". Let’s load an example with geographic coordinates and population structure.

import tskit

# Load a tree sequence with spatial coordinates and populations
ts_spatial = tskit.load("../data/population_expansion_simplified.trees")

print(f"Samples: {ts_spatial.num_samples}")
print(f"Has locations: {ts_spatial.num_individuals > 0}")

Samples: 60
Has locations: True

# 3D spatial visualization
viz = argscape.visualize(
    ts_spatial,
    mode="spatial_3d",
    theme="tskit",
    sample_node_size=10,
    spatial_multiplier=160,
    temporal_multiplier=12,
    width=900,
    height=700
)
viz.display()

<argscape.visualize.VizResult at 0x11f975400>

In 3D mode, samples are placed at their geographic coordinates on the X-Y plane, with time extending upward on the Z axis. Key parameters include:

  • spatial_multiplier - Controls the spread of the X-Y plane

  • temporal_multiplier - Controls the height of the time axis

Use 2D mode (force_graph) when you want to focus on genealogical relationships and topology. Use 3D mode (spatial_3d) when your data has geographic locations and you want to visualize spatial patterns of ancestry.

Next Steps#

On this page