BirthDeath Module v2.0.0

Birth-death process network simulators (Yule and CBDP models).

Author:: Mark Kessler
Last Edit:: 11/10/25
Source:: BirthDeath.py

Constants

TIP_ERROR_THRESHOLD : float = 5 * 1000.0

Exceptions

exception BirthDeathSimulationError(Exception)

This exception is thrown whenever something irrecoverably wrong happens during the process of generating a network within the Yule or CBDP algorithm

Yule

class Yule

The Yule class represents a pure birth model for simulating networks of a fixed (n) amount of extant taxa. gamma -- the birth rate. A larger birth rate will result in shorter branch lengths and a younger network. Value should be a non-negative real number. n -- number of extant taxa at the end of simulation time -- if conditioning on time, the age of the tree to be simulated rng -- numpy random number generator for drawing speciation times

Constructor

__init__(gamma: float, n: Union[int, None] = None, time: Union[float, None] = None, rng: Union[np.random.Generator, None] = None) -> None

Parameter	Type	Description
gamma	Union[float, None]	Birth rate. Should be strictly positive.
n	Union[int, None], optional	Number of taxa in simulated network. Defaults to None.
time	Union[float, None], optional	Age of simulated network, alternative to simulating to a number of taxa. Defaults to None.
rng	Union[np.random.Generator, None], optional	A random number generator. This input allows for consistent generation if a seed is given, generally for debugging. Defaults to None.

Raises: BirthDeathSimulationError: If something goes wrong simulating networks.

Methods

set_time(value: float) -> None

Set simulated network age

Parameter	Type	Description
value	float	The age of any future simulated trees

Raises: BirthDeathSimulationError: if value <= 0

set_taxa(value: int) -> None

Set simulated tree taxa count

Parameter	Type	Description
value	int	an integer >= 2

Raises: BirthDeathSimulationError: if value < 2

set_gamma(new_gamma: float) -> None

Setter for the gamma (birth rate) parameter

Parameter	Type	Description
new_gamma	float	the new birth rate

Raises: BirthDeathSimulationError: if new_gamma <= 0

generate_network -> Network

Simulate one Network. Starts with a root and 2 living lineages and then continuously runs speciation (in this case birth only) events until there are exactly N live species. After the nth event, draw one more time and fill out the remaining branch lengths.

Returns: Network: The simulated tree

clear_generated -> None

Empty out the generated network array

generate_networks(num_networks: int) -> list[Network]

Generate a set number of trees.

Parameter	Type	Description
num_networks	int	The number of networks to generate

Returns: list[Network]: The array of generated networks. (includes all that have been previously generated)

CBDP

class CBDP

Constant Rate Birth Death Process Network simulation

Constructor

__init__(gamma: float, mu: float, n: int, sample: float = 1) -> None

Create a new Constant Rate Birth Death Simulator. You need the following parameters: 1) A birth rate (gamma, as always) 2) A death rate (mu, and should always be less than the birth rate so that networks can actually be generated and reach the goal amount of species) 3) A goal amount of !LIVE! species in the simulated network. 4) A sampling rate. NOTE! When doing network operations on a CBDP simulated tree with n LIVE lineages, you will have more than n leaves in the the network. If you want leaves, great, but if you want the live lineages, be sure to use the live_species counter function.

Parameter	Type	Description
gamma	float	birth rate
mu	float	death rate
n	int	number of !LIVE! taxa for simulated trees
sample	float, optional	Sampling rate from (0, 1]. Defaults to 1.

Raises: BirthDeathSimError: if birth/death/sample/n parameters are non-sensical

Methods

set_bd(gamma: float, mu: float) -> None

Set the birth and death rates for the model

Parameter	Type	Description
gamma	float	The birth rate. Must be a positive real number, and strictly greater than mu.
mu	float	The death rate. Must be a non-negative real number, less than gamma.

Raises: BirthDeathSimError: if birth/death parameters are non-sensical

set_n(new_n: int) -> None

Set the number of taxa for the simulated trees.

Parameter	Type	Description
new_n	int	An integer value >= 2

Raises: BirthDeathSimError: if the n parameter is non-sensical

set_sample(new_sampling: float) -> None

Set the sampling rate. Must be a value in the interval (0,1].

Parameter	Type	Description
new_sampling	float	A float between 0 (exclusive), and 1 (inclusive)

Raises: BirthDeathSimulationError: If the provided sampling rate is not in the right range

generate_network -> Network

Simulate a single network under the Constant Rate Birth Death Model. Follows the algorithm laid out by (2)

Returns: (Network) A network with n taxa chosen from the distributions.

generate_networks(m: int) -> list[Network]

Generate 'm' number of trees and add them to the list of generated trees

Parameter	Type	Description
m	int	number of networks to generate

Returns: list[Network]: The list of all generated trees from this run and any prior uncleared runs.

clear_generated -> None

Empty out the generated network array.

Module Functions

estimate_expected_tips(gamma: float, time: float) -> float

Estimate the expected number of taxa produced by a Yule process.

Parameter	Type	Description
gamma	float	Birth rate parameter (must be > 0).
time	float	Target time horizon (must be >= 0).

Returns: float: Expected number of taxa at the provided time.

random_species_selection(nodes: list[Node], rng: np.random.Generator) -> Node

Returns a random live Node from an array/set. The Node returned will be operated on during a birth or death event

Parameter	Type	Description
nodes	list[Node]	a list of live lineages (aka Nodes with an attribute "live" mapped to True)
rng	np.random.Generator	the result of a np.random.default_rng call (which should have been initialized with a random int seed)

Returns: Node: The randomly selected node to operate on

live_species(nodes: list[Node]) -> list[Node]

Returns a subset of Nodes that represent live lineages. A Node represents a live lineage if it has an attribute "live" set to True.

Parameter	Type	Description
nodes	list[Node]	a list of all nodes in a network

Returns: list[Node]: the subset of nodes in a network that represent live lineages (have attr key value pair "live" : True).

PhyNetPy Documentation

BirthDeath Module v2.0.0

Contents

Constants

Exceptions

Yule

Constructor

Methods

CBDP

Constructor

Methods

Module Functions

Navigation

Modules

This Page