plugins: Plug-ins for dynamical models based on stochastic Euler algorithms

Description

Plug-in facilities for implementing discrete-time Markov processes and continuous-time Markov processes using the Euler algorithm. These can be used in the rprocess and dprocess slots of pomp.

Usage

onestep.sim(step.fun, PACKAGE)
euler.sim(step.fun, delta.t, PACKAGE)
discrete.time.sim(step.fun, delta.t = 1, PACKAGE)
gillespie.sim(rate.fun, v, d, PACKAGE)
onestep.dens(dens.fun, PACKAGE)

Arguments

step.fun

This can be either an Rfunction or the name of a compiled, dynamically loaded native function containing the model simulator. It should be written to take a single Euler step from a single point in state space. If it is an Rfunction, it should be

rate.fun

This can be either an Rfunction or the name of a compiled, dynamically loaded native function that computes the transition rates. If it is an Rfunction, it should be of the form rate.fun(j,x,t,params,...). Here, j is the

v, d

Matrices that specify the continuous-time Markov process in terms of its elementary events. Each should have dimensions nvar x nevent, where nvar is the number of state variables and nevent is the nu

dens.fun

This can be either an R function or a compiled, dynamically loaded native function containing the model transition log probability density function. If it is an R function, it should be of the form dens.fun(x1,x2,t1,t2,params,...). He

delta.t

Size of Euler time-steps.

PACKAGE

an optional argument that specifies to which dynamically loaded library we restrict the search for the native routines. If this is base, we search in the R executable itself.

Value

onestep.sim, euler.sim, discrete.time.sim, and gillespie.sim each return functions suitable for use as the argument rprocess argument in pomp.
onestep.dens returns a function suitable for use as the argument dprocess in pomp.

Details

onestep.sim is the appropriate choice when it is possible to simulate the change in state from one time to another, regardless of how large the interval between them is. To use onestep.sim, you must write a function step.fun that will advance the state process from one arbitrary time to another. euler.sim is appropriate when one cannot do this but can compute the change in state via a sequence of smaller steps. This is desirable, for example, if one is simulating a continuous time process but is willing to approximate it using an Euler approach. discrete.time.sim is appropriate when the process evolves in discrete time. In this case, by default, the intervals between observations are integers.

To use euler.sim or discrete.time.sim, you must write a function step.fun that will take a single Euler step, of size at most delta.t. euler.sim and discrete.time.sim will create simulators that take as many steps as needed to get from one time to another. See below for information on how euler.sim chooses the actual step size it uses.

gillespie.sim allows exact simulation of a continuous-time, discrete-state Markov process using Gillespie's algorithm. This is an event-driven approach: correspondingly, to use gillespie.sim, you must write a function rate.fun that computes the rates of each elementary event and specify two matrices (d,v) that describe, respectively, the dependencies of each rate and the consequences of each event.

onestep.dens will generate a suitable dprocess function when one can compute the likelihood of a given state transition simply by knowing the states at two times under the assumption that the state has not changed between the times. This is typically possible, for instance, when the rprocess function is implemented using onestep.sim, euler.sim, or discrete.time.sim. [NB: currently, there are no high-level algorithms in pomp that use dprocess. This function is provided for completeness only, and with an eye toward future development.]

If step.fun is written as an Rfunction, it must have at least the arguments x, t, params, delta.t, and .... On a call to this function, x will be a named vector of state variables, t a scalar time, and params a named vector of parameters. The length of the Euler step will be delta.t. If the argument covars is included and a covariate table has been included in the pomp object, then on a call to this function, covars will be filled with the values, at time t, of the covariates. This is accomplished via interpolation of the covariate table. Additional arguments may be given: these will be filled by the correspondingly-named elements in the userdata slot of the pomp object (see pomp). If step.fun is written in a native language, it must be a function of type pomp_onestep_sim as specified in the header pomp.h included with the package (see the directory include in the installed package directory).

If rate.fun is written as an Rfunction, it must have at least the arguments j, x, t, params, and .... Here, j is the an integer that indicates which specific elementary event we desire the rate of. x is a named vector containing the value of the state process at time t, and params is a named vector containing parameters. If the argument covars is included and a covariate table has been included in the pomp object, then on a call to this function, covars will be filled with the values, at time t, of the covariates. This is accomplished via interpolation of the covariate table. If rate.fun is a native function, it must be of type pomp_ssa_rate_fn as defined in the header pomp.h, which is included with the package. In writing dens.fun, you must assume that no state transitions have occurred between t1 and t2. If dens.fun is written as an Rfunction, it must have at least the arguments x1, x2, t1, t2, params, and .... On a call to this function, x1 and x2 will be named vectors of state variables at times t1 and t2, respectively. The named vector params contains the parameters. If the argument covars is included and a covariate table has been included in the pomp object, then on a call to this function, covars will be filled with the values, at time t1, of the covariates. If the argument covars is included and a covariate table has been included in the pomp object, then on a call to this function, covars will be filled with the values, at time t1, of the covariates. This is accomplished via interpolation of the covariate table. As above, any additional arguments will be filled by the correspondingly-named elements in the userdata slot of the pomp object (see pomp). If dens.fun is written in a native language, it must be a function of type pomp_onestep_pdf as defined in the header pomp.h included with the package (see the directory include in the installed package directory).

Examples

Run this code

## examples showing how to use these functions
## are provided in the vignette "intro_to_pomp"
vignette("intro_to_pomp")