Growth and lineage simulation

class sistem.GrowthSimulator(anatomy)

Bases: object

The main class used to run the simulator.

Parameters:

anatomy (Anatomy) – The Anatomy object which has been initialized. Required.

clones

A dictionary where keys are site numbers (0-nsites-1), and values are a list of clones currently present in the site.

Type:

Dict[list]

site_counts

Contains the total cell count of each site.

Type:

array

gen

The current generation of the simulator.

Type:

int

cycle_gen(params: Parameters | None = None, t_max: int | None = None, lifespan_mean: int | float | None = None, min_detectable: int | None = None, focal_driver_rate: float | None = None, arm_rate: float | None = None, chromosomal_rate: float | None = None, WGD_rate: float | None = None, focal_gain_rate: float | None = None, chrom_dup_rate: float | None = None, length_mean: int | float | None = None, mag_mean: int | float | None = None, SNV_driver_rate: float | None = None, log_path: str | None = None, pattern: str = '')

Identical to the simulate_agents method, but runs for a single generation only

sample_cells(params: Parameters | None = None, ncells_prim: int | None = None, ncells_meta: int | None = None)

Samples cells from each anatomical site. The probability that a cell is sampled from a clone is proportional to that clones population size. See Parameters for an explanation of the parameters.

Parameters:

  • params (Parameters, optional)

  • ncells_prim (int, optional)

  • ncells_meta (int, optional)

save_checkpoint(outfile)

Saves the growth simulator in its current state to a file.

Parameters:

outfile (str) – The location to save the growth simulator.

simulate_agents(params: Parameters | None = None, t_max: int | None = None, lifespan_mean: int | float | None = None, min_detectable: int | None = None, focal_driver_rate: float | None = None, arm_rate: float | None = None, chromosomal_rate: float | None = None, WGD_rate: float | None = None, focal_gain_rate: float | None = None, chrom_dup_rate: float | None = None, length_mean: int | float | None = None, mag_mean: int | float | None = None, SNV_driver_rate: float | None = None, log_path: str | None = None, pattern: str = '')

Begins the agent-based phase of the simulator. Runs until a minimum detectable number of cells is reached in each site, the max generation is reached, or no cells are left in any site. Only simulates driver mutations. See Parameters for an explanation of the parameters.

Parameters:

  • params (Parameters, optional)

  • t_max (int, optional)

  • lifespan_mean (int, float, optional)

  • min_detectable (int, optional)

  • focal_driver_rate (float, optional)

  • arm_rate (float, optional)

  • chromosomal_rate (float, optional)

  • WGD_rate (float, optional)

  • focal_gain_rate (float, optional)

  • chrom_dup_rate (float, optional)

  • length_mean (int, float, optional)

  • mag_mean (int, float, optional)

  • SNV_driver_rate (float, optional)

  • log_path (str, optional)

simulate_clonal_lineage(params: Parameters | None = None, out_dir: str | None = None, min_mut_fraction: float | None = None, focal_pass_rate: float | None = None, SNV_pass_rate: float | None = None, focal_gain_rate: float | None = None, length_mean: int | float | None = None, mag_mean: int | float | None = None, bin_size: int | None = None, ncells_normal: int | None = None, ref: str | None = None, alt_ref: str | None = None)

Construct a clonal lineage from the sampled cells and adds passenger mutations. Optionally prune the observed clones based on a minimum genotype frequency threshold. Requires running the sample_cells class method beforehand. Automatically saves the ground truth tree, migration graph, mutation history, CNA profiles, and SNV profiles. See Parameters for an explanation of the parameters.

Parameters:

  • params (Params, optional)

  • out_dir (str, optional)

  • min_mut_fraction (float, optional)

  • focal_pass_rate (float, optional)

  • SNV_pass_rate (float, optional)

  • focal_gain_rate (float, optional)

  • length_mean (int, float, optional)

  • mag_mean (int, float, optional)

  • bin_size (int, optional)

  • ncells_normal (int, optional)

  • ref (str, optional)

  • alt_ref (str, optional)

Returns:

The clonal lineage tree.

Return type:

Tree

simulate_singlecell_lineage(params: Parameters | None = None, out_dir: str | None = None, focal_pass_rate: float | None = None, SNV_pass_rate: float | None = None, focal_gain_rate: float | None = None, length_mean: int | float | None = None, mag_mean: int | float | None = None, bin_size: int | None = None, ncells_normal: int | None = None, ref: str | None = None, alt_ref: str | None = None)

Construct a single-cell lineage from the sampled cells under a coalescent, constrained to obey the underlying clonal evolutionary history, and add passenger mutations. Requires running the sample_cells class method beforehand. Automatically saves the ground truth tree, migration graph, mutation history, CNA profiles, and SNV profiles. See Parameters for an explanation of the parameters.

Parameters:

  • params (Params, optional)

  • out_dir (str, optional)

  • focal_pass_rate (float, optional)

  • SNV_pass_rate (float, optional)

  • focal_gain_rate (float, optional)

  • length_mean (int, float, optional)

  • mag_mean (int, float, optional)

  • bin_size (int, optional)

  • ncells_normal (int, optional)

  • ref (str, optional)

  • alt_ref (str, optional)

Returns:

The single-cell lineage tree.

Return type:

Tree