HapNet: a new Python package for automated population-aware haplotype network analysis and visualization

This paper introduces HapNet, an open-source Python package that automates the construction, visualization, and statistical summarization of population-aware haplotype networks from aligned FASTA files, offering a reproducible and scriptable alternative to existing interactive graphical tools.

The Gist

Imagine you are trying to figure out how a group of friends are related to each other, but instead of looking at family trees, you are looking at their DNA. Scientists often use something called a haplotype network to do this. Think of a haplotype network like a subway map. Each station on the map is a unique DNA version (a "haplotype"), and the tracks connecting them show how many tiny genetic "steps" or mutations separate them.

For a long time, making these subway maps has been like drawing them by hand on a whiteboard. You have to click buttons, drag lines, and manually color-code which friend belongs to which city. It's slow, hard to repeat exactly the same way twice, and if you have thousands of friends (DNA samples), your hand would get tired.

Enter HapNet, a new digital tool created by Andrew Davinack. Here is how it works, explained simply:

1. The Magic Input: The "Name Tag" Trick

Usually, to make these maps, you need a separate spreadsheet telling the computer which DNA sample came from which population (like "New York" or "South Africa"). HapNet is clever: it doesn't need a separate spreadsheet.

It just looks at the name tags on the DNA files. If you name your file Polydora_01_Nantucket, HapNet automatically knows, "Ah, this one is from Nantucket!" It reads the last part of the name, sorts everyone into their groups, and gets to work. It's like a bouncer at a club who instantly knows which VIP section a guest belongs to just by reading the last word on their wristband.

2. The Engine: The "Shortest Path" Algorithm

Once HapNet has the data, it acts like a super-fast GPS.

• Step 1: It groups identical DNA sequences together (like grouping all the people who have the exact same blue shirt).
• Step 2: It measures the genetic distance between these groups (counting the "steps" of mutation).
• Step 3: It draws the most efficient map possible (a "minimum spanning tree") to connect everyone with the fewest steps.

3. The Visuals: The "Pie Chart" Stations

The result is a beautiful, publication-ready map.

• The Circles: Each circle is a unique DNA group. The bigger the circle, the more people share that specific DNA.
• The Colors: If a circle is all one color, it means everyone in that group is from the same place (a "private" group). If the circle looks like a pie chart with different colored slices, it means that specific DNA group is shared by people from different places (like a group of friends who all moved to different cities but still share the same DNA).
• The Lines: The lines connecting the circles have little tick marks on them. These are the "mutation steps," showing how many genetic changes happened to get from one group to another.

4. Why It Matters: The "Polydora" Worm Story

The author tested HapNet on a tiny worm called Polydora neocaeca that bores into shellfish. They had worms from Nantucket, New York, Rhode Island, and South Africa.

• What they found: Most worms had their own unique DNA groups. However, they found one specific DNA group (H1) that was shared between Rhode Island and Nantucket. This is like finding a specific family heirloom in two different houses, proving those two groups of worms have been mixing or traveling between those locations.
• The South African Surprise: The South African worms were so genetically different that they were separated from the American worms by many "steps" on the map, showing they are quite distant cousins.

5. The Best Part: It's a Robot, Not a Human

The biggest advantage of HapNet is that it's automated.

• Reproducibility: If you run the same code twice, you get the exact same map every time. No more "oops, I clicked the wrong button."
• Data Export: It doesn't just draw a pretty picture; it also spits out a spreadsheet (a "log file") with all the numbers. This lets other scientists take that data and run their own math on it without having to manually count the dots on the picture.

In a nutshell:
HapNet is like a smart, automated artist that takes a messy pile of DNA files, reads the name tags to sort them by location, draws the most logical family tree connecting them, and hands you both a beautiful poster and a detailed spreadsheet. It turns a tedious, manual art project into a quick, repeatable science experiment.

Technical Summary

1. Problem Statement

Haplotype networks are essential tools in population genetics and phylogeography for visualizing genealogical relationships, inferring population structure, and understanding demographic history. However, existing software solutions (e.g., TCS, PopART) suffer from significant limitations:

