SISTEM

https://sistem.readthedocs.io/en/latest/
Admin
SISTEM is an open-source Python package for simulating tumor growth, metastasis, and DNA-seq data,...
Tokens:24,745
Snippets:163
Trust Score:8.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Initialize SISTEM Simulation Parameters

Source: https://sistem.readthedocs.io/en/latest/_sources/quickstart

Initializes the parameters for a SISTEM simulation. This involves setting various simulation variables like output directory, number of sites, detection thresholds, cell counts, and mutation rates. The `Parameters` class from the `sistem` library is used.

```python
from sistem import Parameters

params = Parameters(
    out_dir='example_out',
    nsites=3,
    epsilon=1e-9,
    min_detectable=5e5,
    capacities=1e7,
    focal_driver_rate=5e-4,
    SNV_pass_rate=0.01,
    alter_prop=0.3,
    ncells_prim=10000,
    ncells_meta=5000,
    ncells_normal=2000,
    min_mut_fraction=0.05,
    coverage=100
)
```

--------------------------------

### Initialize SISTEM Selection Library

Source: https://sistem.readthedocs.io/en/latest/_sources/quickstart

Initializes the selection library for SISTEM simulations. This can be done by directly passing parameters like chromosome lengths, arm ratios, region length, and max ploidy, or by using a pre-defined `Parameters` instance. The library defines the relative fitness of cells based on their genome. Imports include `RandomRegionLibrary` and `hg38_chrom_lengths_from_cytoband`.

```python
from sistem.selection import RandomRegionLibrary
from sistem.genome import hg38_chrom_lengths_from_cytoband

# Create a selection library by directly passing each parameter.
chrom_lens, arm_ratios = hg38_chrom_lengths_from_cytoband()
library = RandomRegionLibrary(
    chrom_lens=chrom_lens,
    arm_ratios=arm_ratios,
    region_len=5e6,
    max_ploidy=8,
)
# Initialize the selection coefficients
library.initialize(CN_coeff=0.1, OG_r=0.05, TSG_r=0.05)

# OR

# You can parameterize the selection library with just a Parameters instance.
library = RandomRegionLibrary(params=params)
library.initialize(params=params)
```

--------------------------------

### Simulate Clonal Lineage with SISTEM Python

Source: https://sistem.readthedocs.io/en/latest/_sources/quickstart

This snippet demonstrates loading a GrowthSimulator instance, sampling cells from primary and metastatic sites, and simulating a clonal lineage. It requires the 'sistem' library and outputs a tree object. Key parameters include passenger SNV rate and minimum mutation fraction for filtering.

```python
from sistem import load_gs
import os

# Assuming 'params' is defined elsewhere with necessary configuration
# params.out_dir = 'path/to/output'

# Load the saved GrowthSimulator instance, if applicable
gs = load_gs(os.path.join(params.out_dir, 'gs.pkl'))

# Begin by sampling cell
gs.sample_cells(
    ncells_prim=10000,
    ncells_meta=5000
)
# Or run gs.sample_cells(params=params)

# Call the lineage simulation method
tree = gs.simulate_clonal_lineage(
    out_dir='example_out',
    SNV_pass_rate=0.01,
    ncells_normal=2000,
    min_mut_fraction=0.05
)
# Or run gs.simulate_clonal_lineage(params=params)
```

--------------------------------

### Initialize Simulation Parameters with SISTEM

Source: https://sistem.readthedocs.io/en/latest/quickstart

Sets up the fundamental parameters for a SISTEM simulation. This includes defining output directory, number of anatomical sites, detection thresholds, cell population sizes, mutation rates, and sequencing coverage. These parameters control various aspects of the simulation, from tumor growth to data generation.

```python
from sistem import Parameters

params = Parameters(
    out_dir='example_out',
    nsites=3,
    epsilon=1e-9,
    min_detectable=5e5,
    capacities=1e7,
    focal_driver_rate=5e-4,
    SNV_pass_rate=0.01,
    alter_prop=0.3,
    ncells_prim=10000,
    ncells_meta=5000,
    ncells_normal=2000,
    min_mut_fraction=0.05,
    coverage=100
)

```

--------------------------------

### Initialize Static Migration Model in SISTEM

Source: https://sistem.readthedocs.io/en/latest/quickstart

Sets up a static anatomy model for simulating migration in SISTEM. This model defines the relationships between anatomical sites and is used to govern the movement of cells during the simulation, optionally incorporating organotropism priors or genotype-driven migration.

```python
from sistem.anatomy import StaticAnatomy

# Initialization code for StaticAnatomy would go here
# For example:
# anatomy = StaticAnatomy()

```

--------------------------------

