PhyNetPy Documentation

Library for the Development and Use of Phylogenetic Network Methods

BiMarkers Module v1.0.0

SNP (biallelic marker) likelihood computation for phylogenetic networks, with optional GPU acceleration.

Author:
Mark Kessler
Last Edit:
5/12/26
Source:
BiMarkers.py

Constants

CUPY_RUNTIME_OK = False
GPU_SPECS = _detect_gpu()
GPU_THRESHOLD = {0: float('inf'), 1: 20, 2: 12, 3: 8}
GPU_VRAM_SAFETY_FACTOR = 0.8
VPI_WORKSPACE_MULTIPLIER = 3
GPU_MAX_SITE_BATCH = 1000

Exceptions

exception SNPResourceError(RuntimeError)

Raised when the SNP likelihood computation would exceed available hardware resources (GPU VRAM or system RAM).

GPUSpecs

class GPUSpecs

Hardware specs for the user's GPU (detected at import time).

Properties

vram_gb -> float property

VRAM capacity in gigabytes (converted from :attr:`vram_bytes`).

Methods

__repr__ -> str

NodeVPI

class NodeVPI

Partial-likelihood vector bundle carried by a model node. Attributes: tensor: Partial-likelihood array of shape ``(S, d1, d2, ...)``, where *S* is the number of sites and each subsequent axis corresponds to an interface. interfaces: Labels for each tensor axis beyond the site axis (length equals ``tensor.ndim - 1``). max_lineages: Maximum lineage count per interface. log_scale: Per-site log rescaling factors, shape ``(S,)``.

SparseMerge

class SparseMerge

Sparse COO representation of the merge tensor M[i, j, k]. For each non-zero entry: stores (i_arr[n], j_arr[n], k_arr[n], coeff_arr[n]). There is exactly one k for each (i, j) pair (since nz = nx + ny is unique). nnz = state_dim(mx) * state_dim(my) (one per valid (i,j) pair)

SparseSplit

class SparseSplit

Sparse COO representation of the split tensor S[i, j, k]. For each non-zero entry: stores (i_arr[n], j_arr[n], k_arr[n], coeff_arr[n]). Multiple (j, k) pairs map to each i (since n = nb + nd has many valid splits).

SNPScorer

class SNPScorer

Callable biallelic-marker log-posterior scorer for MCMC. Mirrors the interface of :class:`phynetpy._mcmc_gt.MCMCGTScorer` (``__call__(model) -> float`` plus a ``last_log_likelihood`` attribute) so it drops directly into the shared Metropolis-Hastings loop. Every call rebuilds the SNP model graph from ``model.network`` and the shared in-memory alignment, evaluates the Bryant biallelic likelihood via :func:`_snp_log_likelihood`, and (in posterior mode) adds the network prior. The alignment is parsed once and reused for the whole chain, so per iteration the only re-parsing cost is the (cheap) model-graph rebuild.

Constructor

__init__(aln: MSA, u: float, v: float, theta: float, samples: dict[str, int], priors: 'MCMC_GTPriors', posterior: bool = True) -> None

Create a new ``SNPScorer``.

Parameter Type Description
aln Biallelic-marker alignment shared across every call.
u Mutation rate red-to-green (1->0).
v Mutation rate green-to-red (0->1).
theta Population mutation rate ``4*N*mu``.
samples Per-taxon sample counts (number of alleles observed).
priors Network-prior hyperparameters used when ``posterior`` is ``True``.
posterior When ``True``, add the network prior to the likelihood so calls return a log-posterior; when ``False``, return the log-likelihood alone.

BiMarkersTransition

class BiMarkersTransition

Class that encodes the probabilities of transitioning from one (n,r) pair to another under a Biallelic model. Includes method for efficiently computing e^Qt Inputs: 1) n-- the total number of samples in the species tree 2) u-- the probability of going from the red allele to the green one 3) v-- the probability of going from the green allele to the red one 4) theta-- population mutation rate ``4*N*mu`` Assumption: Matrix indexes start with n=1, r=0, so Q[0][0] is Q(1,0);(1,0) Q Matrix is given by Equation 15 from: David Bryant, Remco Bouckaert, Joseph Felsenstein, Noah A. Rosenberg, Arindam RoyChoudhury, Inferring Species Trees Directly from Biallelic Genetic Markers: Bypassing Gene Trees in a Full Coalescent Analysis, Molecular Biology and Evolution, Volume 29, Issue 8, August 2012, Pages ...

