TreeNode class

TreeNode class#

Note

The bdms.TreeNode class inherits from ETE’s ete3.TreeNode. Only the child class’ new members are documented here, so see the linked ETE documentation of inherited members.

class bdms.TreeNode(t=0, state=None, state_attr='state', **kwargs)#

Bases: TreeNode

A tree generated by a BDMS process. Subclasses ete3.TreeNode.

Parameters:

  • t (float) – Time of this node.

  • state (Hashable) – State of this node.

  • state_attr (str) – Name of the node attribute to store the state in.

  • kwargs (Any) – Keyword arguments passed to ete3.TreeNode initializer.

t: float#

Time of the node.

state_attr: str#

Name of the node attribute to store the state in.

event: str | None#

Event at this node.

n_mutations: int#

Number of mutations on the branch above this node (zero unless the tree has been pruned above this node, removing mutation event nodes).

evolve(t, birth_process=ConstantProcess(attr=state, value=1), death_process=ConstantProcess(attr=state, value=0), mutation_process=ConstantProcess(attr=state, value=0), mutator=DiscreteMutator(attr=state, state_space=(None,), state_space_idxs={None: 0}, transition_matrix=[[1.]]), birth_mutation_prob=0.0, min_survivors=1, capacity=1000, capacity_method=None, init_population=1, seed=None, verbose=False)#

Evolve for time \(\Delta t\).

Parameters:

  • t (float) – Evolve for a duration of \(t\) time units.

  • birth_process (Process) – Birth process function.

  • death_process (Process) – Death process function.

  • mutation_process (Process) – Mutation process function.

  • mutator (Mutator) – Generator of mutation effects at mutation events (and possibly on daughters of birth events if birth_mutation_prob > 0).

  • birth_mutation_prob (Union[float, Callable[[Any], float]]) – Probability of a mutation event for each daughter node of a birth event. If a callable, then it should take a node attribute as an argument and return a probability.

  • min_survivors (int) – Minimum number of survivors. If the simulation finishes with fewer than this number of survivors, then a TreeError is raised.

  • capacity (int) – Population carrying capacity.

  • capacity_method (Optional[Literal['birth', 'death', 'hard']]) – Method to enforce population carrying capacity. If None, then a TreeError is raised if the population exceeds the carrying capacity. If 'stop', then the simulation stops when the population reaches the carrying capacity. If 'birth', then the birth rate is logistically modulated such that the process is critical when the population is at carrying capacity. If 'death', then the death rate is logistically modulated such that the process is critical when the population is at carrying capacity. If 'hard', then a random individual is chosen to die whenever a birth event results in carrying capacity being exceeded.

  • init_population (int) – Initial population size.

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

  • verbose (bool) – Flag to indicate whether to print progress information.

Raises:

  • TreeError – If the tree is not a root node, or if the tree has already evolved, or if the number of survivors is less than min_survivors, or if the population exceeds capacity with capacity_method=None.

  • ValueError – If init_population is greater than capacity or if the event processes refer to different node attributes.

Return type:

None

sample_survivors(n=None, p=1.0, seed=None)#

Choose \(n\) survivor leaves from the tree, or each survivor leaf with probability \(p\), to mark as sampled (via the event attribute).

Parameters:

  • n (int | None) – Number of leaves to sample.

  • p (float | None) – Probability of sampling a leaf.

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

Raises:

ValueError – If the tree has already been sampled below this node, or if neither n nor p is specified.

Return type:

None

slice(t, attr='x')#
Parameters:

  • t (float) – Slice the tree at time \(t\).

  • attr (str) – Attribute to extract from slice.

Return type:

list[Any]

Returns:

List of attribute attr values at time \(t\) for all lineages alive at that time.

Raises:

ValueError – If the tree has not evolved or has already been pruned below this node, or if the tree has not been sampled below this node, or if t is before the root time or after the tree end time.

prune_unsampled()#

Prune the tree to the subtree subtending the sampled leaves, removing unobserved subtrees.

Raises:

  • ValueError – If the tree has not been sampled below this node, or if the tree has already been pruned below this node.

  • TreeError – If no leaves were sampled.

Return type:

None

remove_mutation_events()#

Remove unifurcating mutation event nodes, preserving branch length, and annotate mutation counts in child node n_mutations attribute.

Raises:

ValueError – If the tree has not been pruned below this node with prune().

Return type:

None

render(file_name, color_by='state', color_map=None, mode='r', scale=None, **kwargs)#

A thin wrapper around ete3.TreeNode.render() that adds some custom decoration and a color bar. See also ETE’s tree rendering tutorial and linked API docs pages there.

If tree is not pruned (or is pruned without removing mutation events), then branches are colored according to the attribute specified by color_by, extinct lineages are indicated as dotted branches, unsampled non-extint lineages are indicated as solid branches, and sampled lineages are indicated as thick solid branches. Sampled leaves are indicated with a circle.

If tree is pruned without retaining mutation events, then nodes are colored according to the attribute specified by color_by, branches are annotated above with branch length (in black text) and below with number of mutations (in green text).

Parameters:

  • file_name (str) – Filename to save the rendered tree to. Use "%%inline" to render inline in a notebook.

  • color_by (str | None) – If not None, color tree by this numerical node attribute.

  • color_map (Mapping[Any, str] | None) – mapping from node attribute values to color names or hex codes.

  • mode (Literal['c', 'r']) – "c" for circular tree, "r" for rectangular tree.

  • scale (float | None) – Scale branch lengths by this factor (ignored if a tree_style is passed in kwargs). If None, then the scale is chosen automatically.

  • kwargs (Any) – Keyword arguments to pass to ete3.TreeNode.render().

Return type:

Any

Returns:

The return value of ete3.TreeNode.render().