Simulating the cell evolution on a tissue — SpatialSimulation • rRACES

This class simulates the cell evolution on a tissue.

This method builds a new simulation.

Arguments

name: The name of the simulation (default: "races_<year>_<hour><minute><second>").
width: The width of the simulated tissue (default: 1000).
height: The height of the simulated tissue (default: 1000).
save_snapshots: A flag to save simulation snapshots on disk (default: FALSE).
seed: The seed for the pseudo-random generator (optional).

Details

The objects of this class can simulate the evolution of many cells belonging to different species on a tissue. Each cell can duplicate or die according to the rates that delineate the cell species.

Simulation supports epigenetic evolutions, and it lets users define species pairs that belong to the same mutant (even though, its genomic characterization is unknown) and differ because of their epigenetic state (i.e., either "+" or "-").

Simulation models epigenetic mutations and allows a cell in one of mutant species to generate a new cell belonging to the other species of the same mutant at a specified rate.

Simulation also allows users to schedule mutations from one mutant to a different mutant.

Fields

add_mutant

Adds a mutant and its species

Parameter: mutant - The mutant name.
Parameter: epigenetic_rates - The epigenetic rates of the mutant species (optional).
Parameter: growth_rates - The duplication rates of the mutant species.
Parameter: death_rates - The death rates of the mutant species.

choose_cell_in

Chooses one cell in a mutant

Parameter: mutant - The mutant of the cell to choose.
Parameter: lower_corner - The lower left corner of a rectangular selection (optional).
Parameter: upper_corner - The upper right corner of a rectangular selection (optional).
Returns: A list reporting "cell_id", "mutant", "epistate", "position_x", and "position_y" of the choosen cell.

death_activation_level

The number of cells that activates cell death in a species.

border_growth_model

Switch between homogeneous and border driven growth models.

get_added_cells

Gets the cells manually added to the simulation

Returns: A dataframe reporting "mutant", "epistate", "position_x", "position_y", and "time" for each cells manually added to the simulation.

search_sample

Seach a rectangular sample having a minimum number of cells

Parameter: mutant_name - The mutant of the searched cells.
Parameter: num_of_cells - The number of cells in the searched sample.
Parameter: width - The width of the searched sample.
Parameter: height - The height of the searched sample.
Returns: If a rectangular sample satisfying the provided constraints can be found, the corresponding rectangle.

get_cell

Gets one the tissue cells

Parameter: x - The position of the aimed cell on the x axis.
Parameter: y - The position of the aimed cell on the y axis.
Returns: A dataframe reporting "cell_id", "mutant", "epistate", "position_x", and "position_y" of the aimed cell.

get_cells

Gets the tissue cells

Parameter: lower_corner - The lower-left corner of the selection frame (optional).
Parameter: upper_corner - The upper-right corner of the selection frame (optional).
Parameter: mutant_filter - The vector of the to-be-selected mutant names (optional).
Parameter: epigenetic_filter - The vector of the to-be-selected epigenetic states (optional).
Returns: A dataframe reporting "cell_id", "mutant", "epistate", "position_x", and "position_y" for each cells satisfying the provided filters and laying in the input frame.

get_clock

Gets the simulated time

Returns: The time simulated by the simulation.

get_count_history

Gets the history of the number of cells per species

Returns: A dataframe reporting "mutant", "epistate", "counts", and "time" for each species and for each sampled time.

get_counts

Counts the number of cells per species

Returns: A dataframe reporting "mutant", "epistate", "counts", and "overall" for each species in the simulation.

get_firing_history

Gets the history of the number of fired events

Returns: A dataframe reporting "event", "mutant", "epistate", "fired", and "time" for each event type, for each species, and for each sampled time.

get_firings

Gets the number of fired events

Returns: A dataframe reporting "event", "mutant", "epistate", and "fired" for each event type and for each species.

get_name

Gets the simulation name

Returns: The simulation name, which corresponds to the name of the directory in which the simulation is saving its progresses.

get_lineage_graph

Gets the simulation lineage graph

Returns: A dataframe reporting "ancestor", "progeny", and "first_occurrence" of each species-to-species transition.

get_rates

Gets the rates of a species

Parameter: species - The species whose rates are aimed.
Returns: The list of the species names.

get_samples_forest

Get the samples forest

Returns: The descendants forest having as leaves the sampled cells.

get_samples_info

Retrieve information about the samples

