PhyNetPy Documentation

Library for the Development and Use of Phylogenetic Network Methods

PhyNetPy API Reference

Welcome to the PhyNetPy documentation. PhyNetPy is a comprehensive Python library for phylogenetic network analysis, providing tools for network construction, manipulation, simulation, and inference.

Version:
0.7.0
Authors:
Mark Kessler, Luay Nakhleh
Copyright:
2025

Module Index

Module Description
Alphabet Character-to-state mapping for biological sequence data (DNA, RNA, Protein, Codon, SNP).
BiMarkers SNP (biallelic marker) likelihood computation for phylogenetic networks, with optional GPU acceleration.
BirthDeath Birth-death process network simulators (Yule and CBDP models).
GTR Time-reversible nucleotide substitution models (GTR, JC, K80, F81, HKY, K81, SYM, TN93).
GeneTrees Gene tree container and analysis utilities including consensus tree construction and concordance factors.
GraphUtils Network decomposition, distances, and structural edits: blobs, tree-of-blobs, displayed trees, cluster/mu/tripartition distances, hybrid-ancestry error, reticulation-aware comparison, and ASCII rendering.
IO Central I/O hub for reading and writing phylogenetic file formats (FASTA, VCF, Newick, Nexus).
JointDissimilarity The joint reticulation-and-tree dissimilarity of two rooted networks: a minimum-cost matching of reticulation tripartitions plus a dissimilarity of the reticulation-free remainders, under leaf, cluster, or Nakhleh structure comparison.
MSA Multiple Sequence Alignment parsing, storage, grouping, and distance computation.
Matrix Data matrix storage and reduction for sequence alignments with unique site pattern compression.
MetropolisHastings Hill-climbing and simulated-annealing search drivers, plus the ProposalKernel interface.
ModelGraph The Model container pairing a network with its likelihood calculator, plus dirty-state tracking for incremental rescoring.
ModelMove Network topology move operations for MCMC search (add/remove/flip reticulation, SPR).
ModelSelection Information-criterion-based reticulation-count selection (AIC, BIC, AICc) and reticulation sweep helpers.
Network Core phylogenetic network data structures: Node, Edge, Branch, and Network classes.
Newick Newick format label extraction and Nexus file generation utilities.
PopulationGenetics Validated population allele-count data and pulse-admixture graph semantics.
ReticulationComparison Reticulation-aware network comparison: tripartition matching, Nakhleh metric, and precision/recall over reticulations.
SNPSimulator SNP data simulator for phylogenetic networks using a forward-in-time 2-state CTMC.
State State management for MCMC accept/reject decisions with model validation.
Validation Comprehensive file format validation for phylogenetic data files (Newick, Nexus, FASTA, PHYLIP, etc.).
criteria Axis 3 -- the statistical objective: MDC, Likelihood, PseudoLikelihood, and Bayesian, which wraps one of the likelihoods rather than sitting parallel to them.
data Axis 1 -- what you observed: GeneTrees, Alignment, BiallelicMarkers. The input knows its own type, which is half of the dispatch key.
infer The public inference API: the verbs infer, score, and simulate, the InferenceResult they return, infer_dimple for divide-and-conquer on a tree of blobs, plus the registry, scorers, kernels, result types, and MCMC diagnostics around them.
models Axis 2 -- the generative biology: MSC (diploid, ILS only) and Allopolyploid (whole-genome duplication).

Getting Started

Installation

pip install phynetpy

Quick Example

from phynetpy import read_newick

# Parse a network from a Newick string
network = read_newick("((A:0.1,B:0.2):0.3,C:0.4);")[0]

# Access network properties
print(f"Number of nodes: {len(network.V())}")
print(f"Number of edges: {len(network.E())}")
print(f"Leaves: {[leaf.label for leaf in network.get_leaves()]}")

Module Categories

Core Data Structures

  • Alphabet - Character-to-state mapping for biological sequence data (DNA, RNA, Protein, Codon, SNP).
  • MSA - Multiple Sequence Alignment parsing, storage, grouping, and distance computation.
  • Matrix - Data matrix storage and reduction for sequence alignments with unique site pattern compression.
  • Network - Core phylogenetic network data structures: Node, Edge, Branch, and Network classes.
  • PopulationGenetics - Validated population allele-count data and pulse-admixture graph semantics.

Models

  • GTR - Time-reversible nucleotide substitution models (GTR, JC, K80, F81, HKY, K81, SYM, TN93).

Simulation

  • BirthDeath - Birth-death process network simulators (Yule and CBDP models).
  • SNPSimulator - SNP data simulator for phylogenetic networks using a forward-in-time 2-state CTMC.

Inference

  • BiMarkers - SNP (biallelic marker) likelihood computation for phylogenetic networks, with optional GPU acceleration.
  • MetropolisHastings - Hill-climbing and simulated-annealing search drivers, plus the ProposalKernel interface.
  • ModelMove - Network topology move operations for MCMC search (add/remove/flip reticulation, SPR).
  • ModelSelection - Information-criterion-based reticulation-count selection (AIC, BIC, AICc) and reticulation sweep helpers.
  • State - State management for MCMC accept/reject decisions with model validation.
  • criteria - Axis 3 -- the statistical objective: MDC, Likelihood, PseudoLikelihood, and Bayesian, which wraps one of the likelihoods rather than sitting parallel to them.
  • data - Axis 1 -- what you observed: GeneTrees, Alignment, BiallelicMarkers. The input knows its own type, which is half of the dispatch key.
  • infer - The public inference API: the verbs infer, score, and simulate, the InferenceResult they return, infer_dimple for divide-and-conquer on a tree of blobs, plus the registry, scorers, kernels, result types, and MCMC diagnostics around them.
  • models - Axis 2 -- the generative biology: MSC (diploid, ILS only) and Allopolyploid (whole-genome duplication).

Analysis

  • GeneTrees - Gene tree container and analysis utilities including consensus tree construction and concordance factors.
  • GraphUtils - Network decomposition, distances, and structural edits: blobs, tree-of-blobs, displayed trees, cluster/mu/tripartition distances, hybrid-ancestry error, reticulation-aware comparison, and ASCII rendering.
  • JointDissimilarity - The joint reticulation-and-tree dissimilarity of two rooted networks: a minimum-cost matching of reticulation tripartitions plus a dissimilarity of the reticulation-free remainders, under leaf, cluster, or Nakhleh structure comparison.
  • ReticulationComparison - Reticulation-aware network comparison: tripartition matching, Nakhleh metric, and precision/recall over reticulations.

I/O

  • IO - Central I/O hub for reading and writing phylogenetic file formats (FASTA, VCF, Newick, Nexus).
  • Newick - Newick format label extraction and Nexus file generation utilities.
  • Validation - Comprehensive file format validation for phylogenetic data files (Newick, Nexus, FASTA, PHYLIP, etc.).

Infrastructure

  • ModelGraph - The Model container pairing a network with its likelihood calculator, plus dirty-state tracking for incremental rescoring.

Navigation

Modules