Constructor

__init__(n: int, u: float, v: float, theta: float) -> None

Initialize the Q matrix

Parameter Type Description
n int sample count
u float Mutation rate from red to green.
v float Mutation rate from green to red.
theta float Population mutation rate ``4*N*mu``.

Methods

expt(t: float = 1) -> np.ndarray

Compute e^(Q*t) efficiently.

Parameter Type Description
t float time, generally in coalescent units. Optional, defaults to 1, in which case e^Q is computed.
Returns: np.ndarray: e^(Q*t).
cols -> int

return the dimension of the Q matrix

Returns: int: the number of columns in the Q matrix
getQ -> np.ndarray

Retrieve the Q matrix.

Returns: np.ndarray: The Q matrix.

SNPStrategy

class SNPStrategy

Per-node partial-likelihood computation for the SNP model. Supports both CPU (NumPy) and GPU (CuPy) execution. When use_gpu=True, all tensor operations run on the GPU via CuPy's drop-in NumPy API.

Constructor

__init__(q: BiMarkersTransition, u: float, v: float, theta: float, sites: int, max_samples: int, site_slice: tuple[int, int] | None = None, use_gpu: bool = False, branch_thetas: Optional[dict] = None) -> None

Create a new ``SNPStrategy``.

Parameter Type Description
q Transition-rate model for the 0/1 substitution process.
u Mutation rate red-to-green (1->0).
v Mutation rate green-to-red (0->1).
theta Default population mutation rate ``4*N*mu``.
sites Total number of sites in the alignment.
max_samples Maximum per-taxon sample count, used to size the per-node partial-likelihood vectors.
site_slice Optional ``(start, stop)`` restricting computation to a contiguous subrange of sites (for chunked/parallel evaluation). ``None`` uses all ``sites``.
use_gpu When ``True``, run tensor operations on the GPU via CuPy instead of NumPy.
branch_thetas Fixed branch-specific population mutation rates.

Methods

compute_at_leaf(n: LeafNode) -> NodeVPI

Compute the partial likelihoods at a leaf node. The format for the partial likelihoods is a two dimensional array where the first dimension (rows) is the site index and the second dimension (columns) is the number of samples for this leaf. Uses vectorized indexing for GPU efficiency (no Python per-site loop).

compute_at_internal(n: InternalNode, x: NodeVPI, y: NodeVPI) -> NodeVPI

Compute the partial likelihoods at an internal node.

compute_at_reticulation(n: ReticulationNode, x: NodeVPI) -> NodeVPI

Compute the partial likelihoods at a reticulation node. The split creates two new interfaces (one per parent branch). During the two transition steps, we use global per-site rescaling (axis-order agnostic) to prevent intermediate underflow. After both transitions, we do a final per-vector rescale. GPU-compatible via self.xp.

compute_at_root(n: RootNode, x: NodeVPI, y: NodeVPI) -> NodeVPI

Compute the partial likelihoods at the root node.

compute_at_aggregator(n: RootAggregatorNode, root: NodeVPI) -> None

Compute the partial likelihoods at a root aggregator node. Uses the accumulated per-vector log_scale factors to recover the true log-likelihood without numerical underflow. The root VPI should have shape (S, d) with log_scale shape (S,) after equalization at the root node. GPU-compatible: pi is built on CPU and transferred; final log-likelihood is brought back to CPU as a Python float.

SNPModelVisitor

class SNPModelVisitor

Drives a :class:`SNPStrategy` over the SNP model graph, threading each node's partial-likelihood result up to its parent.

Constructor

__init__(strategy: SNPStrategy) -> None

Create a new visitor driving ``strategy`` over the model graph.

Parameter Type Description
strategy Per-node partial-likelihood strategy to invoke at each visited node.

Methods

visit_leaf(n: LeafNode) -> None

Compute and record the leaf partial likelihood for ``n``.

visit_internal(n: InternalNode) -> None

Combine both children's partials at internal node ``n`` and record the result.

visit_reticulation(n: ReticulationNode) -> None

Split the child partial across both parent interfaces of reticulation ``n``.

visit_root(n: RootNode) -> None

Combine both children's partials at the root ``n`` and record the result.

visit_aggregator(n: RootAggregatorNode) -> None

Fold the child partial into the final log-likelihood at aggregator ``n``.

visit(n: ModelNode) -> None

Dispatch to the correct visit method based on node type.