Returns: A dataframe containing, for each sample collected during the simulation, the columns "name", "time", "ymin", "xmin", "ymax", "xmax", "tumour_cells", and "tumour_cells_in_bbox". The columns "ymin", "xmin", "ymax", "xmax" report the boundaries of the sample bounding box, while "tumour_cells" and "tumour_cells_in_bbox" are the number of tumour cells in the sample and in the bounding box, respectively.

get_species

Gets the species

Returns: A dataframe describing the registered species.

get_tissue_size

Gets the size of the simulated tissue

Returns: The vector c(x_size, y_size) of the simulated tissue.

mutate_progeny

Generate a mutated offspring

Parameter: cell_position - The position of the cell whose offspring will mutate.
Parameter: mutated_mutant - The mutant of the mutated cell.

Parameter: x - The position of the cell whose progeny will mutate on the x axis.
Parameter: y - The position of the cell whose progeny will mutate on the y axis.
Parameter: mutated_mutant - The mutant of the mutated cell.

place_cell

Place one cell in the tissue

Parameter: species - The name of the new cell species.
Parameter: x - The position on the x axis of the cell.
Parameter: y - The position on the y axis of the cell.

schedule_mutation

Schedules a mutant mutation

Parameter: src - The name of the mutant from which the mutation occurs.
Parameter: dest - The name of the mutant to which the mutation leads.
Parameter: time - The simulated time at which the mutation will occurs.

run_up_to_event

Simulates cell evolution

Parameter: event - The considered event type, i.e., "growth", "death", or "switch".
Parameter: species - The species whose event number is considered.
Parameter: num_of_events - The threshold for the event number.
Parameter: quiet - A Boolean flag to avoid progress bar (optional).

run_up_to_size

Simulates cell evolution

Parameter: species - The species whose number of cells is considered.
Parameter: num_of_cells - The threshold for the cell number.
Parameter: quiet - A Boolean flag to avoid progress bar (optional).

run_up_to_time

Simulates cell evolution

Parameter: time - The final simulation time.
Parameter: quiet - A Boolean flag to avoid progress bar (optional).

run_until

Simulating cell evolution

Parameter: formula - The formula that will be satisfied at the end of the simulation.
Parameter: quiet - A Boolean flag to avoid progress bar (optional).

sample_cells

Sample a tissue rectangle region

Parameter: name - The sample name.
Parameter: lower_corner - The bottom-left corner of the rectangle.
Parameter: upper_corner - The top-right corner of the rectangle.

update_rates

Updates the rates of a species

Parameter: species - The species whose rates must be updated.
Parameter: rates - The list of the rates to be updated.
Returns: The vector of the species names.

var

Builds a variable representing a simulation quantity

Parameter: variable_description - The description of the variable to be built.
Returns: A variable representing the simulation quantity according to the parameter variable_description.

Examples

# create a SpatialSimulation object storing binary dump in a temporary
# directory. The data are deleted from the disk as soon as the object
# is destroyed.
sim <- SpatialSimulation("test")

# add a new species, place a cell in the tissue, and let the simulation
# evolve.
sim$add_mutant(name = "A", growth_rate = 0.3, death_rate = 0.02)
sim$place_cell("A", 500, 500)
sim$run_up_to_time(30)
#> 
 [████████████████████████████████████████] 100% [00m:00s] Saving snapshot                                        


# no directory "test" has been created
"test" %in% list.files(".")
#> [1] FALSE

# By using the optional parameter `save_snapshots`, we force the
# simulation to save its progresses in a local directory whose name
# is the name of the simulation, i.e., "test". This data will be
# preserved when the simulation object will be destroyed.
sim <- SpatialSimulation("test", save_snapshots=TRUE)

# as done above, we add a new species, place a cell in the tissue,
# and let the simulation evolve.
sim$add_mutant(name = "A", growth_rate = 0.3, death_rate = 0.02)
sim$place_cell("A", 500, 500)
sim$run_up_to_time(30)
#> 
 [████████████████████████████████████████] 100% [00m:00s] Saving snapshot                                        


# the directory "test" exists and contains a binary dump of
# sthe simulation.
"test" %in% list.files(".")
#> [1] TRUE

# let us manually delete the "test" directory
unlink("test", recursive = TRUE)

# we can also provide a random seed to the simulation...
sim <- SpatialSimulation("test", seed=13)

# ...or creating a simulation without providing any name. By default, the
# simulation name will have the following format `races_<date>_<hour>`.
sim <- SpatialSimulation(seed=13)

# finally we can also specify the size of the simulated space
# by using the optional parameters `width` and `height`
sim <- SpatialSimulation(width=1200, height=900)