Simulate a gene regulatory circuit — sracipeSimulate • sRACIPE
Description: Simulate a gene regulatory circuit using its topology as the only input. It will generate an ensemble of random models.

# Simulate a gene regulatory circuit

Source: `R/simulateGRC.R`
`sracipeSimulate.Rd`

Simulate a gene regulatory circuit using its topology as the only input. It will generate an ensemble of random models.

    sracipeSimulate(
      circuit = "inputs/test.tpo",
      config = config,
      anneal = FALSE,
      knockOut = NA_character_,
      numModels = 2000,
      paramRange = 100,
      prodRateMin = 1,
      prodRateMax = 100,
      degRateMin = 0.1,
      degRateMax = 1,
      foldChangeMin = 1,
      foldChangeMax = 100,
      hillCoeffMin = 1L,
      hillCoeffMax = 6L,
      integrateStepSize = 0.02,
      simulationTime = 50,
      nIC = 1L,
      nNoise = 0L,
      simDet = TRUE,
      initialNoise = 50,
      noiseScalingFactor = 0.5,
      shotNoise = 0,
      scaledNoise = FALSE,
      outputPrecision = 12L,
      printStart = 50,
      printInterval = 10,
      stepper = "RK4",
      thresholdModels = 5000,
      plots = FALSE,
      plotToFile = FALSE,
      genIC = TRUE,
      genParams = TRUE,
      integrate = TRUE,
      rkTolerance = 0.01,
      timeSeries = FALSE,
      nCores = 1L,
      ...
    )

## Arguments

