Simulate Single-Cell Dynamics with Mutations

Source: R/dynamics_relevant_functions.R

Simulates cell population dynamics using a Gillespie algorithm, tracking births, deaths, transitions between cell types, and mutations on chromosomes. This function models cell growth with logistic constraints and generates detailed lineage information.

simulate_sc_dynamics(
  initial_population,
  max_steps,
  intrinsic_birth_rates,
  intrinsic_death_rates,
  edge_transition_rates,
  clone_capacity,
  chr_lengths,
  mutation_rate
)

Arguments

initial_population

Named numeric vector specifying the initial count for each clone type

max_steps

Maximum number of simulation steps to perform

intrinsic_birth_rates

Named numeric vector of birth rates for each clone type

intrinsic_death_rates

Named numeric vector of death rates for each clone type

edge_transition_rates

Data frame with columns: parent, child, rate - specifying transitions between clone types

clone_capacity

Numeric value representing the carrying capacity of the system of each clone

chr_lengths

Nested list structure defining chromosome lengths for each clone and haplotype

mutation_rate

Probability of mutation occurring during cell division

Value

A list containing:

  • population_history: Data frame tracking population counts over time

  • time_history: Vector of time points corresponding to population_history

  • cell_info: Data frame with detailed lineage information for each cell

  • mutation_info: Data frame recording mutation events that occurred during simulation

Details

The simulation implements a Gillespie algorithm with three possible events:

  1. Birth: A cell divides into two daughter cells with possible mutations

  2. Death: A cell dies and is removed from the population

  3. Transition: A cell changes from one clone type to another

Birth rates are modulated by logistic growth constraints based on total population and clone capacity. The simulation tracks detailed lineage information including parent-child relationships, birth and death times for each cell, and mutation events.

Note

The simulation stops when either max_steps is reached or the total event rate becomes zero.