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

# SequentialLineageTracingDataSimulator.py

## High-level description

The `SequentialLineageTracingDataSimulator` class simulates lineage tracing data generated by sequential Cas9-based technologies, such as the DNA Typewriter. It overlays simulated edits onto a `CassiopeiaTree`, mimicking the sequential recording process of these technologies. The simulator considers factors like initiation and continuation rates of Cas9 recording, cassette architecture, state distributions, and silencing rates to generate realistic data.

## Code Structure

The `SequentialLineageTracingDataSimulator` class inherits from the `LineageTracingDataSimulator` class. It primarily implements the `overlay_data` method, which simulates the sequential editing process on the provided `CassiopeiaTree`. The class also includes helper functions like `edit_site` and `silence_cassettes` to manage individual editing events and cassette silencing, respectively.

## References

* `cassiopeia.data.CassiopeiaTree`: The simulator operates on a `CassiopeiaTree` object, modifying its character states to represent the simulated lineage tracing data.
* `cassiopeia.simulator.LineageTracingDataSimulator`: This class inherits from the `LineageTracingDataSimulator` class, providing a framework for simulating lineage tracing data.

## Symbols

### `SequentialLineageTracingDataSimulator`

#### Description

This class simulates sequential Cas9-based lineage tracing data and overlays it onto a `CassiopeiaTree`. It models the sequential editing process on a "DNA tape" or "cassette" where only one site can be edited at a time.

#### Inputs

| Name                             | Type              | Description                                                                                        |
| :------------------------------- | :---------------- | :------------------------------------------------------------------------------------------------- |
| number\_of\_cassettes            | int               | Number of cassettes in the system.                                                                 |
| size\_of\_cassette               | int               | Number of editable target sites per cassette.                                                      |
| initiation\_rate                 | float             | Exponential parameter for the Cas9 initiation rate.                                                |
| continuation\_rate               | float             | Exponential parameter for the Cas9 continuation rate.                                              |
| state\_priors                    | Dict\[int, float] | Dictionary mapping states to their prior probabilities.                                            |
| heritable\_silencing\_rate       | float             | Silencing rate for the cassettes, simulating heritable missing data events.                        |
| stochastic\_silencing\_rate      | float             | Rate at which to randomly drop out cassettes, simulating dropout due to low sensitivity of assays. |
| heritable\_missing\_data\_state  | int               | Integer representing data that has gone missing due to a heritable event.                          |
| stochastic\_missing\_data\_state | int               | Integer representing data that has gone missing due to stochastic dropout.                         |
| random\_seed                     | Optional\[int]    | Numpy random seed for deterministic simulations.                                                   |

#### Outputs

This class doesn't directly return any output. It modifies the provided `CassiopeiaTree` in place.

#### Internal Logic

The simulator initializes a character matrix representing the cassettes and their states. It then iterates through each node in the tree, simulating the editing process based on the node's lineage and lifetime. For each cassette, it determines if it's initiated and simulates edits based on the continuation rate. It also applies heritable and stochastic silencing to the cassettes, mimicking real-world data variability. Finally, it updates the `CassiopeiaTree` with the simulated character matrix.

### `overlay_data`

#### Description

This method overlays the simulated Cas9-based lineage tracing data onto the provided `CassiopeiaTree`.

#### Inputs

| Name | Type           | Description                                                     |
| :--- | :------------- | :-------------------------------------------------------------- |
| tree | CassiopeiaTree | The `CassiopeiaTree` object to overlay the simulated data onto. |

#### Outputs

This method doesn't return any output. It modifies the input `CassiopeiaTree` in place.

#### Internal Logic

The method first initializes a character matrix with all sites set to an unedited state. It then traverses the tree in depth-first order. For each node, it simulates the Cas9 editing process based on the node's lifetime and the parent's character state. It then applies heritable and stochastic silencing to the character array. Finally, it updates the `CassiopeiaTree` with the simulated character matrix.

### `edit_site`

#### Description

This helper function edits a specific site in the character array based on the provided state priors.

#### Inputs

| Name             | Type              | Description                                             |
| :--------------- | :---------------- | :------------------------------------------------------ |
| character\_array | List\[int]        | The character array representing the cassette states.   |
| site             | int               | The index of the site to edit.                          |
| state\_priors    | Dict\[int, float] | Dictionary mapping states to their prior probabilities. |

#### Outputs

| Name             | Type       | Description                                       |
| :--------------- | :--------- | :------------------------------------------------ |
| character\_array | List\[int] | The updated character array with the edited site. |

#### Internal Logic

The function randomly samples a state from the state priors based on their probabilities and updates the character array at the specified site with the chosen state.

### `silence_cassettes`

#### Description

This helper function simulates the silencing of cassettes in the character array based on the provided silencing rate.

#### Inputs

| Name             | Type       | Description                                           |
| :--------------- | :--------- | :---------------------------------------------------- |
| character\_array | List\[int] | The character array representing the cassette states. |
| silencing\_rate  | float      | The probability of silencing a cassette.              |
| missing\_state   | int        | The state to use for representing silenced cassettes. |

#### Outputs

| Name                      | Type       | Description                                          |
| :------------------------ | :--------- | :--------------------------------------------------- |
| updated\_character\_array | List\[int] | The updated character array with silenced cassettes. |

#### Internal Logic

The function iterates through each cassette and, based on the silencing rate, randomly determines whether to silence it. If a cassette is silenced, all its sites in the character array are set to the specified missing state.