bdms.mutators

Mutation effects generators.

Abstract base class for defining generic mutation effect generators (i.e. \(\mathcal{p}(x\mid x')\)), with arbitrary ete3.TreeNode attribute dependence. Some concrete child classes are included.

These classes are used to define mutation effects for simulations with bdms.TreeNode.evolve.

Example

>>> import bdms

Define a discrete mutation model.

>>> mutator = bdms.mutators.DiscreteMutator(
...     state_space=["a", "b", "c"],
...     transition_matrix=[[0.0, 0.5, 0.5],
...                        [0.5, 0.0, 0.5],
...                        [0.5, 0.5, 0.0]],
... )

Mutate a node.

>>> node = bdms.TreeNode(state="a")
>>> mutator.mutate(node, seed=0)
>>> node.state
'c'

Module Contents

Classes

Mutator	Abstract base class for mutators that mutate a specified
GaussianMutator	Gaussian mutation effects on a specified attribute.
KdeMutator	Gaussian kernel density estimator (KDE) for mutation effect on a specified
DiscreteMutator	Mutations on a discrete space with a stochastic matrix.

class bdms.mutators.Mutator(attr='state', *args, **kwargs)

Bases: abc.ABC

Abstract base class for mutators that mutate a specified ete3.TreeNode node attribute.

Parameters:

• attr (str) – Node attribute to mutate.

• args (Any) –

• kwargs (Any) –

abstract mutate(node, seed=None)

Mutate a bdms.TreeNode object in place.

Parameters:

• node (TreeNode) – A bdms.TreeNode to mutate.

• seed (int | Generator | None) – A seed to initialize the random number generation. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int, then it will be used to derive the initial state. If a numpy.random.Generator, then it will be used directly.

Return type:

None

abstract prob(attr1, attr2, log=False)

Probability of mutating from attr1 to attr2.

Parameters:

• attr1 (float) – The initial attribute value.

• attr2 (float) – The final attribute value.

• log (bool) – If True, return the log-probability.

Returns:

Mutation probability (or log probability).

Return type:

float

class bdms.mutators.GaussianMutator(shift=0.0, scale=1.0, attr='state')

Bases: Mutator

Gaussian mutation effects on a specified attribute.

Parameters:

• shift (float) – Mean shift wrt current attribute value.

• scale (float) – Standard deviation of mutation effect.

• attr (str) – Node attribute to mutate.

mutate(node, seed=None)

Mutate a bdms.TreeNode object in place.

Parameters:

• node (TreeNode) – A bdms.TreeNode to mutate.

• seed (int | Generator | None) – A seed to initialize the random number generation. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int, then it will be used to derive the initial state. If a numpy.random.Generator, then it will be used directly.

Return type:

None

prob(attr1, attr2, log=False)

Probability of mutating from attr1 to attr2.

Parameters:

• attr1 (float) – The initial attribute value.

• attr2 (float) – The final attribute value.

• log (bool) – If True, return the log-probability.

Returns:

Mutation probability (or log probability).

Return type:

float

class bdms.mutators.KdeMutator(data, attr='state', bw_method=None, weights=None)

Bases: Mutator

Gaussian kernel density estimator (KDE) for mutation effect on a specified attribute.

Parameters:

• data (numpy.typing.NDArray[numpy.float64]) – Data to fit the KDE to.

• attr (str) – Node attribute to mutate.

• bw_method (str | float | Callable[Ellipsis, float] | None) – KDE bandwidth (see scipy.stats.gaussian_kde).

• weights (numpy.typing.NDArray[numpy.float64] | None) – Weights of data points (see scipy.stats.gaussian_kde).

mutate(node, seed=None)

Mutate a bdms.TreeNode object in place.

Parameters:

• node (TreeNode) – A bdms.TreeNode to mutate.

• seed (int | Generator | None) – A seed to initialize the random number generation. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int, then it will be used to derive the initial state. If a numpy.random.Generator, then it will be used directly.

Return type:

None

prob(attr1, attr2, log=False)

Probability of mutating from attr1 to attr2.

Parameters:

• attr1 (float) – The initial attribute value.

• attr2 (float) – The final attribute value.

• log (bool) – If True, return the log-probability.

Returns:

Mutation probability (or log probability).

Return type:

float

class bdms.mutators.DiscreteMutator(state_space, transition_matrix, attr='state')

Bases: Mutator

Mutations on a discrete space with a stochastic matrix.

Parameters:

• state_space (Sequence[Hashable]) – hashable state values.

• transition_matrix (numpy.typing.NDArray[numpy.float64]) – Right-stochastic matrix, where column and row orders match the order of state_space.

• attr (str) – Node attribute to mutate.

state_space: dict[Any, int]

Mapping from state values to their indices in the transition matrix.

mutate(node, seed=None)

Mutate a bdms.TreeNode object in place.

Parameters:

• node (TreeNode) – A bdms.TreeNode to mutate.

• seed (int | Generator | None) – A seed to initialize the random number generation. If None, then fresh, unpredictable entropy will be pulled from the OS. If an int, then it will be used to derive the initial state. If a numpy.random.Generator, then it will be used directly.

Return type:

None

prob(attr1, attr2, log=False)

Probability of mutating from attr1 to attr2.

Parameters:

• attr1 (float) – The initial attribute value.

• attr2 (float) – The final attribute value.

• log (bool) – If True, return the log-probability.

Returns:

Mutation probability (or log probability).

Return type:

float