Focal Node Selection

Focal Node Selection#

This tutorial covers ARGscape’s focal node feature for exploring subARGs and ancestor relationships. Learn how to focus on specific nodes through the API or interactive clicks.

What Are Focal Nodes?#

When working with large ARGs, it’s often useful to focus on a specific node and its relationships. ARGscape provides two focal views:

  • SubARG View (focal_mode="subarg") - Shows a node and all its descendants (the subtree rooted at that node)

  • Ancestors View (focal_mode="ancestors") - Shows a node and all its ancestors (the path to the roots)

Both views simplify the visualization by filtering to only the relevant portion of the graph.

Setup#

Let’s load a tree sequence with spatial locations simulated in SLiM so we can demonstrate focal nodes in both 2D and 3D.

import tskit
import argscape

# Load tree sequence with spatial coordinates (simulated in SLiM)
ts = tskit.load("../data/population_remix_simplified.trees")

print(f"Samples: {ts.num_samples}")
print(f"Nodes: {ts.num_nodes}")
print(f"Trees: {ts.num_trees}")
print(f"Populations: {ts.num_populations}")

Samples: 60
Nodes: 118
Trees: 6
Populations: 4

Full ARG View#

First, let’s see the complete ARG to understand its structure.

# Full 2D view
viz = argscape.visualize(
    ts,
    sample_order="dagre",
    show_sample_ids=True,
    show_internal_ids=True
)
viz.display()

<argscape.visualize.VizResult at 0x10fd797f0>

SubARG View (Descendants)#

Use focal_node with focal_mode="subarg" to show a node and all its descendants. This is useful for examining the genealogy of a specific subset of samples.

internal_node = 103

# SubARG view in 2D
viz = argscape.visualize(
    ts,
    focal_node=internal_node,
    focal_mode="subarg",
    sample_order="dagre",
    show_sample_ids=True,
    show_internal_ids=True,
    height=600
)
viz.display()

<argscape.visualize.VizResult at 0x11a32a710>

# Same SubARG view in 3D
viz = argscape.visualize(
    ts,
    mode="spatial_3d",
    focal_node=internal_node,
    focal_mode="subarg",
    height=600
)
viz.display()

<argscape.visualize.VizResult at 0x10fc57b10>

Ancestors View#

Use focal_mode="ancestors" to show a node and all its ancestors. This traces a sample’s lineage back to the roots.

# Focus on a sample node and its ancestors
sample_node = 52

# Ancestors view in 2D
viz = argscape.visualize(
    ts,
    focal_node=sample_node,
    focal_mode="ancestors",
    sample_order="dagre",
    show_sample_ids=True,
    show_internal_ids=True,
    height=500,
    width=500
)
viz.display()

<argscape.visualize.VizResult at 0x11b0d1ba0>

# Same ancestors view in 3D
viz = argscape.visualize(
    ts,
    mode="spatial_3d",
    focal_node=sample_node,
    focal_mode="ancestors",
    width=800,
    height=700
)
viz.display()

<argscape.visualize.VizResult at 0x11b0d1940>

Interactive Selection#

In addition to the API, you can interactively select focal nodes using mouse clicks:

Action

Result

Left-click on node

SubARG view (node + descendants)

Right-click on node

Ancestors view (node + ancestors)

When in a focused view, a header appears showing the current mode and focal node. Click “Return to Full” to reset to the complete ARG.

Try it in the visualization below:

# Interactive visualization - try clicking nodes!
viz = argscape.visualize(
    ts,
    sample_order="dagre",
    show_sample_ids=True,
    show_internal_ids=True,
    width=900,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x11b111010>

Combining with Other Options#

Focal node selection works with all other visualization options like themes, filtering, and styling.

# Publication-ready focused view
viz = argscape.visualize(
    ts,
    focal_node=internal_node,
    focal_mode="subarg",
    theme="paper",
    sample_order="dagre",
    edge_opacity=0.8,
    edge_width=1.5,
    show_sample_ids=True,
    width=800,
    height=500
)
viz.display()

<argscape.visualize.VizResult at 0x11b21c160>

Exporting Focused Views#

Focused visualizations can be exported just like full ARG views.

# Export a focused view
viz = argscape.visualize(
    ts,
    focal_node=sample_node,
    focal_mode="ancestors",
    theme="paper",
    sample_order="dagre",
    show_sample_ids=True,
    width=800,
    height=600
)

# Uncomment to export:
# viz.export("ancestors_of_sample_5.pdf", dpi=300)

Next Steps#

On this page