circuit | data.frame or character. The file containing the circuit or
config | (optional) List. It contains simulation parameters like integration method (stepper) and other lists or vectors like simParams, stochParams, hyperParams, options, thresholds etc. The list simParams contains values for parameters like the number of models (numModels), simulation time (simulationTime), step size for simulations (integrateStepSize), when to start recording the gene expressions (printStart), time interval between recordings (printInterval), number of initial conditions (nIC), output precision (outputPrecision), tolerance for adaptive runge kutta method (rkTolerance), parametric variation (paramRange). The list stochParams contains the parameters for stochastic simulations like the number of noise levels to be simulated (nNoise), the ratio of subsequent noise levels (noiseScalingFactor), maximum noise (initialNoise), whether to use same noise for all genes or to scale it as per the median expression of the genes (scaledNoise), ratio of shot noise to additive noise (shotNoise). The list hyperParams contains the parameters like the minimum and maximum production and degration of the genes, fold change, hill coefficient etc. The list options includes logical values like annealing (anneal), scaling of noise (scaledNoise), generation of new initial conditions (genIC), parameters (genParams) and whether to integrate or not (integrate). The user modifiable simulation options can be specified as other arguments. This list should be used if one wants to modify many settings for multiple simulations.
anneal | (optional) Logical. Default FALSE. Whether to use annealing for stochastic simulations. If TRUE, the gene expressions at higher noise are used as initial conditions for simulations at lower noise.
knockOut | (optional) List of character or vector of characters. Simulation after knocking out one or more genes. To knock out all the genes in the circuit, use `knockOut = "all"`. If it is a vector, then all the genes in the vector will be knocked out simultaneously.
numModels | (optional) Integer. Default 2000. Number of random models to be simulated.
paramRange | (optional) numeric (0-100). Default 100. The relative range of parameters (production rate, degradation rate, fold change).
prodRateMin | (optional) numeric. Default 1. Minimum production rate.
prodRateMax | (optional) numeric. Default 100. Maximum production rate.
degRateMin | (optional) numeric. Default 0.1. Minimum degradation rate.
degRateMax | (optional) numeric. Default 1. Maximum degradation rate.
foldChangeMin | (optional) numeric. Default 1. Minimum fold change for interactions.
foldChangeMax | (optional) numeric. Default 100. Maximum fold change for interactions.
hillCoeffMin | (optional) integer. Default 1. Minimum hill coefficient.
hillCoeffMax | (optional) integer. Default 6. Maximum hill coefficient.
integrateStepSize | (optional) numeric. Default 0.02. step size for integration using "EM" and "RK4" steppers.
simulationTime | (optional) numeric. Total simulation time.
nIC | (optional) integer. Default 1. Number of initial conditions to be simulated for each model.
nNoise | (optional) integer. Default 0. Number of noise levels at which simulations are to be done. Use nNoise = 1 if simulations are to be carried out at a specific noise. If nNoise > 0, simulations will be carried out at nNoise levels as well as for zero noise. "EM" stepper will be used for simulations and any argument for stepper will be ignoired.
simDet | (optional) logical. Default TRUE. Whether to simulate at zero noise as well also when using nNoise > 0.
initialNoise | (optional) numeric. Default 50/sqrt(number of genes in the circuit). The initial value of noise for simulations. The noise value will decrease by a factor `noiseScalingFactor` at subsequent noise levels.
noiseScalingFactor | (optional) numeric (0-1) Default 0.5. The factor by which noise will be decreased when nNoise > 1.
shotNoise | (optional) numeric. Default 0. The ratio of shot noise to additive noise.
scaledNoise | (optional) logical. Default FALSE. Whether to scale the noise in each gene by its expected median expression across all models. If TRUE the noise in each gene will be proportional to its expression levels.
outputPrecision | (optional) integer. Default 12. The decimal point precison of the output.
printStart | (optional) numeric (0-`simulationTime`). Default `simulationTime`. To be used only when `timeSeries` is `TRUE`. The time from which the output should be recorded. Useful for time series analysis and studying the dynamics of a model for a particular initial condition.
printInterval | (optional) numeric (`integrateStepSize`- `simulationTime - printStart`). Default 10. The separation between two recorded time points for a given trajectory. To be used only when `timeSeries` is `TRUE`.
stepper | (optional) Character. Stepper to be used for integrating the differential equations. The options include `"EM"` for Euler-Maruyama O(1), `"RK4"` for fourth order Runge-Kutta O(4) and `"DP"` for adaptive stepper based Dormand-Prince algorithm. The default method is `"RK4"` for deterministic simulations and the method defaults to `"EM"` for stochastic simulations.
thresholdModels | (optional) integer. Default 5000. The number of models to be used for calculating the thresholds for genes.
plots | (optional) logical Default `FALSE`. Whether to plot the simuated data.
plotToFile | (optional) Default `FALSE`. Whether to save the plots to a file.
genIC | (optional) logical. Default `TRUE`. Whether to generate the initial conditions. If `FALSE`, the initial conditions must be supplied as a dataframe to `circuit$ic`.
genParams | (optional) logical. Default `TRUE`. Whether to generate the parameters. If `FALSE`, the parameters must be supplied as a dataframe to `circuit$params`.
integrate | (optional) logical. Default `TRUE`. Whether to integrate the differential equations or not. If `FALSE`, the function will only generate the parameters and initial conditions. This can be used iteratively as one can fist generate the parameters and initial conditions and then modify these before using these modified values for integration. For example, this can be used to knockOut genes by changing the production rate and initial condition to zero.
rkTolerance | (optional) numeric. Default `0.01`. Error tolerance for adaptive integration method.
timeSeries | (optional) logical. Default `FALSE`. Whether to generate time series for a single model instead of performing RACIPE simulations.
nCores | (optional) integer. Default `1` Number of cores to be used for computation. Utilizes `multiprocess` from doFuture pacakge. Will not work in Rstudio.
... | Other arguments

## Value

`RacipeSE` object. RacipeSE class inherits `SummarizedExperiment` and contains the circuit, parameters, initial conditions, simulated gene expressions, and simulation configuration. These can be accessed using correponding getters.

## Related Functions

`sracipeSimulate`, `sracipeKnockDown`, `sracipeOverExp`, `sracipePlotData`

## Examples

    data("demoCircuit")
    rSet <- sRACIPE::sracipeSimulate(circuit = demoCircuit)#> circuit file successfully loaded#> Generating gene thresholds#> generating thresholds for uniform distribution1...
    #> ========================================