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.