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

​

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

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

​

Outputs

​

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

​

Internal Logic

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

    def simulate_tree(self) -> CassiopeiaTree:
        ...