Module Functions

n_to_index(n: int) -> int

Computes the starting index in computing a linear index for an (n,r) pair. Returns the index, if r is 0. The state space **includes the empty state** ``(0, 0)`` at index 0. This is required for the phylogenetic-network coalescent: at a reticulation the lineages entering the hybrid split binomially between the two parent branches, and the boundary cases where *all* lineages inherit from one parent leave the other branch with **zero** lineages. Omitting ``n = 0`` silently drops those terms, so every reticulation loses probability mass (the total site-pattern probability falls below 1 and becomes branch-length dependent). Including ``(0, 0)`` makes the split conserve probability. i.e n=0 returns 0, since (0,0) is index 0 i.e n=1 returns 1, since (1,0) is index 1 (preceded by (0,0)) i.e n=3 returns 6 since (3,0) is preceded by (0,0), (1,0), (1,1), (2,0), (2,1), and (2,2)

Parameter Type Description
n int an n value (number of lineages) from an (n,r) pair
Returns: int: starting index for that block of n values
nr_to_index(n: int, r: int) -> int

Takes an (n,r) pair and maps it to a 1d vector index (0,0) -> 0 (1,0) -> 1 (1,1) -> 2 (2,0) -> 3 ...

Parameter Type Description
n int the number of lineages (``0`` is the empty state)
r int the number of red lineages (<= n)
Returns: int: the index into the linear vector, that represents by (n, r)
state_dim(m: int) -> int

Return the state-space dimension for *m* lineages. The dimension equals the number of valid ``(n, r)`` pairs where ``0 <= n <= m`` and ``0 <= r <= n`` -- i.e. it includes the empty state ``(0, 0)``. For ``m`` this is ``(m + 1)(m + 2) / 2``.

build_sparse_merge(mx: int, my: int) -> SparseMerge

Build sparse COO merge tensor. ~50× less memory and dim_z × faster contraction than the dense version.

Parameter Type Description
mx Max lineages for the left interface.
my Max lineages for the right interface.
Returns: SparseMerge with coordinate arrays.
build_sparse_split(m: int, gamma: float) -> SparseSplit

Build sparse COO split tensor: ``S[i, j, k]`` where ``i`` is ``(n, r)``, ``j`` is ``(n_b, r_b)``, ``k`` is ``(n_d, r_d)``, and the coefficient is ``C(n, n_b) * gamma^{n_b} * (1-gamma)^{n_d}``. This is Rule 3 of the biallelic-network recursion (Zhu et al. 2018, PLOS Comp Biol e1005932; Rabier et al. 2021): the ``n`` lineages entering the hybrid partition into ``n_b`` inheriting from the branch-b parent and ``n_d = n - n_b`` from branch-d, with the ``C(n, n_b)`` ways of choosing which lineages go where and probability ``gamma^{n_b} (1-gamma)^{n_d}``. The coefficient does **not** depend on the red split ``(r_b, r_d)`` beyond the constraint ``r_b + r_d = r`` -- the hypergeometric merge (Rules 2/4) supplies the red-allele combinatorics, so applying it here too would double count. The boundary cases ``n_b = 0`` / ``n_b = n`` (all lineages inherit from a single parent, leaving the other branch empty) MUST be included; dropping them is what makes a tree-only engine lose probability on networks. ``n = 0`` is the empty state and splits to two empty states.

Parameter Type Description
m Max lineages at the node being split.
gamma Inheritance probability for the left parent branch.
Returns: SparseSplit with coordinate arrays.
get_sparse_merge(mx: int, my: int) -> SparseMerge

Get or build a cached sparse merge tensor.

get_sparse_split(m: int, gamma: float) -> SparseSplit

Get or build a cached sparse split tensor.

get_sparse_merge_gpu(mx: int, my: int) -> SparseMerge

Get or build a GPU-resident cached sparse merge tensor.

get_sparse_split_gpu(m: int, gamma: float) -> SparseSplit

Get or build a GPU-resident cached sparse split tensor.

deduplicate_vpis(vpis: list[NodeVPI]) -> list[NodeVPI]

Remove duplicates by identity (``is``), preserving order. Uses an ``id()``-based set for O(n) performance instead of O(n^2) linear scans.

Parameter Type Description
vpis list[NodeVPI] VPI objects, possibly with duplicate references.
Returns: list[NodeVPI]: De-duplicated list in original order.

Navigation

Modules

This Page