### Initialize StaticAnatomy with Parameters Instance

Source: https://sistem.readthedocs.io/en/latest/quickstart

Initializes StaticAnatomy by passing a pre-configured Parameters instance, allowing for reusable configuration objects. Supports the same distance initialization and metastatic library creation methods as direct parameter passing.

```python
anatomy = StaticAnatomy(libraries=library, params=params)
anatomy.initialize_distances(method='random')
anatomy.create_random_metastatic_libraries(method='distance', params=params)
```

--------------------------------

### Sample Cells and Simulate Clonal Lineage with Passenger Mutations

Source: https://sistem.readthedocs.io/en/latest/quickstart

Loads a saved GrowthSimulator checkpoint, samples cells from primary and metastatic sites, and reconstructs clonal lineage with added passenger mutations. Generates clone trees and migration graphs from sampled populations, incorporating normal cells and applying mutation fraction thresholds for variant calling.

```python
from sistem import load_gs

gs = load_gs(os.path.join(params.out_dir, 'gs.pkl'))

gs.sample_cells(
    ncells_prim=10000,
    ncells_meta=5000
)

tree = gs.simulate_clonal_lineage(
    out_dir='example_out',
    SNV_pass_rate=0.01,
    ncells_normal=2000,
    min_mut_fraction=0.05
)
```

--------------------------------

### Examine Driver Regions and Selection Coefficients in SISTEM

Source: https://sistem.readthedocs.io/en/latest/_sources/quickstart

Iterates through the chromosome names and driver region IDs defined in the SISTEM parameters and library to print the corresponding selection coefficients. This provides insight into the evolutionary pressures acting on different genomic regions. The output is shown in a console format.

```python
for chrname in params.chrom_lens:
    for region_id in library.drivers[chrname]:
        print(chrname, region_id, library.delta[chrname][region_id])
```

```console
chr1 3 -0.07050650925424783
chr1 23 0.056907147220048596
chr1 41 -0.01553590386497552
chr1 48 0.07579778217001987
```

--------------------------------

### Run Agent-Based Growth Simulator (Python)

Source: https://sistem.readthedocs.io/en/latest/_sources/quickstart

Initializes and runs the agent-based growth simulator. This involves creating a GrowthSimulator instance with the initialized anatomy and then executing the simulate_agents method. Key parameters include maximum generations (t_max), minimum detectable population size (min_detectable), and driver mutation rates. It also supports saving checkpoints for reusing simulation results. Dependencies include 'os' and 'sistem.GrowthSimulator'.

```python
import os
from sistem import GrowthSimulator

# Initialize GrowthSimulator instance with the anatomy instance.
gs = GrowthSimulator(anatomy)

# Run the simulate_agents method
gs.simulate_agents(
    t_max=5000, 
    min_detectable=5e5, 
    focal_driver_rate=5e-4,
)

# Reminder: you can also specify parameters directly with:
# gs.simulate_agents(params=params)

# For some experiments, you may want to reuse the simulated populations/history,
# so its a good idea to create a checkpoint.
gs.save_checkpoint(os.path.join(params.out_dir, 'gs.pkl'))
```

--------------------------------

### Initialize StaticAnatomy with Direct Parameters

Source: https://sistem.readthedocs.io/en/latest/quickstart

Creates a StaticAnatomy instance by passing parameters directly for anatomical site configuration. Initializes inter-site distances and creates metastatic libraries using distance-based or random methods. Key parameters include number of sites (nsites), migration probability (epsilon), growth rate, and carrying capacity.

```python
anatomy = StaticAnatomy(
    libraries=library,
    nsites=3,
    epsilon=1e-8,
    growth_rate=0.005,
    capacities=1e7
)
anatomy.initialize_distances(method='random')
anatomy.create_random_metastatic_libraries(method='distance', alter_prop=0.3, CN_coeff=0.1)
```

--------------------------------

### Investigate Clonal Populations After Growth Simulation (Python)

Source: https://sistem.readthedocs.io/en/latest/_sources/quickstart

Prints information about clonal populations within each site after the growth simulation is complete. It iterates through each site, displaying the number of clones, number of cells, and the fitness of the least and most fit clones. This provides insights into the distribution and characteristics of cell populations across different anatomical sites.

```python
for s,clones in gs.clones.items():
    fits = [clone.fitness for clone in clones]
    print(f"Site {gs.anatomy.site_ids[s]}")
    print(f"Num clones: {len(clones)}, Num cells: {gs.site_counts[s]}, Least fit: {min(fits):.2f}, Most fit: {max(fits):.2f}")
    print()

```

--------------------------------

### Initialize Migration Model and Metastatic Landscapes (Python)

