PhyNetPy Documentation

Library for the Development and Use of Phylogenetic Network Methods

models Module v1.0.0

Axis 2 -- the generative biology: MSC (diploid, ILS only) and Allopolyploid (whole-genome duplication).

Author:
Mark Kessler
Source:
models.py

Exceptions

exception ModelSpecError(Exception)

Raised when a model is misconfigured for the data it is given.

Model

class Model(ABC)

Base class for a generative biological process. A model says what produced the data and therefore how to read the inferred network: under :class:`~phynetpy.models.MSC` a reticulation is a hybridization or introgression event between diploid lineages, while under :class:`~phynetpy.models.Allopolyploid` it is a polyploid formation event and the network is interpreted through its multiple-labelled (MUL) tree. Models are declarative parameter carriers, not engines. They hold the process parameters (population mutation rate, mutation rates, subgenome assignment) and are handed to the engine the registry selects; the numerical work lives in the engines. .. note:: Unrelated to :class:`phynetpy.ModelGraph.Model`, which is the probabilistic graphical model a search mutates. See the :mod:`phynetpy.m...

Methods

validate(data) -> None

Check this model against the data it will be run on. Called by the registry after dispatch succeeds, so a model may assume the (data, model, criterion) triple is legal and only needs to police its own parameters. The default accepts everything.

Parameter Type Description
data The :class:`~phynetpy.data.Data` the run will consume.
Raises: ModelSpecError: If the model cannot be applied to *data*.
__repr__ -> str

MSC

class MSC(Model)

The multispecies network coalescent: diploid lineages with ILS. The default model, and the one nearly every method in the field is built on. Gene copies coalesce within the branches of the species network at a rate set by the population mutation rate; at a reticulation, each lineage passes into one parent with probability given by that edge's inheritance probability (gamma). Incomplete lineage sorting therefore arises from the coalescent, and a reticulation means hybridization or introgression. The process parameters live here because they *are* the biology. The mutation rates ``u`` and ``v`` describe the biallelic transition model. ``theta`` is the population mutation rate ``4*N*mu`` for every MSC data type. Fixed branch-specific values may override it through ``branch_thetas``. Attribute...

Constructor

__init__(theta: Optional[float] = None, u: float = 1.0, v: float = 1.0, branch_thetas: Optional[Mapping[BranchThetaKey, float]] = None) -> None

Configure the multispecies network coalescent.

Parameter Type Description
theta Population mutation rate ``4*N*mu``. ``None`` defers to the engine (which samples it, for the Bayesian criterion).
u Red-to-green mutation rate (biallelic markers only).
v Green-to-red mutation rate (biallelic markers only).
branch_thetas Fixed per-population values. Stable ``(parent_label, child_label)`` keys identify edges; a child label identifies the branch above that node. Use ``("__root__", root_label)`` for the ancestral population.
Raises: ModelSpecError: If any rate is non-positive.

Methods

__repr__ -> str

Allopolyploid

class Allopolyploid(Model)

Allopolyploidy: networks read through their MUL tree. Models polyploid taxa whose subgenomes descend from distinct diploid progenitors (Hejase et al.; MP-Allop / Polyphest). A reticulation is a polyploid formation event, and the network is scored by expanding it into a multiple-labelled (MUL) tree in which each subgenome of a polyploid appears as its own tip. Because subgenome assignment -- which gene copies belong to which subgenome of which taxon -- is a statement about the biology of the taxa, it lives on the model rather than on the data. When omitted, it is derived from the data's own mapping. Attributes: subgenome_map: Subgenome / species -> list of gene-copy labels. ``None`` derives it from the data.

Constructor

__init__(subgenome_map: Optional[Dict[str, List[str]]] = None) -> None

Configure the allopolyploid process.

Parameter Type Description
subgenome_map Subgenome -> list of gene-copy labels. ``None`` derives the assignment from the data's mapping (or, failing
that from :meth:`phynetpy.GeneTrees.GeneTrees.mp_allop_map`).

Methods

resolve_subgenome_map(data) -> Dict[str, List[str]]

Return the subgenome assignment to use for *data*.

Parameter Type Description
data The :class:`~phynetpy.data.Data` being analysed.
Returns: dict[str, list[str]]: Subgenome -> gene-copy labels.
Raises: ModelSpecError: If no assignment is available.
validate(data) -> None

Check that a subgenome assignment can be resolved.

Parameter Type Description
data The data the run will consume.
Raises: ModelSpecError: If no assignment is available.
__repr__ -> str

BranchLengthUnit

class BranchLengthUnit(str, Enum)

Units carried by every biologically interpreted network. ``SUBSTITUTIONS_PER_SITE`` is required by sequence, marker, and timed-MSC calculations. ``COALESCENT_2N`` supports topology/coalescent workflows. ``UNSPECIFIED`` is safe for graph operations but rejected by biological calculations until the network is explicitly tagged or converted.

Module Functions

convert_network_branch_lengths(network: 'Network', target: BranchLengthUnit | str, theta: float, branch_thetas: Optional[Mapping[BranchThetaKey, float]] = None) -> 'Network'

Return a structural copy with branch lengths converted explicitly. Conversion follows ``t_coal = 2*t_sub/theta_branch``. The source unit is read from ``network`` and must already be explicit. Node-time annotations are copied unchanged; biological calculations derive timing from edges.

resolve_model(spec: Union[Model, str, type, None]) -> Model

Coerce a model shortcut into a :class:`Model` instance. Lets the casual user write ``model="MSC"`` and reserve the object form for when process parameters are actually needed.

Parameter Type Description
spec A :class:`Model` instance (returned unchanged), a :class:`Model` subclass (instantiated with defaults), a case-insensitive shortcut string, or ``None`` for the default (:class:`MSC`).
Returns: Model: The resolved model.
Raises: ModelSpecError: If *spec* is not a recognised model.

Navigation

Modules

This Page