ssa {GillespieSSA}R Documentation

Invoking the stochastic simulation algorithm

Description

Main interface function to the implemented SSA methods. Runs a single realization of a predefined system.

Usage

            ssa( x0,        # initial state vector 
                  a,        # propensity vector
                 nu,        # state-change matrix
              parms = NULL, # model parameters
                 tf,        # final time 
             method = "D",  # SSA method 
            simName = "",      
                tau = 0.3,  # only applicable for ETL 
                  f = 10,   # only applicable for BTL
            epsilon = 0.03, # only applicable for OTL
                 nc = 10,   # only applicable for OTL
                hor = NaN,  # only applicable for OTL
                dtf = 10,   # only applicable for OTL
                 nd = 100,  # only applicable for OTL
ignoreNegativeState = TRUE, 
    consoleInterval = 0, 
     censusInterval = 0, 
            verbose = FALSE, 
        maxWallTime = Inf)

Arguments

x0 numerical vector of initial states where the component elements must be named using the same notation as the corresponding state variable in the propensity vector, a.
a character vector of propensity functions where state variables correspond to the names of the elements in x0.
nu numerical matrix of change if the number of individuals in each state (rows) caused by a single reaction of any given type (columns).
parms named vector of model parameters.
tf final time.
method text string indicating the SSA method to use, the valid options are: D — Direct method (default method), ETL - Explicit tau-leap, BTL — Binomial tau-leap, or OTL — Optimized tau-leap.
simName optional text string providing an arbitrary name/label for the simulation.
tau step size for the ETL method (>0).
f coarse-graining factor for the BTL method (>1) where a higher value results in larger step-size.
epsilon accuracy control parameter for the OTL method (>0).
nc critical firing threshold for the OTL method (positive integer).
hor numerical vector of the highest order reaction for each species where hor=(1,2,22). Setting hor=NaN uses the default hor=rep(22,N) where N is the number of species (See page 6 in Cao et al. 2006). Unless hor=NaN the number of elements must equal the number of states N. Only applicable in the OTL method.
dtf D method threshold factor for the OTL method. The OTL method is suspended if tau it estimates is smaller than the dtf multiple of the tau that the D method would have used (i.e. tau_OTL<dtf*tau_D) (See step 3, page 3 in Cao et al. 2006).
nd number of single-reaction steps performed using the Direct method during otl suspension (See step 3, page 3, Cao et al. 2006).
ignoreNegativeState boolean object indicating if negative state values should be ignored (this can occur in the etl method). If ignoreNegativeState=TRUE the simulation finishes gracefully when encountering a negative population size (i.e. does not throw an error). If ignoreNegativeState=FALSE the simulation stops with an error message when encountering a negative population size.
consoleInterval (approximate) interval at which ssa produces simulation status output on the console (assumes verbose=TRUE). If consoleInterval=0 console output is generated each time step (or tau-leap). If consoleInterval=Inf no console output is generated. Note, verbose=FALSE disables all console output. Console output drastically slows down simulations.
censusInterval (approximate) interval between recording the state of the system. If censusInterval=0 (t,x) is recorded at each time step (or tau-leap). If censusInterval=Inf only (t0,x0) and (tf,xf) is recorded. Note, the size of the time step (or tau-leaps) ultimatelly limits the interval between subsequent recordings of the system state since the state of the system cannot be recorded at a finer time interval the size of the time steps (or tau-leaps).
verbose boolean object indicating if the status of the simulation simulation should be displayed on the console. If verbose=TRUE the elapsed wall time and (t,x) is displayed on the console every consoleInterval time step and a brief summary is displayed at the end of the simulation. If verbose=FALSE the simulation runs entirely silent (overriding consoleInterval). Verbose runs drastically slows down simulations.
maxWallTime maximum wall time duration (in seconds) that the simulation is allowed to run for before terminated. This option is usefull, in particular, for systems that can end up growing uncontrolably.

Details

Although ssa can be invoked by only specifying the system arguments (initial state vector x0, propensity vector a, state-change matrix nu), the final time (tf), and the SSA method to use, substantial improvements in speed and accuracy can be obtained by adjusting the additional (and optional) ssa arguments. By default ssa (tries to) use conservative default values for the these arguments, prioritizing computational accuracy over computational speed. These default values are, however, not fool proof for the approzimate methods, and occasionally one will have to hand tweak them in order for a stochastic model to run appropriately.

Value

Returns a list object with the following elements,

data a numerical matrix object of the simulation time series where the first column is the time vector and subsequent columns are the state frequencies.
stats sub-list object with elements containing various simulation statistics. The of the sub-list are:
stats$startWallTime start wall clock time (YYYY-mm-dd HH:MM:SS).
stats$endWallTime end wall clock time (YYYY-mm-dd HH:MM:SS).
stats$elapsedWallTime elapsed wall time in seconds.
stats$terminationStatus string vector listing the reason(s) for the termination of the realization in 'plain words'. The possible termination statuses are: finalTime = if the simulation reached the maximum simulation time tf, extinction = if the population size of all states is zero, negativeState = if one or several states have a negative population size (can occur in the ETL method), zeroProp = if all the states have a zero propensity function, maxWallTime = if the maximum wall time has been reached. Note the termination status may have more than one message.
stats$nSteps total number of time steps (or tau-leaps) executed.
stats$meanStepSize mean step (or tau-leap) size.
stats$sdStepSize one standard deviation of the step (or tau-leap) size.
stats$SuspendedTauLeaps number of steps performed using the Direct method due to OTL suspension (only applicable for the OTL method).
arg$... sub-list with elements containing all the arguments and their values used to invoke ssa (see Usage and Arguments list above).

