PhyNetPy Documentation

Library for the Development and Use of Phylogenetic Network Methods

criteria Module v1.0.0

Axis 3 -- the statistical objective: MDC, Likelihood, PseudoLikelihood, and Bayesian, which wraps one of the likelihoods rather than sitting parallel to them.

Author:
Mark Kessler
Source:
criteria.py

Exceptions

exception CriterionError(Exception)

Raised when a criterion is misconfigured.

Criterion

class Criterion(ABC)

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...

Methods

__repr__ -> str

MDC

class MDC(Criterion)

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.

Constructor

__init__(weighting: Optional[str] = None) -> None

Configure the parsimony criterion.

Parameter Type Description
weighting Per-tree weighting scheme (``"bootstrap"``, ``"posterior"``, ...). ``None`` weights every gene tree equally.
Raises: CriterionError: If a weighting scheme is requested.

Likelihood

class Likelihood(Criterion)

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.

Constructor

__init__(use_branch_lengths: Optional[bool] = None) -> None

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.

Methods

__repr__ -> str

PseudoLikelihood

class PseudoLikelihood(Criterion)

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.

Constructor

__init__(subsets: str = 'trinets', use_branch_lengths: Optional[bool] = None) -> None

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.
Raises: CriterionError: If *subsets* is not ``"trinets"``.

Methods

__repr__ -> str

Bayesian

class Bayesian(Criterion)

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...

Properties

accepts_data -> tuple property

Data types the wrapped objective is defined on.

use_branch_lengths -> Optional[bool] property

Branch-length policy of the wrapped objective.

Constructor

__init__(objective: Optional[Criterion] = None, prior: Optional[Any] = None, chain_length: int = 1000000, burnin: int = 100000, sample_freq: int = 100, seed: Any = None, temperatures: Optional[list] = None) -> None

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).
Raises: CriterionError: If the objective is itself Bayesian, or the chain budget is inconsistent.

Methods

__repr__ -> str

Module Functions

resolve_criterion(spec: Union[Criterion, str, type, None]) -> Criterion

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`).
Returns: Criterion: The resolved criterion.
Raises: CriterionError: If *spec* is not a recognised criterion.

Navigation

Modules

This Page