Skip to main content

​
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

NameTypeDescription
branch_length_neutralUnion[float, Callable[[], float]]Branch length of neutrally evolving individuals. Can be a constant or a callable returning a float.
branch_length_fitUnion[float, Callable[[], float]]Branch length of the fit subclone. Can be a constant or a callable returning a float.
experiment_durationfloatTotal duration of the simulation.
generations_until_fit_subcloneintGeneration 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

  1. Initializes the branch length callables for neutral and fit individuals.
  2. Creates a directed graph to represent the tree.
  3. Initializes a queue to manage the growth of the tree, starting with the root node.
  4. 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.
  5. 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

DependencyPurpose
networkxUsed for creating and manipulating the tree graph.
queueUsed for managing the growth of the tree.
typingUsed for type hinting.
cassiopeia.dataUsed for the CassiopeiaTree class.
cassiopeia.simulatorUsed 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

NameTypeDescription
xUnion[float, Callable[[], float]]Branch length value or callable.

​
Outputs

NameTypeDescription
constant_branch_length_callable or xCallable[[], float]A callable that returns the branch length.

​
Internal Logic

  1. If x is an integer or float, it defines a new callable that always returns x.
  2. Otherwise, it returns x directly, assuming it’s already a callable.
    def _create_callable(
        self, x: Union[float, Callable[[], float]]
    ) -> 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() -> 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

NameTypeDescription
resCassiopeiaTreeThe 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) -> CassiopeiaTree:
        ...
⌘I