SimpleFitSubcloneSimulator.py

High-level description

The SimpleFitSubcloneSimulator class simulates the growth of a clonal population where a single subclone develops a fitness advantage after a specified number of generations. This simulator is useful for generating both deterministic and stochastic phylogenies that exhibit non-neutral evolution due to the presence of a fitter subclone.

Code Structure

The SimpleFitSubcloneSimulator class inherits from the TreeSimulator class. It overrides the simulate_tree method to implement its specific simulation logic. The class uses a queue to manage the growth of the tree, adding new nodes and edges based on the specified branch lengths and the time of the experiment.

References

This code references the following symbols:

cassiopeia.data.CassiopeiaTree
cassiopeia.simulator.TreeSimulator

Symbols

`SimpleFitSubcloneSimulator`

Description

This class simulates a clonal population with a single fit subclone emerging after a specified number of generations. It allows for both deterministic and stochastic simulations by accepting either constant values or callables for branch lengths.

Inputs

Name	Type	Description
branch_length_neutral	Union[float, Callable[[], float]]	Branch length of neutrally evolving individuals. Can be a constant or a callable returning a float.
branch_length_fit	Union[float, Callable[[], float]]	Branch length of the fit subclone. Can be a constant or a callable returning a float.
experiment_duration	float	Total duration of the simulation.
generations_until_fit_subclone	int	Generation at which the fit subclone emerges.

Outputs

This class doesn’t directly return any output. It simulates a tree and stores it internally.

Internal Logic

Initializes the branch length callables for neutral and fit individuals.
Creates a directed graph to represent the tree.
Initializes a queue to manage the growth of the tree, starting with the root node.
Iteratively processes nodes from the queue:
- Determines the time until the next division based on the node’s fitness.
- If the time exceeds the experiment duration, the node becomes a leaf.
- Otherwise, creates two children nodes, assigns their fitness based on the current generation and the generations_until_fit_subclone parameter, and adds them to the queue.
Constructs a CassiopeiaTree object from the simulated tree graph and returns it.

Side Effects

The simulate_tree method modifies the internal state of the SimpleFitSubcloneSimulator object by creating and populating the tree graph.

Dependencies

Dependency	Purpose
networkx	Used for creating and manipulating the tree graph.
queue	Used for managing the growth of the tree.
typing	Used for type hinting.
cassiopeia.data	Used for the `CassiopeiaTree` class.
cassiopeia.simulator	Used for the `TreeSimulator` class.

class SimpleFitSubcloneSimulator(TreeSimulator):
    ...

`_create_callable`

Description

This private method converts a constant branch length value or a callable into a callable. This allows the simulator to handle both deterministic and stochastic branch lengths.

Inputs

Name	Type	Description
x	Union[float, Callable[[], float]]	Branch length value or callable.

Outputs

Name	Type	Description
constant_branch_length_callable or x	Callable[[], float]	A callable that returns the branch length.

Internal Logic

If x is an integer or float, it defines a new callable that always returns x.
Otherwise, it returns x directly, assuming it’s already a callable.

    def _create_callable(
        self, x: Union[float, Callable[[], float]]
    ) -&gt; Callable[[], float]:
        # In case the user provides an int, we still hold their back...
        if type(x) in [int, float]:

            def constant_branch_length_callable() -&gt; float:
                return x

            return constant_branch_length_callable
        else:
            return x

`simulate_tree`

Description

This method simulates the growth of a clonal population with a single fit subclone and returns the resulting tree as a CassiopeiaTree object.

Inputs

This method doesn’t take any explicit inputs. It uses the parameters provided during the initialization of the SimpleFitSubcloneSimulator object.

Outputs

Name	Type	Description
res	CassiopeiaTree	The simulated tree.

Internal Logic

Refer to the “Internal Logic” section of the SimpleFitSubcloneSimulator class description for details on the simulation process.

    def simulate_tree(self) -&gt; CassiopeiaTree:
        ...

​High-level description

​Code Structure

​References

​Symbols

​SimpleFitSubcloneSimulator

​Description

​Inputs

​Outputs

​Internal Logic

​Side Effects

​Dependencies

​_create_callable

​Description

​Inputs

​Outputs

​Internal Logic

​simulate_tree

​Description

​Inputs

​Outputs

​Internal Logic

High-level description

Code Structure

References

Symbols

`SimpleFitSubcloneSimulator`

Description

Inputs

Outputs

Internal Logic

Side Effects

Dependencies

`_create_callable`

Description

Inputs

Outputs

Internal Logic

`simulate_tree`

Description

Inputs

Outputs

Internal Logic