Source: https://sistem.readthedocs.io/en/latest/_sources/quickstart

Initializes the migration model using StaticAnatomy, defining organotropism priors and/or genotype-driven migrations. It allows for direct parameter passing or using a Parameters instance. The function sets up anatomical sites, migration probabilities, growth rates, carrying capacities, and creates metastatic libraries based on distance or random methods. Dependencies include the 'sistem.anatomy' module.

```python
from sistem.anatomy import StaticAnatomy

# Pass parameters directly.
anatomy = StaticAnatomy(
    libraries=library, 
    nsites=3,
    epsilon=1e-8,
    growth_rate=0.005,
    capacities=1e7
)
anatomy.initialize_distances(method='random') #method is random or precomputed
anatomy.create_random_metastatic_libraries(method='distance', alter_prop=0.3, CN_coeff=0.1) #method is random or distance

# Or pass a Parameters instance.
anatomy = StaticAnatomy(libraries=library, params=params)
anatomy.initialize_distances(method='random') #method is random or precomputed
anatomy.create_random_metastatic_libraries(method='distance', params=params) #method is random or distance
```

--------------------------------

### View Pairwise Site Distances (Python)

Source: https://sistem.readthedocs.io/en/latest/_sources/quickstart

Generates and prints a triangular distance matrix representing pairwise site distances, which act as organotropism priors. This is done after initializing the migration model and requires the 'numpy' library. The output is a 2D array where each element represents the distance between two sites.

```python
import numpy as np

dist_matrix = np.zeros((anatomy.nsites, anatomy.nsites))
dist_matrix[np.triu_indices(anatomy.nsites)] = anatomy.dists[:, 0]
print(dist_matrix)
```

--------------------------------

### Inspect Clonal Populations and Fitness Statistics

Source: https://sistem.readthedocs.io/en/latest/quickstart

Iterates through simulated clonal populations at each anatomical site to retrieve clone counts, total cell counts, and fitness statistics (minimum and maximum fitness values). Provides summary statistics for evaluating tumor heterogeneity and selection dynamics post-growth simulation.

```python
for s,clones in gs.clones.items():
    fits = [clone.fitness for clone in clones]
    print(f"Site {gs.anatomy.site_ids[s]}")
    print(f"Num clones: {len(clones)}, Num cells: {gs.site_counts[s]}, Least fit: {min(fits):.2f}, Most fit: {max(fits):.2f}")
    print()
```

--------------------------------

### Generate Bulk Read Counts with SISTEM Python

Source: https://sistem.readthedocs.io/en/latest/_sources/quickstart

This snippet shows how to generate bulk read count data after lineage simulation using the 'gen_readcounts_bulk' function from 'sistem.data'. It takes the simulated lineage tree and an output directory as input. The 'coverage' parameter controls sequencing depth.

```python
from sistem.data import gen_readcounts_bulk

# Assuming 'tree' is the output from gs.simulate_clonal_lineage
# and 'params' is defined elsewhere
# params.out_dir = 'path/to/output'

# Call the gen_readcounts_bulk function with the tree outputted from the previous
# step and any non-default parameters.
gen_readcounts_bulk(
    tree,
    out_dir='example_out',
    coverage=100
)
# Or run gen_readcounts_bulk(tree, params=params)
```

--------------------------------

### Print Driver Regions and Selection Coefficients

Source: https://sistem.readthedocs.io/en/latest/quickstart

Iterates through the initialized selection library to print the chromosome name, region ID, and corresponding selection coefficient for each driver region. This helps in understanding the genomic targets and their evolutionary impact within the simulation.

```python
for chrname in params.chrom_lens:
    for region_id in library.drivers[chrname]:
        print(chrname, region_id, library.delta[chrname][region_id])

```

--------------------------------

### Run Agent-Based Growth Simulator

Source: https://sistem.readthedocs.io/en/latest/quickstart

Initializes GrowthSimulator and executes the simulate_agents method to model tumor growth across anatomical sites over discrete generations. Simulates driver mutations (focal CNAs and SNVs) affecting fitness until reaching minimum population thresholds or maximum generation limit. Saves checkpoint for reuse in downstream analyses.

```python
import os
from sistem import GrowthSimulator

gs = GrowthSimulator(anatomy)

gs.simulate_agents(
    t_max=5000,
    min_detectable=5e5,
    focal_driver_rate=5e-4,
)

gs.save_checkpoint(os.path.join(params.out_dir, 'gs.pkl'))
```

--------------------------------

### Generate Read Counts for Bulk Sequencing with SISTEM

Source: https://sistem.readthedocs.io/en/latest/quickstart

