Quickstart

Quickstart#

This guide will walk you through creating your first ARGscape visualization in just a few lines of code.

Prerequisites#

Make sure you have ARGscape installed:

pip install argscape

Tip

Want a full graphical interface? Run argscape serve to launch the ARGscape web application with an intuitive UI for uploading tree sequences, running spatial inference, and creating visualizations - no coding required. This requires pip install argscape[spatial].

The rest of this tutorial covers the Python API and CLI tools for programmatic workflows.

Creating a Sample Tree Sequence#

First, let’s create a simple tree sequence using msprime. If you already have a .trees file, you can skip to the next section.

import msprime
import tskit

# Simulate a simple tree sequence
ts = msprime.sim_ancestry(
    samples=10,
    sequence_length=2000,
    recombination_rate=1e-8,
    population_size=10_000,
    random_seed=42
)

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

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: 54
Mutations: 6

Basic Visualization#

Now let’s create a visualization using argscape.visualize():

import argscape

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

# Display inline (in Jupyter notebook)
viz.display()

<argscape.visualize.VizResult at 0x14db03310>

Try hovering your cursor over one of the nodes - much of the metadata available within the tree sequence can be previewed this way. You can also zoom or click and drag to explore your visualization. Nodes can be dragged and dropped to customize the layout.

Customizing the Visualization#

ARGscape provides many options to customize the appearance:

# Customize the visualization
viz = argscape.visualize(
    ts,
    theme="paper",             # Use the tskit color scheme
    show_sample_ids=True,      # Display sample IDs
    show_root_ids=True,        # Display root IDs
    show_mutations=True,       # Display mutation markers
    sample_node_size=10,       # Larger sample nodes
    edge_opacity=0.7,          # More visible edges
    height=700,
    width=900
)

viz.display()

<argscape.visualize.VizResult at 0x14db35210>

Opening in Browser#

Opening in your browser instead of a notebook enables more advanced controls, including on-the-fly customization of layout, theme, and more. You can also see basic tree sequence statistics.

# Open in default browser
viz.show()

Exporting to File#

Export publication-ready figures (requires pip install argscape[spatial] and Playwright):

# Export as PNG
viz.export("my_visualization.png", dpi=300)

# Export as SVG for vector graphics
viz.export("my_visualization.svg")

# Export as PDF
viz.export("my_visualization.pdf")

Loading Existing Tree Sequences#

If you have an existing .trees file:

import tskit
import argscape

# Load from file
ts = tskit.load("path/to/your/file.trees")

# For compressed files (.tsz)
import tszip
ts = tszip.decompress("path/to/your/file.tsz")

# Then visualize as before
viz = argscape.visualize(ts)
viz.show()

Using the CLI#

You can also visualize directly from the command line:

# Open in browser
argscape_viz input.trees

# Export to file
argscape_viz input.trees -o output.png --theme liquid

# With custom options
argscape_viz input.trees -o output.svg --show-mutations --max-samples 100

What’s Next?#

On this page