PhyNetPy Documentation

Library for the Development and Use of Phylogenetic Network Methods

Home » ModelMove

ModelMove Module v1.0.0

Network topology move operations for MCMC search (add/remove/flip reticulation, SPR).

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

Contents

Exceptions

exception MoveError(Exception)

This exception is raised whenever there is a fatal error in executing a network move.

Move

class Move(ABC)

Abstract superclass for all model move types. A move can be executed on a model that is passed in, and edits an aspect of the model.

Constructor

__init__()

Moves in general do not require any parameters

Methods

execute(model: Model) -> Model abstract
Parameter Type Description
model Model A Model obj
Returns: Model: A new Model obj that is the result of this operation on model
undo(model: Model) -> None abstract

A function that will undo what "execute" did.

Parameter Type Description
model Model A phylogenetic network model object.
same_move(model: Model) -> None abstract

Applies the exact move as execute, on a different but identical (with respect to topology) Model object to a model that has had "execute" called on it.

Parameter Type Description
model Model A phylogenetic network model obj.
hastings_ratio -> float abstract

Returns the hastings-ratio for a move-- that is the ratio of valid states to return to post-move, to the number of valid states to transition to pre-move.

Returns: float: Hastings Ratio. For symmetric moves, this is 1.0.

AddReticulation

class AddReticulation(Move)

A move that adds a reticulation to a network.

Constructor

__init__() -> None

Initializes a move that adds a reticulation to a network.

Methods

execute(model: Model) -> Model

Adds a reticulation to a network.

Parameter Type Description
model Model The model object containing the network.
Returns: Model: The modified model with the added reticulation.
undo(model: Model) -> None

Undoes the addition of a reticulation to a network.

Parameter Type Description
model Model The model object containing the network.
same_move(model: Model) -> None

Applies the same addition of a reticulation to another model.

Parameter Type Description
model Model The model object containing the network.
hastings_ratio -> float

Returns the Hastings ratio for the addition move.

Returns: float: The Hastings ratio.

RemoveReticulation

class RemoveReticulation(Move)

A move that removes a reticulation from a network.

Constructor

__init__() -> None

Initializes a move that removes a reticulation from a network.

Methods

execute(model: Model) -> Model
undo(model: Model) -> None
same_move(model: Model) -> None
hastings_ratio -> float

FlipReticulation

class FlipReticulation(Move)

A move that flips the direction of a reticulation edge.

Constructor

__init__() -> None

Initializes a move that flips the direction of a reticulation edge.

Methods

execute(model: Model) -> Model

Removes a reticulation edge from the network

Parameter Type Description
model Model The model object containing the network.
Returns: Model: The modified model with the flipped reticulation
undo(model: Model) -> None

Undoes the flipping of the reticulation edge.

Parameter Type Description
model Model The model object containing the network.
same_move(model: Model) -> None

Applies the same flipping of the reticulation edge to another model.

Parameter Type Description
model Model The model object containing the network.
hastings_ratio -> float

Return the hastings ratio for this move

Returns: float: The hastings ratio for the flip reticulation move

SwitchParentage

class SwitchParentage(Move)

For use in Infer_MP_Allop, this move alters the genetic parentage of an entire subnetwork, while maintaining the same ploidy values for each leaf.

Constructor

__init__(debug_id: int = 0) -> None

Initializes a move that switches the parentage of a subnetwork.

Parameter Type Description
debug_id int The debug id for the move.

Methods

random_object(mylist: list, rng: np.random.Generator) -> object

Selects a random object from a list.

Parameter Type Description
mylist list The list of objects to select from.
rng np.random.Generator The random number generator.
Returns: object: The randomly selected object.
execute(model: Model) -> Model

Executes the Swap-Parentage Move.

Parameter Type Description
model Model A model object, for which there must be a populated network field
Returns: Model: A modified model, with a newly proposed network topology
undo(model: Model) -> None

Undoes the Swap-Parentage Move

Parameter Type Description
model Model The model object containing the network.
same_move(model: Model) -> None

Executes the same topology change on another model

Parameter Type Description
model Model The model object containing the network.
hastings_ratio -> float

Returns the Hastings ratio for the Swap-Parentage Move.

Returns: float: The Hastings ratio.
delete_edge(net: Network, edge: Edge) -> None

Deletes an edge from the network.

Parameter Type Description
net Network The network object.
edge Edge The edge to delete.

SPR

class SPR(Move)

A move that performs a Subtree Prune and Regraft operation on a network.

Constructor

__init__(debug_id: int = 0) -> None

Initializes a move that performs a Subtree Prune and Regraft operation.

Parameter Type Description
debug_id int The debug id for the move.

Methods

random_object(mylist: list, rng: np.random.Generator) -> object

Selects a random object from a list.

Parameter Type Description
mylist list The list of objects to select from.
rng np.random.Generator The random number generator.
Returns: object: The randomly selected object.
execute(model: Model) -> Model

Executes the Subtree Prune and Regraft move.

Parameter Type Description
model Model The model object containing the network.
Returns: Model: The modified model with the Subtree Prune and Regraft move executed.
undo(model: Model) -> None

Undoes the Subtree Prune and Regraft move.

Parameter Type Description
model Model The model object containing the network.
same_move(model: Model) -> None

Perform the same Subtree Prune and Regraft move on another model.

Parameter Type Description
model Model The model object containing the network.
hastings_ratio -> float

Returns the Hastings ratio for the Subtree Prune and Regraft move.

Returns: float: The Hastings ratio.

Module Functions

insert_node_in_edge(edge: Edge, node: Node, net: Network) -> None

Given an edge, a -> b, place a node c, such that a -> c -> b. This requires the deletion of edge a -> b, then the addition of edges a -> c and c -> b.

Parameter Type Description
edge Edge An edge, a -> b
node Node A node, c.
net Network The network that contains nodes a, b, and c
connect_nodes(src: Node, dest: Node, net: Network) -> None

Given two nodes in a network, connect them and check whether or not a reticulation is created.

Parameter Type Description
src Node The parent of the new edge
dest Node The child of the new edge
net Network Network for which to add the edge

PhyNetPy Documentation - Copyright 2025 Mark Kessler, Luay Nakhleh

Navigation

Modules

This Page