CancerSim, including this README and the API reference manual
is hosted on readthedocs.
Cancer is a group of complex diseases characterized by excessive cell proliferation, invasion, and destruction of the surrounding tissue  . Its high division and mutation rates lead to excessive intratumour genetic heterogeneity which makes cancer highly adaptable to environmental pressures such as therapy  . This process is known as somatic evolution of cancer. Throughout most of its existence a tumour is inaccessible to direct observation and experimental evaluation. Therefore, computational modelling can be useful to study many aspects of cancer. Some examples where theoretical models can be of great use include early carcinogenesis, as lesions are clinically observable when they already contain millions of cells, seeding of metastases, and cancer cell dormancy  .
Statement of Need
Advanced cancer simulation software [@waclaw2015] often exhibit a prohibitively steep learning curve especially for new students in the field of somatic evolution of cancer. A software package that is accessible, simple to use, and yet covers the essential biological processes of cancer growth is needed to provide an entry point for students and newcomers to mathematical oncology.
Here, we present
CancerSim, a software that simulates somatic evolution
of tumours. The software produces virtual spatial tumours with variable
extent of intratumour genetic heterogeneity and realistic mutational
profiles. Simulated tumours can be subjected to multi-region sampling to
obtain mutation profiles that are realistic representation of the
sequencing data. This makes the software useful for studying various
sampling strategies in clinical cancer diagnostics. An early version of
this cancer evolution model was used to simulate tumours subjected to
sampling for classification of mutations based on their abundance
Cancer growth model
Our model is abstract, not specific to any neoplasm type, and does not consider a variety of biological features commonly found in neoplasm such as vasculature, immune contexture, availability of nutrients, and architecture of the tumour surroundings. It most closely resembles the superficially spreading tumours like carcinoma in situ, skin cancers, or gastric cancers, but it can be used to model any tumour on this abstract level.
The tumour is simulated using a two-dimensional, on-lattice, agent-based model. The tumour lattice structure is established by a sparse matrix whose non-zero elements correspond to the individual cells. Each cell is surrounded by eight neighbouring cells (Moore neighbourhood). The value of the matrix element is an index pointing to the last mutation the cell acquired in the list of mutations which is updated in each simulation step.
The simulation advances in discrete time-steps. In each simulation step,
every tumour cell in the tumour that has an unoccupied neighbour can
divide with a certain probability (set by the parameter
daughter cell resulting from a cell division inherits all mutations from
the parent cell and acquires a new mutation with a given probability
mutation_probability). A new mutation that changes death and birth probability of cell can be introduced
at into random cell at the specific time step defined by
By changing fitness parameters of a mutant cell
adv_mutant_death_probability one can model various evolutionary processes
like emergence of a faster dividing sub-clone or selective effects of a drug treatment.
The simulation allows the acquisition of more than one mutational event per cell
number_of_mutations_per_division). In that case, variable amounts of
sequencing noise  can be added to make
the output data more biologically realistic. The key parameters
determine the final size of the tumour, while the degree of intratumour heterogeneity can
be varied by changing the
For neutral tumour evolution, parameter
adv_mutant_death_probability must be the same as
Throughout the cancer growth phase,
CancerSim stores information about
the parent cell and a designation of newly acquired mutations for every
cell. Complete mutational profiles of cells are reconstructed a
posteriori based on the stored lineage information.
The division rules which allow only cells with empty neighbouring nodes
to divide, cause exclusively peripheral growth and complete absence of
dynamics in the tumour centre. To allow for variable degree of growth
inside the tumour, we introduced a death process. At every time step,
after all cells attempt their division, a number of random cells die according
yield their position to host a new cancer cell in a subsequent time
After the simulation, the tumour matrix, and the lists of lineages and frequencies of each mutation in the tumour are exported to files. Furthermore, the virtual tumour can be sampled and a histogram over the frequency of mutations will be visualised. Alternatively, a saved tumour can be loaded from file and then be subjected to the sampling process.
CancerSim is written in Python (version >3.5). We recommend to install
it directly from the source code. To download the code:
EITHER clone the repository:
$> git clone https://github.com/mpievolbio-scicomp/cancer_sim.git
OR download the source code archive:
$> wget https://github.com/mpievolbio-scicomp/cancer_sim/archive/master.zip $> unzip master.zip -d cancer_sim
Change into the source code directory
$> cd cancer_sim
We provide for two alternatives to install the software after it was downloaded:
New conda environment
We provide an
environment.yml to be consumed by
conda. To create a
fully self-contained conda environment (named
$> conda env create -n casim --file environment.yml
This will also install the cancer simulation code into the new environment.
To activate the new conda environment:
$> source activate casim
$> conda activate casim
if you have set up conda appropriately.
Install into existing and activated conda environment
To install the software into an already existing environment:
$> conda activate <name_of_existing_conda_environment> $> conda env update --file environment.yml
requirements.txt is meant to be consumed by
$> pip install -r requirements.txt [--user]
--user is needed to install without admin privileges.
CancerSim is available in python as the
E.g. in a python script, one would import the module as:
>>> from casim import casim
Although not strictly required, we recommend to run the test suite after
installation. Simply execute the
run_tests.sh shell script:
This will generate a test log named
<timestamp> being the date and time when the test was run. You should
OK at the bottom of the log. If instead errors or failures are
reported, something is wrong with the installation or the code itself.
Feel free to open a github issue at
https://github.com/mpievolbio-scicomp/cancer_sim/issues and attach the
test log plus any information that may be useful to reproduce the error
(version hash, computer hardware, operating system, python version, a
conda env export if applicable).
The test suite is automatically run after each commit to the code base. Results are published on travis-ci.org.
Setting the simulation parameters
The parameters of the cancer simulation are specified in a python module or
programmatically via the
CancerSimulationParameters class. A
params.py is included in the source code (under
casim/params.py) and reproduced here:
$> cat casim/params.py ################################################################################ # # # Commented casim parameter input file. # # Valid settings are indicated in parentheses at the end of each comment line. # # [0,1] stands for the closed interval from 0 to 1, including the limits; || # # means "or". # # # ################################################################################ # Number of mesh points in each dimension (>0) matrix_size = 1000 # Number of generations to simulate (>0). number_of_generations = 20 # Probability of cell division per generation ([0,1]). division_probability = 1 # Probability of division for cells with advantageous mutation ([0,1]). adv_mutant_division_probability = 1 # Fraction of cells that die per generation ([0,1]). death_probability = 0.1 # Fraction of cells with advantageous mutation that die per generation ([0,1]). adv_mutant_death_probability = 0.0 # Probability of mutations ([0,1]). mutation_probability = 1 # Mutation probability for the adv. cells ([0,1]). adv_mutant_mutation_probability = 1 # Number of mutations per cell division (>=0). number_of_mutations_per_division = 10 # Number of generations after which the beneficial mutation occurs (>=1). adv_mutation_wait_time = 10 # Number of mutations present in first cancer cell (>=0). number_of_initial_mutations = 150 # Tumour multiplicity ("single" || "double"). tumour_multiplicity = "single" # Sequencing read depth (read length * number of reads / genome length). read_depth = 100 # Fraction of cells to be sampled ([0,1]). sampling_fraction = 0.1 # Sampling position (list of (x,y) coordinates in the range [0,matrix_size-1]). # If left blank or None, random position will be chosen. # sampling_positions = None # This will randomly set a single sampling position. sampling_positions = [(500,500),(490,490)] # Plot the tumour growth curve (True || False). plot_tumour_growth = True # Export the tumour growth data to file (True || False). export_tumour = True
Here, we simulate a single 2D tumour on a 1000x1000 grid (
matrix_size=1000) for a total of
20 generations (
On average, both healthy and mutant cells divide once per generation
division_probability). The first cancer cell carries 150 mutations
number_of_initial_mutations=150); both healthy and mutant cells aquire 10 new
each generation with a certainty of 100% (
mutation_probability=1). The advantageous mutation happens in
the 10th generation (
adv_mutation_wait_time=10). Mutant cells with advantageous mutations live on forever
adv_mutant_death_probability=0) while healthy cells die with a rate of 0.1
per generation (
After completion of the last generation, two spatial samples are taken, one from the tumour center and one from a
slightly more lateral
sampling_positions = [(500,500),(490,490)]). Each sample contains 10% (with respect to the whole tumour size)
closely positioned tumour cells
sampling_fraction=0.1). The samples are subject to genetic sequencing with a read depth
of 100 (
read_depth=100). The data is written to disk (
and plots showing the mutation histograms for the whole tumour as well as for the sampled part of the
tumour are generated. Furthermore, a plot showing the tumour growth over time is
Users should start with the template and adjust the parameters as needed for their application by setting experimentally or theoretically known values or by calibrating the simulation output against experiments or other models.
Run the example
The simulation is started from the command line. The syntax is
$> python -m casim.casim [-h] [-s SEED] [-p PARAMS] [-o DIR]
SEED is the random seed. Using the
same seed in two simulation runs with identical parameters results in
identical results. If not given,
SEED defaults to 1.
PARAMS should point to
a python parameter file. If not given, it defaults to
params.py in the current
working directory. If that file does not exist, default parameters are assumed.
DIR specifies the directory where to store the
simulation log and output data. If not given, output will be stored in
casim_out in the current directory. For each seed, a
cancer_SEED will be created. If that subdirectory already
exists because an earlier run used the same seed, the run will abort.
This is a safety catch to avoid overwriting data from previous runs.
After the run has finished, you should find the results in the specified output directory:
$> ls out/cancer_1/simOutput growthCurve.pdf mut_container.p sample_out_490_490.txt mtx.p sampleHistogram_490_490.pdf sample_out_500_500.txt mtx_VAF.txt sampleHistogram_500_500.pdf wholeTumourVAFHistogram.pdf
Let's take a look at the
.txt files. They contain the simulation output:
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
frequency is the frequency which at a given mutation occurs.
Corresponding to the given sample positions, there is one
sample_out_XXX_YYY.txt and one
sampleHistogram_XXX_YYY.pdf for each
.txt filel lists all mutations of the artificial sample
taken from the whole tumour. Columns are identical to
wholeTumourVAFHistogram.pdf is the histogram for the
complete tumour. You should see figures similar to these:
The remaining output files are serialized versions ("pickles") of the tumour
geometry as a 2D matrix (
mtx.p) and the
mutation list (list of tuples listing the cancer cell index and the mutation ID of each
An example demonstrating how to parametrize the simulation through the
CancerSimulationParameters API is provided in the accompanying jupyter notebook at
quickstart_example.ipynb`. Launch it in
demonstrate how to use the restart capability to modifiy tumour growth parameters in the
middle of a run. In this way, one can model different phases of tumour growth,
e.g. tumour dormancy or onset of cancer therapy.
As an Open Source project, we welcome all contributions to
recommend the usual github workflow: Fork this repository, commit
your changes and additions to the fork and create a pull request back to the
master branch on this repository. If uncertain about anything, please create an
issue at https://github.com/mpievolbio-scicomp/cancer_sim/issues.
Comments, bug reports, or other issues as well as requests for support should be submitted as a github issue. Please check the list of issues if your problem has already been addressed. We will do our best to respond in a timely manner.
 S. Turajlic, A. Sottoriva, T. Graham, and C. Swanton, Nat Rev Genet (2019). DOI: 10.1038/s41576-019-0114-6
 P. M. Altrock, L. L. Liu, and F. Michor, Nat Rev Cancer 15, 730 (2015). DOI: 10.1038/nrc4029
 L. Opasic, D. Zhou, B. Werner, D. Dingli, and A. Traulsen, BMC Cancer 19, 403 (2019). DOI: 10.1186/s12885-019-5597-1
 B. Waclaw, I. Bozic, M. E. Pittman, R. H. Hruban, B. Vogelstein, and M. A. Nowak, Nature 525, 261 (2015). DOI: 10.1038/nature14971
 M. J. Williams, B. Werner, C. P. Barnes, T. A. Graham, and A. Sottoriva, Nature Genetics 48, 238 (2016). DOI: 10.1038/ng.3489