PhyNetPy Documentation

Library for the Development and Use of Phylogenetic Network Methods

State Module v1.0.0

State management for MCMC accept/reject decisions with model validation.

Author:
Mark Kessler
Last Edit:
5/12/26
Source:
State.py

State

class State

Accept/reject bookkeeping for the Metropolis-Hastings and annealing drivers, around one live model. A proposal is a :class:`Move` executed in place on ``model.network``. Rejection undoes the move in place. Acceptance records the proposal's score as the accepted score and nothing else: the live network simply stays as it is. There is no second copy of the network, so accepting a move costs nothing, and scorers that cache topology by network identity (see ``MPLScorer``) keep their caches across acceptances. The one invariant this rests on: :meth:`likelihood` returns the cached accepted score and never re-scores the live network, because the live network may be mid-proposal when it is read. Callers that want a network to keep (a best-so-far) must snapshot it with ``Network.copy()``; the live ...

Properties

current_model -> Model | None property

The live model. Between proposals it is the accepted state.

proposed_model -> Model | None property

The live model, which a proposal mutates in place.

Constructor

__init__(model: Model | None = None, validate: Callable[[Model], bool] = network_invariants_routine) -> None

Initialize a State around ``model``.

Parameter Type Description
model Model | None, optional A Phylogenetic Model. Defaults to
None only used for if bootstrapping is to be used.
validate Callable[[Model], bool] A callable function that checks for model validity. The parameter for such a function should be a Model object, and return True if the Model is
valid False if not. Defaults to 'network_invariants_routine', which checks that the Model's phylogenetic network is acyclic and has well-formed root, leaf, and reticulation degrees.

Methods

likelihood -> float

The accepted score: the likelihood of the last accepted state. Computed from the model once, before any proposal, and afterwards updated only by :meth:`commit`. Never re-scores the live network.

Parameter Type Description
Returns a float that is the model likelihood for the current accepted state
generate_next(move: Move) -> bool

Apply one move to the live model, as a proposal. Relies on the move's own undo() for rollback instead of deep-copying the entire model as a snapshot.

Parameter Type Description
move Move Any instantiated subclass of Move.
Returns: bool: True if the network associated with the model is valid, False otherwise.
revert(move: Move) -> None

Undo the proposal: the live model returns to the accepted state.

Parameter Type Description
move Move Any instantiated subclass of Move.
commit(move: Move, score: float | None = None) -> None

Accept the proposal. The live network already is the new state; only the accepted score changes.

Parameter Type Description
move Move The accepted move (kept for the driver API).
score float | None The proposal's score, as the driver computed it. When omitted, the model's cached likelihood is read, which is the same value when nothing changed the parameters after it was scored.
proposed -> Model

Grab the live model, which carries the current proposal.

Returns: Model: The proposed / edited Model.
bootstrap(data: Matrix, submodel: GTR) -> None

Generate an initial state by 1) simulating a network 2) building a model based on that network and some input data. Currently only in use for the simplest case, a DNA/Felsenstein model.

Parameter Type Description
data Matrix The nexus file data that has been preprocessed by the Matrix class.
submodel GTR Any substitution model (can be subtype of GTR)
validate_proposed_network(prev_move: Move) -> bool

Check certain conditions on a network to check for validity.

Parameter Type Description
prev_move Move the move obj that was imposed on the current model
Returns: bool: True if valid, False otherwise.

Module Functions

network_invariants_routine(model: Model) -> bool

Validate that a network satisfies phylogenetic invariants. Checks: 1. Exactly one root (in-degree 0, out-degree >= 2) 2. Every leaf has (in=1, out=0) 3. Every reticulation has (in=2, out=1) 4. Every other internal node has (in=1, out >= 2) 5. The graph is a DAG (acyclic)

Parameter Type Description
model A Model whose ``network`` attribute is the phylogenetic network.
Returns: True when all invariants hold, False otherwise.

Navigation

Modules

This Page