hapnet: installation guide and use

What Hapnet does

Hapnet builds a population-aware haplotype network from an aligned FASTA file. It produces: 

• a publication-ready network figure (PNG/PDF/SVG).

• TSV logs including haplotype definitions, sequence-to-haplotype membership, shared haplotypes, and a summary.

Requirements

• Python 3.9+

• An aligned FASTA file (all sequences same length)

​

Quick start (most users)

1. Open Terminal (macOS/Linux) or PowerShell (Windows)

2. Create a fresh environment and install: 
   
   MacOS/Linux
   pip install hapnet 
   
   Windows (Powershell)
   pip install hapnet
    

3. Run Hapnet on your aligned FASTA: 
   hapnet your_alignment.fasta --out network.png --log-prefix run1
    

Outputs will be written to your current folder (or wherever you specify).

​

Input FASTA format (important)

1) Sequences must be aligned.

All sequences must be the same length (e.g., output from MAFFT, MUSCLE, Clustal, etc.)

2) Population must be the last underscore-delimited token

Hapnet parses population identity from the final underscore-delimited token in each FASTA header.

Examples:

>Ind1_Pop1
>Ind2_Pop2

>Ind3_Pop2

​

More complex headers are fine as long as population is last:

​

>Ind7_Site1_2019_Pop3
>MN605578_Pneocaeca_rI

​

In these examples, the populations are interpreted as Pop1, Pop2, Pop3, RI.

​

Command-line options

​

hapnet input.fasta --out network.png --log-prefix run1

​

--out can be network.png, network.pdf, or network.svg

--log-prefix sets the prefix for output TSV files (e.g., run1_*)

​

Output files explained

​

If you run:

​

hapnet input.fasta --out network.png --log-prefix run1

​

You will get:

​

1. network.png (the haplotype. network figure (nodes sized by frequency; shared haplotypes shown as population pie charts; mutation tick marks on edges)

​

2. run1_haplotypes.tsv (one row per haplotype - haplotype ID, sequence, total count, etc.)

​

3. run1_membership.tsv (maps each input sequence header to its haplotype ID)

​

4. run1_summary.tsv (summary statistics e.g. total haplotypes, number private/shared, etc.)

​

​

​

Recommended Workflow for Real Data Sets

​

1. Align sequences (MAFFT/MUSCLE/etc.).

2. Ensure headers end with _PopulationLabel.

3. Run hapnet.

4.  Use the TSV logs for downstream analysis, QC, and manuscript tables.

​

​

​

Troubleshooting

​

"command not found: hapnet"

​

You likely forgot to activate the environment or you installed into a different environment than the one you're using

​

"Sequences are not the same length"

​

Your FASTA is not aligned or contains sequences with gaps/missing ends: realign and/or trim to equal length.

​

"My populations are wrong"

​

hapnet uses the final underscore token. If your header ends in _2019 or _COI then hapnet will treat that as population. FIx by renaming headers so population is last. 

​

"Plot is crowded/nodes overlap"

​

Dense networks can become hard to visualize when there are many haplotypes. The TSV logs remain correct even if the figure is crowded; consider plotting subsets or summarizing. 

​

​

Citation

​

If you do plan to use this in your analysis and to publish it, please cite as follows:

​

Davinack, A.A. (2026). hapnet: Population-aware haplotype networks in Python (v0.1.0). https://pypi.org/project/hapnet 

​

​

​