Plug-ins for state-process models

Share:

Description

The functions documented here can be used to specify the rprocess and dprocess slots for a pomp model. There are options for discrete- and continuous-time Markov processes.

Usage

1
2
3
4
5
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 R function, the name of a compiled, dynamically loaded native function containing the model simulator, or a Csnippet. The latter is the preferred option. It should be written to take a single Euler step from a single point in state space.

For an explanation and examples on the use of Csnippet to write fast simulators, see the tutorials on the package website.

If it is an R function, it should have prototype

step.fun(x,t,params,delta.t,...).

Here, x is a named numeric vector containing the value of the state process at time t, params is a named numeric vector containing parameters, and delta.t is the length of the Euler time-step.

If step.fun is the name of a native function, it must be of type

pomp_onestep_sim

as defined in the header file ‘pomp.h’, which is included with the pomp package. Do

file.show(system.file("include/pomp.h",package="pomp"))

to view this header file. For details on how to write such codes, see Details.

rate.fun

This can be either an R function, a Csnippet, or the name of a compiled, dynamically loaded native function that computes the transition rates. If it is an R function, it should be of the form rate.fun(j,x,t,params,...). Here, j is the number of the event, x is a named numeric vector containing the value of the state process at time t and params is a named numeric vector containing parameters.

For examples on the use of Csnippet to write fast simulators easily, see tutorials on the package website.

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. For details on how to write such codes, see Details.

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 number of elementary events. v describes the changes that occur in each elementary event: it will usually comprise the values 1, -1, and 0 according to whether a state variable is incremented, decremented, or unchanged in an elementary event. d is a binary matrix that describes the dependencies of elementary event rates on state variables: d[i,j] will have value 1 if event rate j must be updated as a result of a change in state variable i and 0 otherwise

dens.fun

This can be either an R function, a Csnippet, 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,...).

Here, x1 and x2 are named numeric vectors containing the values of the state process at times t1 and t2, params is a named numeric vector containing parameters.

If dens.fun is the name of a native function, it should be of type

pomp_onestep_pdf

as defined in the header ‘pomp.h’, which is included with the pomp package. This function should return the log likelihood of a transition from x1 at time t1 to x2 at time t2, assuming that no intervening transitions have occurred. For details on how to write such codes, see Details.

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. This argument is ignored if step.fun, rate.fn, or dens.fun is provided as an R function or a Csnippet.

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.

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. The functions 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 kind of 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, with an eye toward future development.]

If step.fun is written as an R function, 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 user-supplied 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

1
pomp_onestep_sim

as specified in the header ‘pomp.h’ included with the package. Execute

1
file.show(system.file("include/pomp.h",package="pomp.h"))

to view this file.

If rate.fun is written as an R function, it must have at least the arguments j, x, t, params, and .... Here, j is the an integer that indicates for which of the elementary events the current rate is desired. 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

1
pomp_ssa_rate_fn

as defined in the header ‘pomp.h’; see above for instructions on how to view this file.

In writing dens.fun, you must assume that no state transitions have occurred between t1 and t2. If dens.fun is written as an R function, 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

1
pomp_onestep_pdf

as defined in the header ‘pomp.h’ included with the package; see above for instructions on how to view this file.

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.

Author(s)

Aaron A. King kingaa at umich dot edu

See Also

pomp and the tutorials on the package website.

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.