This function generates read count data for bulk sequencing experiments. It takes the simulated tree, an output directory, and optional coverage parameters as input. The output consists of total and alternate read counts for each SNV.

```python
from sistem.data import gen_readcounts_bulk

# Call the gen_readcounts_bulk function with the tree outputted from the previous
# step and any non-default parameters.
gen_readcounts_bulk(
    tree,
    out_dir='example_out',
    coverage=100
)
# Or run gen_readcounts_bulk(tree, params=params)
```

--------------------------------

### Get Driver Start Regions in sistem.selection.BaseLibrary

Source: https://sistem.readthedocs.io/en/latest/selection

Abstract method to identify possible start region indices for a driver event. This method is crucial for modeling driver mutations and requires the current cell, chromosome, and the size of the event as input. It returns a list of possible start region indices.

```python
_get_driver_start_regions(_cell_ , _chromosome_ , _size_)
    
    Identifies the possible start region indices of a driver event. 

    Parameters:
        
      * **cell** (_Cell_) – The current cell.
      * **chromosome** (_Chromosome_) – The current chromosome.
      * **size** (_int_) – The size in number of regions of the event (1 for SNVs, >=1 for CNAs).
```

--------------------------------

### Initialize Selection Library for Tumor Growth Simulation

Source: https://sistem.readthedocs.io/en/latest/quickstart

Configures the selection library for an agent-based model, defining cell fitness based on genome. It can be initialized directly with genomic parameters like chromosome lengths and region sizes, or via a Parameters instance. Selection coefficients for driver genes (CN, OG, TSG) are set to determine replication and death probabilities.

```python
from sistem.selection import RandomRegionLibrary
from sistem.genome import hg38_chrom_lengths_from_cytoband

# Create a selection library by directly passing each parameter.
chrom_lens, arm_ratios = hg38_chrom_lengths_from_cytoband()
library = RandomRegionLibrary(
    chrom_lens=chrom_lens,
    arm_ratios=arm_ratios,
    region_len=5e6,
    max_ploidy=8,
)
library.initialize(CN_coeff=0.1, OG_r=0.05, TSG_r=0.05)

# OR

# Parameterize the selection library with a Parameters instance.
library = RandomRegionLibrary(params=params)
library.initialize(params=params)

```

--------------------------------

### Get Passenger Start Regions in sistem.selection.BaseLibrary

Source: https://sistem.readthedocs.io/en/latest/selection

Abstract method to identify possible start region indices for a passenger event. Similar to _get_driver_start_regions, this method is used for modeling passenger mutations and requires the cell, chromosome, and event size. It returns a list of potential start indices.

```python
_get_passenger_start_regions(_cell_ , _chromosome_ , _size_)
    
    Identifies the possible start region indices of a passenger event. 

    Parameters:
        
      * **cell** (_Cell_) – The current cell.
      * **chromosome** (_Chromosome_) – The current chromosome.
      * **size** (_int_) – The size in number of regions of the event (1 for SNVs, >=1 for CNAs).
```

--------------------------------

### Region Management

Source: https://sistem.readthedocs.io/en/latest/selection

This section details the parameters used for region management operations, including starting and ending indices, and magnitude for event types.

