Library for the Development and Use of Phylogenetic Network Methods
Axis 2 -- the generative biology: MSC (diploid, ILS only) and Allopolyploid (whole-genome duplication).
Raised when a model is misconfigured for the data it is given.
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...
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. |
ModelSpecError: If the model cannot be applied to *data*.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...
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. |
ModelSpecError: If any rate is non-positive.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.
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`). |
Return the subgenome assignment to use for *data*.
| Parameter | Type | Description |
|---|---|---|
| data | The :class:`~phynetpy.data.Data` being analysed. |
ModelSpecError: If no assignment is available.Check that a subgenome assignment can be resolved.
| Parameter | Type | Description |
|---|---|---|
| data | The data the run will consume. |
ModelSpecError: If no assignment is available.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.
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.
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`). |
ModelSpecError: If *spec* is not a recognised model.