PhyNetPy Documentation

Library for the Development and Use of Phylogenetic Network Methods

ModelGraph Module v0.1.0

The Model container pairing a network with its likelihood calculator, plus dirty-state tracking for incremental rescoring.

Author:
Mark Kessler
Last Edit:
3/11/25
Source:
ModelGraph.py

Contents

Exceptions

exception ModelError(Exception)

Class to handle any errors related to building the model or running likelihoods computations on the model.

Model

class Model

A network under evaluation, together with the calculator that scores it. Search drivers mutate ``network`` through :class:`~.ModelMove.Move` objects and read the resulting score back through :meth:`likelihood`, which caches until a move marks the model dirty.

Constructor

__init__(rng: np.random.Generator | np.random.SeedSequence | int | None = None) -> None

Initialize a model object.

Parameter Type Description
rng Optional RNG context. Accepts a ``numpy.random.Generator`` (used directly), a ``numpy.random.SeedSequence`` (used to build a fresh generator), or an ``int`` seed. ``None`` falls back to ``numpy.random.default_rng()``, which seeds itself from OS entropy. Callers that care about reproducibility (e.g. ``MPL.search``) should pass a ``SeedSequence`` spawned from the search-wide seed.

Methods

set_likelihood_calculator(calculator: Any) -> None

Set a callable that computes the model's likelihood/score. The callable should accept a single argument (the Model instance) and return a float.

Parameter Type Description
calculator A callable (Model) -> float.
update_network -> None

Called after any move modifies the network topology. Marks the model as needing recomputation. Treated as a *full* invalidation: any fine-grained dirty-node set that a move may have posted via :meth:`mark_touched` is promoted to ``None`` (all-dirty) so the scorer's fallback path kicks in. Moves that know exactly which nodes they touched should call :meth:`mark_touched` *instead of* this method (or before it).

mark_touched(nodes: 'set[Node] | None') -> None

Record which network nodes were modified by the last move. Called by :class:`Move` subclasses from ``execute``/``undo`` to let scorers with per-network-edge caches (e.g. MCMC_GT's :class:`_GTLikelihoodEngine`) invalidate only the affected region instead of the entire likelihood. Semantics: * ``mark_touched(None)`` -> escalate to full invalidation, regardless of any previously-posted set. Safe fallback used by moves whose impact is hard to localize. * ``mark_touched(set(...))`` -> merge into any existing dirty set (so multiple sequential mutations accumulate). If the model is already "all dirty" the call is a no-op. * ``mark_touched(set())`` -> initialise an empty set, signalling "nothing dirty this iteration" (useful for rebinding after a full rescore).

Parameter Type Description
nodes Nodes whose incident branches or gammas changed, or ``None`` for all-dirty.
clear_dirty_nodes -> None

Reset the fine-grained dirty-node set to "nothing dirty". Called by scorers after they have consumed ``_dirty_nodes`` and updated their caches accordingly. Leaves the coarse ``_dirty`` flag alone; the caller controls that via :meth:`likelihood` gating.

likelihood -> float

Compute the model likelihood/score using the registered calculator.

Returns: float: The model likelihood or score.
Raises: ModelError: If no likelihood calculator has been set.
prime_likelihood(value: float) -> None

Seed the likelihood cache with an already-known score. Search drivers call this after committing an accepted proposal: the committed network's score is exactly the proposal's score, which was computed moments earlier. Without priming, :meth:`update_network` would leave the model dirty and the next :meth:`likelihood` call would recompute a value it already has. Only valid when ``value`` is genuinely the score of the model's current network; passing anything else silently corrupts the search.

Parameter Type Description
value The known score of the current network.

Navigation

Modules

This Page