Themes

This tutorial explores ARGscape’s built-in color themes and how to customize them. Themes control the visual appearance of your visualizations, from node colors to backgrounds and text.

Setup

Let’s create a sample tree sequence to demonstrate the themes.

Show code cell source

Hide code cell source

import msprime
import argscape
import matplotlib.pyplot as plt
import matplotlib.patches as mpatches

# Simulate a tree sequence
ts = msprime.sim_ancestry(
    samples=12,
    sequence_length=1500,
    recombination_rate=1e-8,
    population_size=10_000,
    random_seed=42
)
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"Mutations: {ts.num_mutations}")

Samples: 24
Trees: 2
Mutations: 2

Available Themes

ARGscape includes four built-in themes:

Theme	Style	Best For
liquid	Light with glass effects	General use, web display (default)
tskit	Dark with cyan/green accents	Presentations, screen viewing
grayscale	Black and white	Journal publications (no color)
paper	High contrast colors	Print publications, color figures

Theme Color Palettes

Show code cell source

Hide code cell source

def show_palette(theme_name, theme=None):
    """Display color palette for a theme."""
    if theme is None:
        theme = argscape.get_theme(theme_name)
    
    colors = {
        'Background': theme.background,
        'Sample nodes': theme.nodes.sample,
        'Internal nodes': theme.nodes.internal,
        'Root nodes': theme.nodes.root,
        'Edges': theme.edges.default,
        'Mutations': theme.mutation,
        'Text': theme.text,
    }
    
    fig, ax = plt.subplots(figsize=(10, 1.5))
    
    # Draw color swatches
    n = len(colors)
    for i, (name, color) in enumerate(colors.items()):
        rect = mpatches.Rectangle((i/n, 0), 1/n - 0.01, 1, 
                                   facecolor=color, edgecolor='#ccc', linewidth=1)
        ax.add_patch(rect)
        # Choose text color based on background lightness
        text_color = '#000' if sum(int(color[j:j+2], 16) for j in (1,3,5)) > 380 else '#fff'
        ax.text((i + 0.5)/n, 0.5, name, ha='center', va='center', 
                fontsize=8, color=text_color, fontweight='bold')
    
    ax.set_xlim(0, 1)
    ax.set_ylim(0, 1)
    ax.axis('off')
    ax.set_title(f'{theme_name} theme', fontsize=12, fontweight='bold', pad=10)
    plt.tight_layout()
    plt.show()

# Show all theme palettes
for theme_name in argscape.list_themes():
    show_palette(theme_name)

liquid Theme (Default)

A light, Apple-inspired theme with subtle glass effects. Best for general use and web display.