• Lack of Automation: They rely primarily on interactive graphical user interfaces (GUIs), making it difficult to automate analyses or integrate them into modern, scripted bioinformatic pipelines.
• Reproducibility Issues: The manual nature of GUI-based workflows hinders reproducibility and scalability, especially as genetic datasets grow in size and complexity.
• Population Metadata Handling: Many tools require manual assignment of individuals to populations within the interface, introducing potential for human error and limiting the ability to handle large-scale population metadata efficiently.
• Language Fragmentation: While R packages (e.g., pegas) exist for network inference, they often require custom scripting to generate population-aware visualizations, lacking a unified, end-user workflow.

2. Methodology

HapNet is introduced as a lightweight, open-source Python package designed to address these gaps. Its technical workflow operates as follows:

• Input Format: The software accepts a single aligned FASTA file. Population identity is encoded directly within the sequence headers using an underscore-delimited suffix (e.g., SampleID_PopulationCode). This eliminates the need for auxiliary metadata files.
• Haplotype Definition: Sequences are read and grouped by identical nucleotide strings to define unique haplotypes. Each haplotype tracks the list of contributing individuals and their associated populations.
• Network Construction:
  • Distance Calculation: Pairwise Hamming distances are computed between all unique haplotypes across the aligned sequences.
  • Graph Construction: A complete weighted graph is built based on these distances.
  • Algorithm: A Minimum Spanning Tree (MST) is inferred from the graph to create a parsimonious network connecting all haplotypes.
• Visualization:
  • The network is laid out using a force-directed algorithm.
  • Node Sizing: Node areas are proportional to haplotype frequency (number of individuals).
  • Population Representation: Shared haplotypes are visualized as pie charts, with sectors colored by population. Private haplotypes are colored by their single population.
  • Edge Details: Mutational steps between haplotypes are displayed as tick marks on the edges.
• Output Generation: In addition to publication-ready graphics (PNG, PDF, SVG), HapNet generates machine-readable tab-delimited (.tsv) log files containing haplotype sequences, individual assignments, population compositions, and summary statistics.

3. Key Contributions

• First Python-Native Automated Solution: HapNet is the first Python package specifically designed for fully automated, end-to-end population-aware haplotype network construction and visualization.
• Workflow Integration: It enables command-line execution, allowing seamless integration into larger bioinformatic pipelines and ensuring high reproducibility.
• Metadata Efficiency: By parsing population data directly from FASTA headers, it streamlines the input process and removes the need for manual population assignment.
• Dual Output: It provides both high-quality visualizations for publication and structured tabular data for downstream statistical analysis, bridging the gap between visualization and quantitative analysis.
• Accessibility: The package is freely available via PyPI and GitHub, with dependencies (Biopython, NumPy, SciPy, NetworkX, Matplotlib) handled automatically.

4. Results (Empirical Example)

The utility of HapNet was demonstrated using mitochondrial COI sequences from the shell-boring polychaete worm Polydora neocaeca.

• Dataset: 18 samples from four locations: Nantucket Island (N=8), New York (N=1), Rhode Island (N=3), and South Africa (N=6).
• Findings:
  • The software identified 8 unique haplotypes.
  • Haplotype H1 was identified as shared between Rhode Island and Nantucket populations.
  • Haplotypes H2 and H8 were exclusive to South African samples and were separated from the North American network by multiple mutational steps, indicating significant genetic divergence.
  • Classification Logic: The software correctly classified H2 as "private" to South Africa despite being present in multiple individuals there, demonstrating its ability to distinguish between within-population frequency and cross-population sharing.
• Output: The analysis produced a clear network visualization showing population connectivity and generated four tables summarizing haplotype composition, frequency, and geographic distribution.

5. Significance

HapNet represents a significant step forward in the standardization of population genetic analysis. By shifting haplotype network construction from interactive GUIs to a scriptable, command-line Python environment, it:

• Enhances Reproducibility: Researchers can now document and rerun network analyses exactly as performed, a critical requirement for modern scientific rigor.
• Improves Scalability: The automated nature of the tool allows for the processing of larger datasets that would be tedious or error-prone in manual interfaces.
• Facilitates Interoperability: Being Python-native, it fits naturally into the growing ecosystem of Python-based bioinformatics tools, allowing for easier data sharing and integration with other statistical workflows.
• Democratizes Advanced Analysis: By providing a free, open-source tool with clear documentation, it lowers the barrier to entry for researchers needing population-aware network visualizations without requiring advanced programming skills beyond basic command-line usage.