mutators module

mutators module#

Classes for defining mutation effect generators \(\mathcal{p}(x\mid x')\), with arbitrary bdms.TreeNode attribute dependence. An abstract base class and several 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'
class bdms.mutators.Mutator(attr='state', *args, **kwargs)#

Bases: ABC

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

Parameters:

attr (str) – Node attribute to mutate.

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.

Return type:

float

Returns:

Mutation probability (or log probability).

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.

Return type:

float

Returns:

Mutation probability (or log probability).

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:
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.

Return type:

float

Returns:

Mutation probability (or log probability).

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]) – State values.

  • transition_matrix (ndarray[tuple[int, ...], dtype[float64]]) – Right-stochastic matrix, where column and row orders match the order of state_space.

  • attr (str) – Node attribute to mutate.

state_space_idxs: 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.

Return type:

float

Returns:

Mutation probability (or log probability).