```APIDOC
## POST /api/regions

### Description
Creates or modifies a region based on the provided parameters.

### Method
POST

### Endpoint
/api/regions

### Parameters
#### Request Body
- **start** (int) - Required - The index of the starting region.
- **end** (int) - Required - The index of the ending region.
- **mag** (int) - Required - If the event is a CNA (start != end), then it is the number of copies being gained. If the event is an SNV (start == end), then it interprets an SNV being added in region start.

### Request Example
```json
{
  "start": 10,
  "end": 20,
  "mag": 5
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the operation.

#### Response Example
```json
{
  "message": "Region updated successfully."
}
```
```

--------------------------------

### Python: Simulate Clonal Lineage and Bulk Mutation Profiles

Source: https://sistem.readthedocs.io/en/latest/_sources/bulk_profiles

This Python script demonstrates how to simulate a clonal lineage and generate bulk mutation profiles using the Sistem library. It sets up simulation parameters, initializes selection and anatomy models, and runs the growth simulation. Key steps include creating a Parameters object, initializing RandomArmLibrary and GenotypeAnatomy, and running the GrowthSimulator. The output includes clone-level CNA and SNV profiles.

```python
import os
from sistem import Parameters, GrowthSimulator
from sistem.selection import RandomArmLibrary
from sistem.anatomy import GenotypeAnatomy

params = Parameters(
    out_dir='sim2_out', 
    nsites=3, 
    epsilon=1e-8, 
    min_detectable=5e5, 
    capacities=1e7, 
    focal_driver_rate=5e-4, 
    SNV_pass_rate=0.01, 
    alter_prop=0.3, 
    ncells_prim=10000, 
    ncells_meta=5000, 
    ncells_normal=2000, 
    min_mut_fraction=0.05,
    coverage=100
)

# Create a Library instance and initialize with random coefficients
library = RandomArmLibrary(params=params)
library.initialize(params=params)

# Create the Anatomy instance and initialize the distances.
anatomy = GenotypeAnatomy(library, params=params)
anatomy.initialize_distances()

# Now create the GrowthSimulator.
gs = GrowthSimulator(anatomy)

# Start the simulation. This may take ~20 minutes. You can monitor the sim.log file in real time.
gs.simulate_agents(params=params)
gs.save_checkpoint(os.path.join(params.out_dir, 'gs.pkl'))
gs.sample_cells(params=params)
tree = gs.simulate_clonal_lineage(params=params)

```

--------------------------------

### RandomArmLibrary.initialize()

Source: https://sistem.readthedocs.io/en/latest/selection

Initializes a RandomArmLibrary instance for random arm-based selection model simulations. This method sets up the library with default parameters for evolutionary dynamics modeling.

```APIDOC
## RandomArmLibrary.initialize()

### Description
Initializes a RandomArmLibrary instance for random arm-based selection model simulations.

### Method
Constructor/Initialization

### Class
RandomArmLibrary

### Parameters
None (uses default parameters)

### Returns
- **RandomArmLibrary** (object) - An initialized RandomArmLibrary instance ready for simulation

### Usage Example
```python
from sistem import RandomArmLibrary

library = RandomArmLibrary()
library.initialize()
```
```

--------------------------------

### Generate Bulk Profiles and Clone Tree with Sistem

Source: https://sistem.readthedocs.io/en/latest/bulk_profiles

This Python code simulates a clonal lineage and constructs bulk mutation profiles using the Sistem library. It requires the 'sistem' library and its submodules for selection and anatomy. The output includes clonal lineage trees, migration graphs, and bulk mutation profiles.

```python
import os
from sistem import Parameters, GrowthSimulator
from sistem.selection import RandomArmLibrary
from sistem.anatomy import GenotypeAnatomy

params = Parameters(
    out_dir='sim2_out',
    nsites=3,
    epsilon=1e-8,
    min_detectable=5e5,
    capacities=1e7,
    focal_driver_rate=5e-4,
    SNV_pass_rate=0.01,
    alter_prop=0.3,
    ncells_prim=10000,
    ncells_meta=5000,
    ncells_normal=2000,
    min_mut_fraction=0.05,
    coverage=100
)

# Create a Library instance and initialize with random coefficients
library = RandomArmLibrary(params=params)
library.initialize(params=params)

# Create the Anatomy instance and initialize the distances.
anatomy = GenotypeAnatomy(library, params=params)
anatomy.initialize_distances()

# Now create the GrowthSimulator.
gs = GrowthSimulator(anatomy)

# Start the simulation. This may take ~20 minutes. You can monitor the sim.log file in real time.
gs.simulate_agents(params=params)
gs.save_checkpoint(os.path.join(params.out_dir, 'gs.pkl'))
gs.sample_cells(params=params)
tree = gs.simulate_clonal_lineage(params=params)

```

--------------------------------

### FittedArmLibrary.initialize()

Source: https://sistem.readthedocs.io/en/latest/selection

Initializes a FittedArmLibrary instance for fitted arm-based selection model simulations. This library type uses pre-fitted parameters for more controlled evolutionary dynamics.

```APIDOC
## FittedArmLibrary.initialize()

### Description
Initializes a FittedArmLibrary instance with pre-fitted parameters for arm-based selection modeling.

### Method
Constructor/Initialization

### Class
FittedArmLibrary

### Parameters
None (uses pre-fitted default parameters)

### Returns
- **FittedArmLibrary** (object) - An initialized FittedArmLibrary instance with fitted parameters

### Usage Example
```python
from sistem import FittedArmLibrary

library = FittedArmLibrary()
library.initialize()
```
```

--------------------------------

### Simulate Migration Patterns and Analyze Frequencies (Python)

Source: https://sistem.readthedocs.io/en/latest/migration_history

This Python script simulates multi-site migration patterns using the 'sistem' library. It sets up simulation parameters, initializes selection libraries and anatomy, runs agent-based growth simulations, samples cells, and builds clonal lineages. Finally, it extracts migration patterns from generated graphs and counts their frequencies. Dependencies include 'os', 'collections.Counter', 'sistem', and 'get_migration_pattern'.

```python
import os
from collections import Counter
from sistem import Parameters, GrowthSimulator
from sistem.selection import RandomArmLibrary
from sistem.anatomy import StaticAnatomy

# will be using helper functions from get_migration_pattern.py
from get_migration_pattern import read_graph, get_pattern

# Set to the desired sample size and where all the simulations will be stored
num_sims = 1
sims_dir = 'sim3_out'
if not os.path.isdir(sims_dir):
    os.makedirs(sims_dir)

# Create the simulations and save in sims_dir/1, sims_dir/2, ...
for i in range(num_sims):
    cur_sim_dir = os.path.join(sims_dir, f'{i}')

    # Initialize parameters
    params = Parameters(
        out_dir = cur_sim_dir,
        nsites=5,
        epsilon=1e-8,
        min_detectable=5e5,
        capacities=5e6,
        focal_driver_rate=5e-4,
        alter_prop=0.2,
        ncells_prim=10000,
        ncells_meta=10000,
        min_mut_fraction=0.05
    )

    # Create a Library instance and initialize with random coefficients
    library = RandomArmLibrary(params=params)
    library.initialize(params=params)

    # Create the Anatomy instance, initialize the distances, and create site-specific libraries.
    anatomy = StaticAnatomy(library, params=params)
    anatomy.initialize_distances()
    anatomy.create_random_metastatic_libraries(method='distance', params=params)

    # Now create the Growth Simulator and start the simulation. This should take around 30 minutes.
    gs = GrowthSimulator(anatomy)
    gs.simulate_agents(params=params)

    # Sample cells and then build the clonal lineage and migration graph. This should only take a few minutes.
    gs.sample_cells(params=params)
    tree = gs.simulate_clonal_lineage(params=params)

# Now for each simulation we will use some helper functions to identify the pattern.
patterns = []
for i in range(num_sims):
    graph_path = os.path.join(sims_dir, f'{i}/migration_graph.tsv')
    g = read_graph(graph_path)
    p = get_pattern(g)
    patterns.append(p)

# And we can get the relative counts of each pattern as follows:
c = Counter(patterns)
for p,count in c.items():
    print(p, count)

```

--------------------------------

### BaseLibrary.initialize()

Source: https://sistem.readthedocs.io/en/latest/selection

Initializes the base library class with core functionality for evolutionary simulations. This is the parent class for all library types and provides essential methods for fitness computation, viability checking, and statistics tracking.

```APIDOC
## BaseLibrary.initialize()

### Description
Initializes the BaseLibrary instance with core simulation parameters and attributes.

### Method
Constructor/Initialization

### Class
BaseLibrary

### Parameters
None (uses default parameters)

### Returns
- **BaseLibrary** (object) - An initialized BaseLibrary instance

### Core Methods Available
- `is_driver_region_model` (property) - Check if using driver region model
- `is_driver_SNV_model` (property) - Check if using driver SNV model
- `check_viability()` - Verify cell viability
- `compute_fitness()` - Calculate fitness values
- `get_driver_start_regions()` - Retrieve driver starting regions
- `get_passenger_start_regions()` - Retrieve passenger starting regions
- `init_attributes()` - Initialize simulation attributes
- `init_base_fit()` - Initialize base fitness
- `init_max_fit()` - Initialize maximum fitness
- `update_stats()` - Update simulation statistics

### Usage Example
```python
from sistem import BaseLibrary

base_lib = BaseLibrary()
base_lib.initialize()
viable = base_lib.check_viability()
fitness = base_lib.compute_fitness()
```
```

--------------------------------

### Initialize Selection Coefficients in sistem.selection.BaseLibrary

Source: https://sistem.readthedocs.io/en/latest/selection

Method used to initialize selection coefficients within the BaseLibrary. This method serves as a template for how selection coefficients are set up, abstracting the specific details to subclasses. It takes optional keyword arguments.

```python
initialize(_params : Parameters | None = None_, _CN_coeff : float | None = None_, _SNV_coeff : float | None = None_, _OG_r : float | None = None_, _TSG_r : float | None = None_, _EG_r : float | None = None_)
    
    Method used to initialize selection coefficients. See Parameters for an explanation of the parameters. 

    Parameters:
        
      * **params** (_Parameters_ _,__optional_)
      * **CN_coeff** (_float_ _,__optional_)
      * **SNV_coeff** (_float_ _,__optional_)
      * **OG_r** (_float_ _,__optional_)
      * **TSG_r** (_float_ _,__optional_)
      * **EG_r** (_float_ _,__optional_)
```

--------------------------------

### Create SISTEM GrowthSimulator with random region library and anatomy

Source: https://sistem.readthedocs.io/en/latest/_sources/cell_lineage

Instantiates a RandomRegionLibrary with random coefficients, creates a SimpleAnatomy instance for single-site simulation, and initializes the GrowthSimulator for tumor growth simulation.

```python
# Create a Library instance and initialize with random coefficients
library = RandomRegionLibrary(params=params)
library.initialize(params=params)

# Create the Anatomy instance and then GrowthSimulator. No need to initialize distances using SimpleAnatomy.
anatomy = SimpleAnatomy(library, params=params)
gs = GrowthSimulator(anatomy)
```

--------------------------------

### FittedRegionLibrary Initialization - Python

Source: https://sistem.readthedocs.io/en/latest/selection

Initializes the FittedRegionLibrary with user-defined selection coefficients for genomic regions. Coefficients can be loaded from a file or provided as a dictionary.

```python
from sistem.selection import FittedRegionLibrary

# Initialize using a file path
# Assuming 'region_coeffs.tsv' exists and has the correct format
# filepath = 'region_coeffs.tsv'
# fitted_region_lib_file = FittedRegionLibrary(filepath=filepath)

# Initialize using a dictionary
delta_region_coeffs = {
    'chr1': [0.1, -0.2, 0.0, 0.15],
    'chr2': [-0.05, 0.1, 0.2, -0.1]
}
fitted_region_lib_dict = FittedRegionLibrary(delta=delta_region_coeffs)
```

--------------------------------

### GrowthSimulator Class Initialization and Attributes

Source: https://sistem.readthedocs.io/en/latest/growth_sim

Initializes the GrowthSimulator with an Anatomy object and provides access to simulation state attributes like clones, site counts, and generation.

```python
class GrowthSimulator(_anatomy_):
    """The main class used to run the simulator."""
    def __init__(self, anatomy: Anatomy):
        # ... initialization logic ...
        pass

    clones: Dict[list]  # A dictionary where keys are site numbers and values are lists of clones
    site_counts: array  # Contains the total cell count of each site
    gen: int  # The current generation of the simulator
```

--------------------------------

### Initialize Parameters in sistem.selection.BaseLibrary

Source: https://sistem.readthedocs.io/en/latest/selection

Abstract base class for selection libraries. This method is used to initialize selection coefficients and takes various optional parameters to configure the library's behavior, such as chromosome lengths, region lengths, and ploidy limits.

```python
_initialize(_** kwargs_)
    
    Function used to initialize the selection coefficients.
```

--------------------------------

### FittedArmLibrary Initialization - Python

Source: https://sistem.readthedocs.io/en/latest/selection

Initializes the FittedArmLibrary with user-defined selection coefficients for chromosome arms. Coefficients can be loaded from a file or provided as a dictionary.

```python
from sistem.selection import FittedArmLibrary
import pandas as pd

# Initialize using a file path
# Assuming 'selection_coeffs.tsv' exists and has the correct format
# filepath = 'selection_coeffs.tsv'
# fitted_arm_lib_file = FittedArmLibrary(filepath=filepath)

# Initialize using a dictionary
delta_coeffs = {
    'chr1': [0.1, -0.2],
    'chr2': [-0.05, 0.15]
}
fitted_arm_lib_dict = FittedArmLibrary(delta=delta_coeffs)
```

--------------------------------

### Define Simulation Parameters with Sistem.Parameters

Source: https://sistem.readthedocs.io/en/latest/parameters

The Parameters class in Sistem facilitates the configuration of simulation experiments by offering a centralized object for various parameters. It supports default values and allows for manual overrides, aiding in type checking and managing simulation settings.

```python
from sistem import Parameters

# Create a Parameters object with default values
params = Parameters()

# Example of overriding a default parameter
params.N0 = 50
params.growth_rate = 0.01

# Pass the parameters object to a simulation function (example)
# simulation_function(_params_=params)
```

--------------------------------

### RandomRegionLibrary Initialization - Python

Source: https://sistem.readthedocs.io/en/latest/selection

Initializes the RandomRegionLibrary with random selection coefficients for genomic regions. Allows specifying parameters, CN coefficient range, and ratios for OGs, TSGs, and EGs.

```python
from sistem.selection import RandomRegionLibrary

# Initialize with default parameters
random_region_lib = RandomRegionLibrary()

# Initialize with custom CN_coeff and ratios
random_region_lib_custom = RandomRegionLibrary(CN_coeff=0.3, OG_r=0.1, TSG_r=0.05, EG_r=0.01)

# Initialize using a Parameters object (assuming Parameters class is defined elsewhere)
# params = Parameters(...)
# random_region_lib_params = RandomRegionLibrary(params=params)
```

--------------------------------

### SISTEM Core API Features

Source: https://sistem.readthedocs.io/en/latest/selection

SISTEM provides comprehensive API features for tumor evolution simulation including migration models, growth and lineage simulation, DNA-seq read generation, and configurable parameters with default values and output file information.

```APIDOC
## SISTEM Core Features

### Description
Core functionality for evolutionary dynamics and tumor simulation modeling.

### Available Features

#### 1. Selection Models
Implement various selection mechanisms for evolutionary simulations
- Random-based selection (arm, region, hybrid)
- Fitted selection (arm, region, hybrid)
- Base library functionality

#### 2. Migration Models
Simulate cell migration patterns during tumor evolution

#### 3. Growth and Lineage Simulation
Model tumor growth dynamics and track cellular lineage relationships

#### 4. DNA-seq Reads/Counts
Generate synthetic DNA-seq data including:
- Read generation
- Count matrices
- Sequencing depth simulation

#### 5. Parameters and Defaults
Configurable simulation parameters with sensible defaults for:
- Fitness parameters
- Mutation rates
- Migration rates
- Growth rates

#### 6. Output File Information
Supported output formats and file handling for:
- Cell trees
- Clone trees
- Expression profiles
- Read alignments

### Quick Start
```python
from sistem import RandomArmLibrary

# Initialize simulation
library = RandomArmLibrary()
library.initialize()

# Access core functionality
fitness = library.compute_fitness()
driver_regions = library.get_driver_start_regions()
passenger_regions = library.get_passenger_start_regions()
```
```

--------------------------------

### Simulate and Analyze Migration Patterns using Python

Source: https://sistem.readthedocs.io/en/latest/_sources/migration_history

This Python script simulates biological migration patterns across multiple sites using the 'sistem' library. It initializes simulation parameters, creates anatomical structures and selection libraries, runs agent-based growth simulations, samples cells, builds clonal lineages, and extracts migration patterns from generated graphs. The script requires 'sistem', 'collections', and 'os' libraries, and helper functions from 'get_migration_pattern.py'. Outputs include simulation directories with migration graphs and a final count of identified migration patterns.

```python
import os
from collections import Counter
from sistem import Parameters, GrowthSimulator
from sistem.selection import RandomArmLibrary
from sistem.anatomy import StaticAnatomy

# will be using helper functions from get_migration_pattern.py
from get_migration_pattern import read_graph, get_pattern

# Set to the desired sample size and where all the simulations will be stored
num_sims = 1
sims_dir = 'sim3_out'
if not os.path.isdir(sims_dir):
    os.makedirs(sims_dir)

# Create the simulations and save in sims_dir/1, sims_dir/2, ...
for i in range(num_sims):
    cur_sim_dir = os.path.join(sims_dir, f'{i}')

    # Initialize parameters
    params = Parameters(
        out_dir = cur_sim_dir,
        nsites=5, 
        epsilon=1e-8, 
        min_detectable=5e5, 
        capacities=5e6,
        focal_driver_rate=5e-4, 
        alter_prop=0.2, 
        ncells_prim=10000, 
        ncells_meta=10000, 
        min_mut_fraction=0.05
    )

    # Create a Library instance and initialize with random coefficients
    library = RandomArmLibrary(params=params)
    library.initialize(params=params)

    # Create the Anatomy instance, initialize the distances, and create site-specific libraries.
    anatomy = StaticAnatomy(library, params=params)
    anatomy.initialize_distances()
    anatomy.create_random_metastatic_libraries(method='distance', params=params)

    # Now create the Growth Simulator and start the simulation. This should take around 30 minutes.
    gs = GrowthSimulator(anatomy)
    gs.simulate_agents(params=params)

    # Sample cells and then build the clonal lineage and migration graph. This should only take a few minutes.
    gs.sample_cells(params=params)
    tree = gs.simulate_clonal_lineage(params=params)

# Now for each simulation we will use some helper functions to identify the pattern.
patterns = []
for i in range(num_sims):
    graph_path = os.path.join(sims_dir, f'{i}/migration_graph.tsv')
    g = read_graph(graph_path)
    p = get_pattern(g)
    patterns.append(p)

# And we can get the relative counts of each pattern as follows:
c = Counter(patterns)
for p,count in c.items():
    print(p, count)
```

--------------------------------

### Initialize Clone Attributes in sistem.selection.BaseLibrary

Source: https://sistem.readthedocs.io/en/latest/selection

Abstract method to create and update an Attributes object for a clone, reflecting its current genome state. This is a preparatory step for fitness computations and other clone-specific analyses. It takes a Clone object as input.

```python
_init_attributes(_clone_)
    
    Creates an Attributes object for a clone and updates it to reflect its genome state. 

    Parameters:
        
    **clone** (_Clone_) – The clone object in question.
```
Tokens:
Raw