Library for the Development and Use of Phylogenetic Network Methods
Axis 3 -- the statistical objective: MDC, Likelihood, PseudoLikelihood, and Bayesian, which wraps one of the likelihoods rather than sitting parallel to them.
Raised when a criterion is misconfigured.
Base class for a statistical objective. A criterion says *what number is being optimised*: a parsimony cost, a full likelihood, a pseudo-likelihood, or a posterior. It is independent of both the data type and the biology, which is why it is its own axis. Two class attributes make the legality of a run checkable before any computation starts: * ``accepts_data`` -- the data types the objective is mathematically defined on. Violating it is a :class:`TypeError`, not a missing feature: MDC over a sequence alignment is not unimplemented, it is undefined. * ``scorable`` -- whether the objective can score a single fixed network. ``False`` for :class:`~phynetpy.criteria.Bayesian`, whose value on one network collapses to its wrapped objective. Attributes: use_branch_lengths: Tri-valued branch-length...
Minimizing deep coalescences: a parsimony criterion. Counts the extra gene lineages needed to reconcile the gene trees with the species network and prefers the network needing fewest. Defined over gene-tree *topologies*, so branch lengths are ignored by construction -- ``use_branch_lengths`` is fixed at ``False`` and cannot be overridden. Lower is better, unlike every other criterion here; the verbs normalise this so that :attr:`~phynetpy.infer.InferenceResult.score` is always reported in the criterion's own natural direction and documented as such.
Configure the parsimony criterion.
| Parameter | Type | Description |
|---|---|---|
| weighting | Per-tree weighting scheme (``"bootstrap"``, ``"posterior"``, ...). ``None`` weights every gene tree equally. |
CriterionError: If a weighting scheme is requested.Full likelihood of the data under the model. Integrates over all coalescent histories rather than summarising them, so it is the most statistically efficient of the point-estimate criteria and the most expensive. Defined on all three data types. Attributes: use_branch_lengths: ``True`` requires and uses gene-tree branch lengths, ``False`` scores topologies only, ``None`` uses them when present.
Configure the full-likelihood criterion.
| Parameter | Type | Description |
|---|---|---|
| use_branch_lengths | Branch-length policy. ``None`` (default) uses gene-tree branch lengths when the data carries them. |
Pseudo-likelihood over subsets of the taxa. Replaces the full likelihood with a product of likelihoods over small subsets (by default rooted triples), which is far cheaper and scales to many more taxa at some cost in efficiency (Yu & Nakhleh 2015; Solis-Lemus & Ane 2016). Defined on gene-tree topologies and on biallelic markers, but not on alignments: a pseudo-likelihood over subsets of gene trees needs gene trees, and PhyNetPy does not estimate them from sequences. Attributes: subsets: Which subsets the product runs over. Only ``"trinets"`` (rooted triples) is implemented. use_branch_lengths: Branch-length policy; the triplet method consumes topologies only.
Configure the pseudo-likelihood criterion.
| Parameter | Type | Description |
|---|---|---|
| subsets | Subset family for the product. ``"trinets"`` (3-taxon subnetworks) is the only supported value. | |
| use_branch_lengths | Branch-length policy. |
CriterionError: If *subsets* is not ``"trinets"``.Bayesian mode: sample a posterior built on an objective. Not a fourth objective but a *mode layered on one*. The casual user writes ``Bayesian()`` and gets the full likelihood; the power user writes ``Bayesian(objective=PseudoLikelihood())``. Which data types are legal follows from the wrapped objective, so ``accepts_data`` is delegated to it. Scoring a single fixed network under a Bayesian criterion collapses to computing its likelihood or posterior density, so ``scorable`` is ``False`` and :func:`phynetpy.infer.score` refuses it, pointing the caller at ``.objective`` instead. Attributes: objective: The wrapped likelihood (full or pseudo). prior: Prior hyperparameters, or ``None`` for the engine's defaults. chain_length: Total proposed moves. burnin: Iterations discarded before sampling b...
Data types the wrapped objective is defined on.
Branch-length policy of the wrapped objective.
Configure the Bayesian mode.
| Parameter | Type | Description |
|---|---|---|
| objective | The likelihood the posterior is built on. ``None`` | |
| selects | class:`Likelihood`. | |
| prior | Prior hyperparameters (:class:`~phynetpy.infer.MCMC_GTPriors` for gene trees and | |
| markers | :class:`~phynetpy.infer.MCMCSeqPriors` for alignments). ``None`` uses the engine's defaults. | |
| chain_length | Total proposed moves. | |
| burnin | Iterations discarded before sampling. | |
| sample_freq | Thinning interval for retained samples. | |
| seed | Master RNG seed. | |
| temperatures | MC3 temperature ladder (alignments only). |
CriterionError: If the objective is itself Bayesian, or the chain budget is inconsistent.Coerce a criterion shortcut into a :class:`Criterion` instance. Lets the casual user write ``criterion="MPL"`` and reserve the object form for when parameters are actually needed.
| Parameter | Type | Description |
|---|---|---|
| spec | A :class:`Criterion` instance (returned unchanged), a :class:`Criterion` subclass (instantiated with defaults), a case-insensitive shortcut string, or ``None`` for the default (:class:`Likelihood`). |
CriterionError: If *spec* is not a recognised criterion.