Preparing a run

In order to invoke SSA the stochastic model needs at least four components, the initial state vector (x0), state-change matrix (nu), propensity vector (a), and the final time of the simulation (tf). The initial state vector defines the population sizes in all the states at t=0, e.g. for a system with two species X1 and X2 where both have an initial population size of 1000 the initial state vector is defined as x0 <- c(X1=1000,X2=1000). The elements of the vector have to be labelled using the same notation as the state variables used in the propensity functions. The state-change matrix defines the change in the number of individuals in each state (rows) as caused by one reaction of a given type (columns). For example, the state-change matrix for system with the species S1 and S2 with two reactions

S1 –c1–> S2

S2 –c2–> 0

is defined as nu <- matrix(c(-1,0,+1,-1),nrow=2,byrow=TRUE) where c1 and c2 are the per capita reaction probabilities. The propensity vector, a, defines the probabilities that a particular reaction will occur over the next infinitesimal time interval [t,t+dt]. For example, in the previous example the propensity vector is defined as a <- c("c1*X1","c2*X2"). The propensity vector consists of character elements of each reaction's propensity function where each state variable requires the corresponding named element label in the initial state vector (x0).

Example: Irreversible isomerization

Perhaps the simplest model that can be formulated using the SSA is the irreversible isomerization (or radioactive decay) model. This model is often used as a first pedagogic example to illustrate the SSA (see e.g. Gillespie 1977). The deterministic formulation of this model is

dX/dt=-cX

where the single reaction channel is

S –c–> 0.

By setting X_0=1000 and c=0.5 it is now simple to define this model and run it for 10 time steps using the Direct method,

out <- ssa(x0=c(X=1000),a=c("c*X"),nu=matrix(-1),parms=c(c=0.5),tf=10)

The resulting time series can then be displayed by,

ssa.plot(out)

Note

Selecting the appropriate SSA method is a trade-off between computational speed, accuracy of the results, and which SSa actually works for a given scenario. This depends on the characteristics of the defined system (e.g. number of reaction channels, number of species, and the absolute and relative magnitude of the propensity functions). All methods are not appropriate for all models. When selecting a SSA method all of these factors have to be taken into consideration. The various tau-leap methods accept a number of additional arguments. While the default values of these arguments may work for some scenarios they may have to be adjusted for others. The default values for the tau-leap methods are conservative in terms of computational speed and substantial increase in efficiency may be gained by optimizing their values for a specific system.

Author(s)

Mario Pineda-Krch (http://pineda-krch/gillespiessa)

See Also

GillespieSSA-package, ssa.d, ssa.etl, ssa.btl, ssa.otl, ssa.plot

Examples

## Irreversible isomerization
## Large initial population size (X=1000)
## Not run: 
parms <- c(c=0.5)
x0  <- c(X=10000)
a   <- c("c*X")
nu  <- matrix(-1)
out <- ssa(x0,a,nu,parms,tf=10,simName="Irreversible isomerization") # Direct method
plot(out$data[,1],out$data[,2]/10000,col="red",cex=0.5,pch=19)
## End(Not run)

## Smaller initial population size (X=100)
## Not run: 
x0  <- c(X=100)
out <- ssa(x0,a,nu,parms,tf=10) # Direct method
points(out$data[,1],out$data[,2]/100,col="green",cex=0.5,pch=19)
## End(Not run)

## Small initial population size (X=10)
## Not run: 
x0  <- c(X=10)
out <- ssa(x0,a,nu,parms,tf=10) # Direct method
points(out$data[,1],out$data[,2]/10,col="blue",cex=0.5,pch=19)
## End(Not run)

## Logistic growth
## Not run: 
parms <- c(b=2, d=1, K=1000)
x0  <- c(N=500)
a   <- c("b*N", "(d+(b-d)*N/K)*N")
nu  <- matrix(c(+1,-1),ncol=2)
out <- ssa(x0,a,nu,parms,tf=10,method="D",maxWallTime=5,simName="Logistic growth")
ssa.plot(out)
## End(Not run)

## Kermack-McKendrick SIR model 
## Not run: 
parms <- c(beta=0.001, gamma=0.1)
x0  <- c(S=499,I=1,R=0)
a   <- c("beta*S*I","gamma*I") 
nu  <- matrix(c(-1,0,+1,-1,0,+1),nrow=3,byrow=TRUE)
out <- ssa(x0,a,nu,parms,tf=100,simName="SIR model")
ssa.plot(out)
## End(Not run)

## Lotka predator-prey model
## Not run: 
parms <- c(c1=10, c2=.01, c3=10)
x0  <- c(Y1=1000,Y2=1000)
a   <- c("c1*Y1","c2*Y1*Y2","c3*Y2")
nu  <- matrix(c(+1,-1,0,0,+1,-1),nrow=2,byrow=TRUE) 
out <- ssa(x0,a,nu,parms,tf=100,method="ETL",simName="Lotka predator-prey model")
ssa.plot(out)
## End(Not run)

[Package GillespieSSA version 0.5-3 Index]