PhyNetPy Documentation

Library for the Development and Use of Phylogenetic Network Methods

PopulationGenetics Module v1.0.0

Validated population allele-count data and pulse-admixture graph semantics.

Author:
Mark Kessler
Source:
PopulationGenetics.py

Exceptions

exception PopulationGeneticsError(ValueError)

Raised when population-genetic data or graph semantics are invalid.

PopulationData

class PopulationData

Biallelic allele counts arranged as populations by sites. The numerator and denominator are stored separately. This avoids treating missing genotypes as reference alleles and supports different sample sizes among populations and sites. A callable count of zero denotes a missing population/site observation. This is an analysis container, not a ``phynetpy.data.Data`` inference-axis type; :func:`phynetpy.infer.infer` and :func:`phynetpy.infer.score` do not consume it.

Properties

populations -> tuple[str, ...] property

Population labels in matrix-row order.

sites -> tuple[str, ...] | None property

Site labels in matrix-column order, if supplied.

n_populations -> int property

Number of populations.

n_sites -> int property

Number of sites.

alternate_allele_counts -> np.ndarray property

Read-only population-by-site alternate-allele counts.

called_allele_counts -> np.ndarray property

Read-only population-by-site callable-allele counts.

Constructor

__init__(alternate_allele_counts: Any, called_allele_counts: Any, populations: Sequence[str], sites: Sequence[str] | None = None) -> None

Create a population-by-site allele-count table.

Parameter Type Description
alternate_allele_counts Two-dimensional nonnegative integer counts.
called_allele_counts Matching counts of callable gene copies.
populations Unique population labels, one per matrix row.
sites Optional unique site labels, one per matrix column.
Raises: PopulationGeneticsError: If dimensions, labels, or counts are inconsistent.

Methods

allele_frequencies(population: str | None = None) -> np.ndarray

Calculate alternate-allele frequencies without imputing missing data.

Parameter Type Description
population Optional population label. If omitted, return the full population-by-site matrix.
Returns: A floating-point array. Entries with no called alleles are ``NaN``.
Raises: PopulationGeneticsError: If *population* is unknown.
from_genotypes(genotypes: Any, samples: Sequence[str], population_members: Mapping[str, Sequence[str]], ploidy: int | Sequence[int] = 2, sites: Sequence[str] | None = None) -> PopulationData @classmethod

Aggregate a sample-by-site matrix into population allele counts. Genotypes are alternate-allele copy counts. ``None``, ``NaN``, ``"."``, ``"?"``, ``"-"``, ``"./."``, and ``".|."`` are treated as missing. Every sample must belong to exactly one population.

Parameter Type Description
genotypes Two-dimensional sample-by-site genotype-count matrix.
samples Unique sample labels in matrix-row order.
population_members Population label -> member sample labels.
ploidy Positive ploidy shared by all samples, or one value per sample.
sites Optional site labels.
Returns: Aggregated: class:`PopulationData`.
Raises: PopulationGeneticsError: If genotypes, ploidy, or membership are malformed.
from_biallelic_markers(markers: Any, called_alleles: int | Mapping[str, int] | None = None) -> PopulationData @classmethod

Aggregate PhyNetPy biallelic-marker rows by their population mapping. The marker object's species-to-allele mapping supplies population membership. Callable gene-copy counts must be supplied explicitly: ``BiallelicMarkers`` defaults its ``samples`` values to one even when a VCF row contains diploid genotype dosages, so that default is not a reliable denominator.

Parameter Type Description
markers A :class:`phynetpy.data.BiallelicMarkers` object.
called_alleles A positive count shared by all marker rows, or a row-label -> count mapping. Pass ``markers.samples`` explicitly when those values are known to have been supplied correctly.
Returns: Aggregated: class:`PopulationData`.
Raises: PopulationGeneticsError: If *markers* is the wrong type or callable-copy counts are absent or incomplete.
__repr__ -> str

AdmixtureGraph

class AdmixtureGraph

Validated pulse-admixture topology and proportions over a ``Network``. ``Network``, ``Node``, and ``Edge`` remain the graph implementation. This wrapper adds only population-genetic invariants: * one rooted directed acyclic component; * nodes with multiple parents are explicitly marked as reticulations; * their incoming inheritance proportions are strictly between zero and one and sum to one. The wrapper intentionally does not interpret ``Edge.length``. PhyNetPy networks currently carry sequence or coalescent units, while classical allele-frequency admixture graphs use genetic-drift lengths. Conflating those quantities would be scientifically incorrect. Divergence nodes may be unary or multifurcating, and admixture may involve more than two sources. Thus the wrapper does not impose the bin...

Properties

network -> Network property

The wrapped graph. Call :meth:`validate` after mutating it.

root -> Node property

The unique ancestral root.

terminal_populations -> tuple[Node, ...] property

Terminal population nodes in deterministic label order.

admixture_nodes -> tuple[Node, ...] property

Nodes with ancestry from two or more parent populations.

Constructor

__init__(network: Network, tolerance: float = 1e-08) -> None

Attach admixture-graph semantics to an existing network.

Parameter Type Description
network The directed graph to validate and wrap.
tolerance Absolute tolerance for inheritance proportions summing to one and for recognizing an unused zero gamma.
Raises: PopulationGeneticsError: If the graph is not a valid admixture history.

Methods

admixture_proportions(node: Node | str) -> dict[str, float]

Map each parent population to its contribution at an admixture node.

Parameter Type Description
node An admixture node or its label.
Returns: Parent label -> inheritance proportion, sorted by parent label.
Raises: PopulationGeneticsError: If the node is absent or is not an admixture node.
validate -> None

Validate topology, reticulation flags, and inheritance proportions.

Raises: PopulationGeneticsError: At the first violated invariant.
__repr__ -> str

Navigation

Modules

This Page