viz = argscape.visualize(
    ts,
    theme="liquid",
    show_sample_ids=True,
    show_mutations=True,
    sample_order="dagre",
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x10e961940>

tskit Theme

The original ARGscape dark theme with signature cyan and green accents. Best for presentations and screen viewing.

viz = argscape.visualize(
    ts,
    theme="tskit",
    show_sample_ids=True,
    show_mutations=True,
    sample_order="dagre",
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x10d5e7b10>

grayscale Theme

A publication-ready theme using only shades of gray. Best for journals that don’t accept color figures.

viz = argscape.visualize(
    ts,
    theme="grayscale",
    show_sample_ids=True,
    show_mutations=True,
    sample_order="dagre",
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x10eaa0910>

paper Theme

High-contrast colors optimized for print publications. Distinct colors for different node types make it easy to identify structure.

viz = argscape.visualize(
    ts,
    theme="paper",
    show_sample_ids=True,
    show_mutations=True,
    sample_order="dagre",
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x14d28e780>

Themes in 3D Mode

All themes work in 3D spatial visualizations. Let’s load a tree sequence with spatial data and population structure to see how each theme renders in 3D.

import tskit

# Load tree sequence with spatial coordinates and population structure
ts_spatial = tskit.load("../data/population_split_simplified.trees")

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

Samples: 60
Populations: 4
Has spatial locations: True

liquid Theme in 3D

The default liquid theme provides a clean, modern look in 3D visualizations.

viz = argscape.visualize(
    ts_spatial,
    mode="spatial_3d",
    theme="liquid",
    color_by_population=True,
    sample_node_size=10,
    spatial_multiplier=160,
    temporal_multiplier=12,
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x14d28ec40>

tskit Theme in 3D

The dark tskit theme provides excellent contrast in 3D, making it ideal for presentations and screen viewing. The dark background helps edges and nodes stand out.

viz = argscape.visualize(
    ts_spatial,
    mode="spatial_3d",
    theme="tskit",
    color_by_population=True,
    sample_node_size=10,
    spatial_multiplier=160,
    temporal_multiplier=12,
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x14d344cb0>

paper Theme in 3D

The paper theme’s high-contrast colors work well in 3D for publication figures where clarity is essential.

viz = argscape.visualize(
    ts_spatial,
    mode="spatial_3d",
    theme="paper",
    color_by_population=True,
    sample_node_size=10,
    spatial_multiplier=160,
    temporal_multiplier=12,
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x14d305370>

3D Theme Recommendations

Use Case	Recommended Theme
Interactive exploration	liquid or tskit
Presentations (projector)	tskit (dark)
Publication figures	paper
Animations/videos	tskit (dark backgrounds hide edges nicely)

Note: The grayscale theme also works in 3D but may be harder to read without color contrast to distinguish depth.

Custom Colors

You can override specific colors from any theme using the color parameters in argscape.visualize(). This is useful when you want to use a theme’s overall style but change a few colors to match your preferences or publication requirements.

# 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,
    show_mutations=True,
    sample_order="dagre",
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x14d305150>

# Dark theme with custom accent colors
viz = argscape.visualize(
    ts,
    theme="tskit",
    sample_color="#ffd166",    # Gold samples
    mutation_color="#06d6a0",  # Teal mutations
    show_sample_ids=True,
    show_mutations=True,
    sample_order="dagre",
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x14d2e5a50>

Available Color Overrides

Parameter	Description
sample_color	Color for sample (leaf) nodes
internal_color	Color for internal nodes
root_color	Color for root nodes
edge_color	Color for edges
background_color	Background color
mutation_color	Color for mutation markers
text_color	Color for text labels

All colors should be specified as hex strings (e.g., "#ff0000" for red).

Advanced: Creating Custom Themes

For more control, use argscape.customize_theme() to create a reusable custom theme object. This is useful when you want to apply the same custom colors to multiple visualizations.

# Create a custom theme based on 'paper'
my_theme = argscape.customize_theme(
    "paper",
    sample_color="#2a9d8f",     # Teal samples
    internal_color="#e9c46a",   # Gold internal nodes
    root_color="#e76f51",       # Coral root nodes
    edge_color="#264653",       # Dark teal edges
    mutation_color="#f4a261",   # Orange mutations
)

# View the custom theme's palette
show_palette("custom", my_theme)

# Use the custom theme - pass it as a dict via theme parameter workaround
# Note: For now, use the inline color parameters shown above
# The customize_theme() function is useful for inspecting/planning color schemes

viz = argscape.visualize(
    ts,
    theme="paper",
    sample_color="#2a9d8f",
    internal_color="#e9c46a",
    root_color="#e76f51",
    edge_color="#264653",
    mutation_color="#f4a261",
    show_sample_ids=True,
    show_mutations=True,
    sample_order="dagre",
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x14d2e6f50>

Theme Selection Guide

Use Case	Recommended Theme
Interactive exploration	liquid
Jupyter notebooks	liquid or tskit
Dark-background presentations	tskit
Journal figures (color)	paper
Journal figures (B&W)	grayscale
Posters	paper
Web embedding	liquid
Custom branding	Any + color overrides

Accessing Theme Details Programmatically

You can inspect theme colors in your code.

# List available themes
print("Available themes:", argscape.list_themes())

# Get theme details
theme = argscape.get_theme("paper")
print(f"\nTheme: {theme.name}")
print(f"Background: {theme.background}")
print(f"Sample nodes: {theme.nodes.sample}")
print(f"Internal nodes: {theme.nodes.internal}")
print(f"Root nodes: {theme.nodes.root}")
print(f"Edges: {theme.edges.default}")
print(f"Mutations: {theme.mutation}")

Available themes: ['tskit', 'liquid', 'grayscale', 'paper']

Theme: paper
Background: #ffffff
Sample nodes: #2563eb
Internal nodes: #6b7280
Root nodes: #dc2626
Edges: #374151
Mutations: #ea580c

Tips for Publication Figures

1. Use grayscale or paper - designed for print

2. Use sample_order="dagre" - minimizes edge crossings for cleaner layouts

3. Increase DPI - use 300+ for publication quality

4. Consider PDF export - vector format scales perfectly

5. Test print preview - colors may look different in print

6. Check journal guidelines - some require specific formats

7. Use custom colors - match your paper’s color scheme or institution branding

Next Steps

• First Visualization - All visualization options

• Exporting Visualizations - Export settings for different use cases

• 3D Spatial Visualization - Themes in 3D visualizations