> ## Documentation Index
> Fetch the complete documentation index at: https://demo.agenticlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

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

```python theme={null}
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

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.

```python theme={null}
    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

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

```python theme={null}
    def simulate_tree(self) -> CassiopeiaTree:
        ...
```