tskit_arg_visualizer : interactive plotting of ancestral recombination graphs

James Kitchens, Yan Wong · 2025

Read tskit_arg_visualizer : interactive plotting of ancestral recombination graphs by James Kitchens, Yan Wong (2025) in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/arxiv-2508-03958.txt.

Introduction

James Kitchens and Yan Wong introduce, in a 2025 software paper, a tool for drawing ancestral recombination graphs. Such graphs capture the full family history of recombining DNA, and they sit at the heart of population genetics. Their Python package draws the graphs interactively, so a researcher can explore one by hand. The authors show it at work in teaching and in picking through graphs inferred from real data.

Catalog record

CREATORJames Kitchens, Yan Wong
YEAR2025
COLLECTIONPAPERS
FORMATTXT
FILE SIZE12 KB
VERSION1.0
LICENSEhttp://creativecommons.org/licenses/by/4.0/
RIGHTSCC BY
SOURCEarXiv

Source: https://arxiv.org/abs/2508-03958

Browse the full library · About the Tower of Babel

Full text

The opening of the work, from the library's hosted text:

tskit_arg_visualizer : interactive plotting of ancestral recombination graphs James Kitchens, Yan Wong Abstract Abstract Summary: Ancestral recombination graphs (ARGs) are a complete representation of the genetic relationships between recombining lineages and are of central importance in population genetics. Recent breakthroughs in simulation and inference methods have led to a surge of interest in ARGs. However, understanding how best to take advantage of the graphical structure of ARGs remains an open question for researchers. Here, we introduce tskit_arg_visualizer , a Python package for programmatically drawing ARGs using the interactive D3.js visualization library. We highlight the usefulness of this visualization tool for both teaching ARG concepts and exploring ARGs inferred from empirical datasets. Availability and implementation: The latest stable version of tskit_arg_visualizer is available through the Python Package Index ( https://pypi.org/project/tskit-arg-visualizer , currently v0.1.0). Documentation and the development version of the package are found on GitHub ( https://github.com/kitchensjn/tskit_arg_visualizer ). Supplementary materials: Methods for creating the example ARGs seen in Figure 1 can be found in the supplementary materials. Contact: [email protected] 1 Introduction At each position in the genome, genetic relationships between sampled genomes can be described by an evolutionary (or “gene”) tree. During meiosis, recombination generates mosaic chromosomes by bringing together regions with distinct inheritance histories, such that many different local trees can exist along the chromosome. However, neighboring local trees are usually highly correlated, sharing the majority of their nodes and edges in common [ 6 , 14 ] . An “ancestral recombination graph” (ARG), first coined by Griffiths [ 4 ] , describes the set of local trees for a genomic region woven together into a graphical structure based on their shared branches (for a more complete definition of ARGs, see [ 8 ] and [ 25 ] ). ARGs capture the observable patterns of inheritance that underlie the genetic diversity of the samples [ 16 ] , making them an extremely data-rich object for genetic studies [ 15 ] . Thanks to major advances in ARG inference methods, ARG-based analyses can now be applied to many different empirical systems [ 19 , 20 , 11 , 10 , 27 , 1 ] . Coupled with the development of associated statistical methods, ARGs are currently being used to investigate a broad range of population genetics questions, including recognizing recombinant lineages [ 10 , 26 ] , identifying selected loci [ 21 , 23 ] , and reconstructing complex demographic histories [ 3 ] . With this growth in interest [ 12 ] , there is a pressing need for tools that support ARG research and lower the barrier of entry into this field. Visualization is critically important for teasing apart and communicating the complex relationships encoded in an ARG. This is often done by plotting local trees along a genome, regularly focusing on individual trees at loci of interest (e.g. [ 7 ] ), or emphasizing the correlation between trees using colors or additional lines (e.g. [ 18 ] ). However, this tree-based approach necessarily obscures how these trees fit into the larger ARG. Alternatively, as an ARG is a form of directed acyclic graph, the graph structure itself can be visualized. For example, classical depictions generally show a network of nodes organized by time, linked by vertical and horizontal edges, with the root at the top and samples at the bottom [ 4 , 5 , 24 ] . Although useful with small, hand-built examples [ 19 , 12 ] , the resulting visualization can be confusingly tangled and hard to interpret for larger empirical ARGs which often reflect highly reticulated ancestries. Moreover, this visualization strategy can make it hard to focus on specific genomic loci of interest, as local trees are more difficult to discern amid the larger structure of the graph. Here, we present tskit_arg_visualizer , a graph-based visualizer which addresses the problems of tangling and local tree representation using modern software techniques. Force-directed simulation is used to untangle the graph, and interactive highlighting is used to reveal both local trees and the extent of genome regions spanned by edges and their associated mutations. In doing so, the visualizer draws the full ancestral structure, while simultaneously allowing the user to explore genetic relationships within local genomic regions. tskit_arg_visualizer adds to a growing list of tools aimed at teasing apart these data-rich graphs. 2 Results 2.1 Implementation tskit_arg_visualizer is a Python package that leverages the D3.js visualization library to draw interactive ARGs in a browser based environment. When run from the command-line, this package launches a browser window; alternatively, plotting is possible directly inside a Jupyter Notebook. Figures can also be drawn inside Quarto presentations, providing interactivity when teaching about ARGs in a class or workshop setting. 2.2 Model As the name suggests, tskit_arg_visualizer is designed to easily integrate into the tskit ecosystem of packages, and provides functions to convert from a tskit.TreeSequence in a manner that scales to millions of nodes and edges (as was required for Figure 1C). This package represents an ARG as a collection of tables for nodes, edges, mutations, and breakpoints, altogether referred to as a D3ARG . This mirrors the tskit tree sequence tabular format but with a focus on efficiency of visualization rather than efficiency of storage. For example, in addition to graph specific details such as node times and connections, tables contain styling information used to customize the visualization. Another key difference is that an edge in a D3ARG can contain disjoint chromosomal intervals, whereas a tskit tree sequence stores a separate edge per interval. Additionally, tables can be manually built without tskit by using the pandas Python package [ 22 ] or importing from a previously saved JSON file. 2.3 Visualizations tskit_arg_visualizer offers two methods for viewing an ARG: • draw() : displays the full graph to the screen (Figures 1A and 1B) • draw_node() : useful for larger ARGs, first filters to a subgraph around a focal node before displaying (Figure 1C) These can be combined with two edge-drawing stylizations. The conventional “orthogonal” format, shown in Figure 1B, connects parent and child nodes via vertical and horizontal lines. It is particularly suitable for “full ARGs” [ 25 ] with marked recombination nodes and where common ancestor nodes have a maximum of 2 children. The more flexible “line” stylization, shown in Figure 1C, connects each parent to its child via a straight line, which better accommodates ARGs containing nodes with many direct connections. In all cases, a customized force-directed simulation is used to untangle graph edges [ 2 ] . Force-directed simulations balance a combination of “forces” to position nodes in a visually interpretable way – often where nodes repel one another but are held together by edges in the graph that act as springs. A major advantage of this algorithm is that it can limit the number of crossed lines without the need for scenario specific rules or knowledge of the graph’s shape. As the y-axis position of a node corresponds with its age, we fix this value and only allow the node’s x-axis position to be updated by the simulation. Force-directed simulations are likely to settle into local optima rather than finding the true minimum number of crossed lines, so the visualizer also allows nodes to be

Read the complete text