Library for the Development and Use of Phylogenetic Network Methods
SNP (biallelic marker) likelihood computation for phylogenetic networks, with optional GPU acceleration.
Raised when the SNP likelihood computation would exceed available hardware resources (GPU VRAM or system RAM).
Hardware specs for the user's GPU (detected at import time).
VRAM capacity in gigabytes (converted from :attr:`vram_bytes`).
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,)``.
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)
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).
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.
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. |
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 ...
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``. |
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. |
return the dimension of the Q matrix
Retrieve the Q matrix.
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.
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. |
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 the partial likelihoods at an internal node.
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 the partial likelihoods at the root node.
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.
Drives a :class:`SNPStrategy` over the SNP model graph, threading each node's partial-likelihood result up to its parent.
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. |
Compute and record the leaf partial likelihood for ``n``.
Combine both children's partials at internal node ``n`` and record the result.
Split the child partial across both parent interfaces of reticulation ``n``.
Combine both children's partials at the root ``n`` and record the result.
Fold the child partial into the final log-likelihood at aggregator ``n``.
Dispatch to the correct visit method based on node type.
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 |
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) |
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 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. |
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. |
Get or build a cached sparse merge tensor.
Get or build a cached sparse split tensor.
Get or build a GPU-resident cached sparse merge tensor.
Get or build a GPU-resident cached sparse split tensor.
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. |