Animations

Animations#

ARGscape supports animated visualizations that bring tree sequences to life. This tutorial demonstrates how to create temporal and genomic animations in both 2D and 3D modes.

Setup#

First, let’s import the necessary modules and create some example tree sequences.

import msprime
import tskit
import argscape
from argscape import TemporalAnimation, GenomicAnimation

# Create a simple tree sequence for 2D animations
ts = msprime.sim_ancestry(
    samples=20,
    population_size=1000,
    sequence_length=5000,
    recombination_rate=1e-7,
    random_seed=42
)

print(f"Samples: {ts.num_samples}")
print(f"Trees: {ts.num_trees}")
print(f"Sequence length: {ts.sequence_length:,.0f} bp")

Samples: 40
Trees: 7
Sequence length: 5,000 bp

Temporal Animations#

Temporal animations reveal the time structure of the ARG by progressively showing nodes based on their time values.

Glide Mode (Default)#

The "glide" mode smoothly expands the visible time range from samples upward toward roots.

# Glide animation - samples to roots
viz = argscape.visualize(
    ts,
    animation=TemporalAnimation(mode="glide", rate=9.0),
    height=600
)
viz.display()

<argscape.visualize.VizResult at 0x11fd5d940>

Click the play button to start the animation. You can:

  • Adjust speed with the slider

  • Pause and resume

  • Reset to beginning

Root-to-Samples Mode#

The "root-to-samples" mode animates in the opposite direction - from roots down to samples.

# Root-to-samples animation
viz = argscape.visualize(
    ts,
    animation=TemporalAnimation(mode="root-to-samples", rate=5.0),
    theme="tskit",  # Dark theme
    show_controls=True,
    height=700
)
viz.display()

<argscape.visualize.VizResult at 0x122712710>

Genomic Animations#

Genomic animations slide a window across the sequence, showing how local tree structure changes due to recombination.

Window in Tree Count#

For variable recombination rates, specify window size by number of trees instead.

# Show one tree at a time
viz = argscape.visualize(
    ts,
    theme="tskit",
    animation=GenomicAnimation(
        window_trees=1,  # Show 1 tree at a time
        step=1,          # Move by 1 tree per frame
        rate=1.0
    ),
    show_controls=True,
    height=700
)
viz.display()

<argscape.visualize.VizResult at 0x11fcf6490>

3D Spatial Animations#

Animations work with 3D spatial visualizations too. Let’s load a spatial tree sequence.

# Load spatial tree sequence
ts_spatial = tskit.load("../data/population_expansion_simplified.trees")

print(f"Samples: {ts_spatial.num_samples}")
print(f"Trees: {ts_spatial.num_trees}")

Samples: 60
Trees: 1

# Temporal animation in 3D
viz = argscape.visualize(
    ts_spatial,
    mode="spatial_3d",
    animation=TemporalAnimation(mode="glide", rate=9.0),
    spatial_multiplier=160,
    temporal_multiplier=12,
    height=700
)
viz.display()

<argscape.visualize.VizResult at 0x122734c30>

Next Steps#

On this page