Reference Manual¶
-
class
casim.casim.
CancerSimulator
(parameters=None, seed=None, outdir=None)¶ Class CancerSimulator: Represents the Monte-Carlo simulation of cancer tumour growth on a 2D grid. Construct a new CancerSimulation.
Parameters: - parameters (CancerSimulationParameters) – The cancer simulation parameters
- seed (int) – The random seed.
- outdir ((str || path-like object)) – The directory where simulation data is saved. Default: “casim_out/” in the current working directory.
-
count_mutations
(mutation_list, get_frequencies)¶ Count number each time mutation is detected in the sample
Parameters: mutation_list (list of lists) – mutation profiles of each cell in the sample
-
death_step
(step)¶ Takes a group of random cells and kills them
Parameters: step (int) – The time step in the simulation
-
division
(cell, beneficial, neighbors, step, mutation_counter, pool)¶ Perform a cell division.
Parameters: - cell (tuple) – The mother cell coordinates.
- beneficial (bool) – Flag to indicate if the cell carries the beneficial mutation.
- neighbors (list) – The neighboring cells.
- step (int) – The time step in the simulation
- mutation_counter (int) – The counter of mutations to be updated
- pool (list) – The (temporary) pool of cells.
-
dump
()¶ Serialize the object. The current simulation will be stored in a machine readable format to <OUTDIR>/cancer_<SEED>/cancer_sim.py.dill, where <OUTDIR> is the specified output directory or (if the latter was not defined) a temporary directory.
-
export_histogram
(sample_data, sample_coordinates)¶ Create and export histogram of mutational frequencies (aka variant allelic frequencies)
Parameters: - sample_data (list) – List of mutations and their frequencies
- sample_coordinates (tuple (i,j) of cell indices) – coordinates of central sample cell
-
export_sample
(sample_data, sample_coordinates)¶ Export (write to disk) frequencies of samples.
Parameters: - sample_data (list) – List of mutations and their frequencies
- sample_coordinates (tuple (i,j) of cell indices) – coordinates of central sample cell
-
export_tumour_matrix
(tumour_mut_data)¶ Export (write to disk) the matrix of tumour cells.
Parameters: tumour_matrix (array like) – The tumour matrix to export
-
extend_sample
(sample_center, sample_size)¶ Takes a subset of cells from the tumour positioned around single input cell with specific coordinates. Output is a list of tuples of cells belonging to the sample. :param sample_center: coordinates of cell that will be center of the sample :type sample: tuple
Parameters: sample_size (float) – The size of the sample (fraction of total cells.)
-
increase_mut_number
(original_mut_list)¶ Scale up the number of mutations according to the ‘number_of_initial_mutations’ ‘and number_of_mutations_per_division’ parameter.
Parameters: solid_pre_vaf (list) – The list of mutations to scale.
-
mutation
(*args)¶ Perform a mutation.
Parameters: - cell – At which cell the mutation occurs
- neighbors – The neighboring cells
- mutation_counter – The current number of mutations, to be incremented.
- pool – The pool of all cells.
- place_to_divide – The position at which the mutation occurs.
- beneficial – Flag to control whether the mutation is beneficial or not.
-
mutation_reconstruction
(cells_to_reconstruct)¶ Reconstructs list of mutations of individual cell by going thorough its ancestors.
Parameters: cell (list of tuples [(i,j)] of cell indices.) – Cell for which mutational profile will be recovered.
-
neighbours
(cell)¶ Returns the nearest-neighbor cells around the given node.
Parameters: cell (tuple (i,j) of cell indices.) – The node for which to calculate the neighbors.
-
place_to_divide
()¶ Selects random unoccupied place on the matrix where cell will divide.
-
run
()¶ Run the simulation.
Returns: 0 if the run finishes successfully. After a successful run, simulation output and log will be written to the output directory <DIR>/cancer_<SEED>/simOutput and <DIR>/cancer_<SEED>/log, respectively. Simulation output is split into several files:
- mtx_VAF.txt is a datafile with three columns: mutation_id lists the index of each primary mutation, additional_mut_id indexes the subsequent mutations that occur in a cell of a given mutation_id; frequency is the frequency at which a given mutation occurs.
- sample_out_XXX_YYY.txt lists all mutations of the artificial sample taken from the whole tumour. Columns are identical to mtx_VAF.txt.
- wholeTumourVAFHistogram.pdf contains a histogram plot of the mutation frequencies for the whole tumour
- sampleHistogram_XXX_YYY.pdf is the mutation frequency histogram for the sampled portion of the tumour. The two numbers XXX and YYY are the positional coordinates (grid indices) in the tumour matrix.
- mtx.p is the serialized (aka “pickled”) 2D tumour matrix in sparse matrix format.
- mut_container.p is the serialized (aka “pickled”) mutation list, a list of tuples [t_i]. Each tuple t_i consists of two values, t_i = (c_i, m_i). The first element c_i is the cell number in which the i’th mutation occurs. The second element, m_i, is the mutation index m_i=i.
-
simulate_seq_depth
(extended_vaf)¶ Adds a beta binomial noise to sampled mutation frequencies
Parameters: extended_vaf (list) – The list of cells to take a sample from.
-
terminate_cell
(cell, step)¶ Kills cancer cell and removes it from the pool of cancer cells
Parameters: - cell (tuple (i,j) of cell indices.) – cell chosen for termination
- step (int) – The time step in the simulation
-
tumour_growth
()¶ Run the tumour growth simulation.
-
class
casim.casim.
CancerSimulatorParameters
(matrix_size=None, number_of_generations=None, division_probability=None, adv_mutant_division_probability=None, death_probability=None, adv_mutant_death_probability=None, mutation_probability=None, adv_mutant_mutation_probability=None, number_of_mutations_per_division=None, adv_mutation_wait_time=None, number_of_initial_mutations=None, tumour_multiplicity=None, read_depth=None, sampling_fraction=None, plot_tumour_growth=None, export_tumour=None, sampling_positions=None)¶ Class CancerSimulatorParameters: Represents the parameters for a cancer simulation. Construct a new CancerSimulationParameters object.
Parameters: - matrix_size (int (matrix_size > 0)) – The size of the (square) grid in each dimension.
- number_of_generations (int (number_of_generations > 0)) – The number of generations to simulate.
- division_probability (float (0.0 <= division_probability <= 1.0)) – The probability for a cell division to occur during one generation.
- adv_mutant_division_probability (float (0.0 <= adv_mutant_division_probability <= 1.0)) – The probability for the division of a cell with advantageous mutation to occur during one generation.
- death_probability (float (0.0 <= death_probability <= 1.0)) – The probability for a cell to die during one generation.
- adv_mutant_death_probability (float (0.0 <= adv_mutant_death_probability <= 1.0)) – The probability for a cell with advantageous mutation to die during one generation.
- mutation_probability (float (0.0 <= mutation_probability <= 1.0)) – The probability of mutation.
- adv_mutant_mutation_probability (float (0.0 <= adv_mutant_mutation_probability <= 1.0)) – The probability for a mutation to occur during one generation in a cell with adv. mutation.
- number_of_mutations_per_division (int (0 < number_of_mutations_per_division)) – The number of mutations per division
- adv_mutation_wait_time (int (adv_mutation_wait_time > 0)) – The number of generations into the simulation after which the advantageous mutation is inserted.
- number_of_initial_mutations (int (number_of_initial_mutations >= 0)) – Number of mutations present in first cancer cell.
- tumour_multiplicity (str) – Run in single or double tumour mode (i.e. consider growth of one single tumour or two tumours simultaneously). Possible values: “single”, “double”.
- read_depth (int (read_depth >= 0)) – The sequencing read depth (read length * number of reads / genome length). Default: 100.
- sampling_fraction (float (0 <= sampling_fraction <= 1)) – The fraction of cells to include in a sample. Default: 0.
- sampling_positions (List (or array) of tuples of ints. E.g. ([10,20], [2,31])) – The positions of cells to include in a sample. Default: Random position.
- plot_tumour_growth (bool) – Render graph of the tumour size as function of time. Default: True.
- export_tumour (bool) – Dump the tumour data to file. Default: True.
-
casim.casim.
check_set_number
(value, typ, default=None, minimum=None, maximum=None)¶ Checks if a value is instance of type and lies within permissive_range if given.
-
casim.casim.
load_cancer_simulation
(dumpfile)¶ Unpickle a cancer simulation from a dill generated dump.
Parameters: dumpfile (str) – Path to the file that contains the dumped object.
-
casim.casim.
main
(arguments)¶ The entry point for the command line interface.
Parameters: arguments (Namespace) – The command line arguments for the cancer simulation tool.