This function constructs a pomp
object,
encoding a partiallyobserved Markov process model together with a uni or multivariate time series.
One implements the model by specifying its components, each of which can be written as R functions or, for much greater computational efficiency, using C code.
The preferred way to specify most components (as detailed below) is through the use of Csnippet
s, snippets of C that are compiled and linked into a running R session.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27  ## S4 method for signature 'data.frame'
pomp(data, times, t0, ..., rprocess, dprocess, rmeasure, dmeasure,
measurement.model,
skeleton, skeleton.type = c("map","vectorfield"), skelmap.delta.t = 1,
initializer, rprior, dprior, params, covar, tcovar,
obsnames, statenames, paramnames, covarnames, zeronames,
PACKAGE, fromEstimationScale, toEstimationScale, globals)
## S4 method for signature 'numeric'
pomp(data, times, t0, ..., rprocess, dprocess, rmeasure, dmeasure,
measurement.model,
skeleton, skeleton.type = c("map","vectorfield"), skelmap.delta.t = 1,
initializer, rprior, dprior, params, covar, tcovar,
obsnames, statenames, paramnames, covarnames, zeronames,
PACKAGE, fromEstimationScale, toEstimationScale, globals)
## S4 method for signature 'matrix'
pomp(data, times, t0, ..., rprocess, dprocess, rmeasure, dmeasure,
measurement.model,
skeleton, skeleton.type = c("map","vectorfield"), skelmap.delta.t = 1,
initializer, rprior, dprior, params, covar, tcovar,
obsnames, statenames, paramnames, covarnames, zeronames,
PACKAGE, fromEstimationScale, toEstimationScale, globals)
## S4 method for signature 'pomp'
pomp(data, times, t0, ..., rprocess, dprocess, rmeasure, dmeasure,
measurement.model, skeleton, skeleton.type, skelmap.delta.t,
initializer, rprior, dprior, params, covar, tcovar,
obsnames, statenames, paramnames, covarnames, zeronames,
PACKAGE, fromEstimationScale, toEstimationScale, globals)

data, times 
The time series data and times at which observations are made.
If If If

t0 
The zerotime, at which the stochastic dynamical system is to be initialized.
This must be no later than the time of the first observation, i.e., 
rprocess 
optional function; a function of prototype rprocess(xstart,times,params,\dots) that simulates from the unobserved process.
The form of this function is given below.
pomp provides a number of 
dprocess 
optional function; a function of prototype dprocess(x,times,params,log,\dots) that evaluates the likelihood of a sequence of consecutive state transitions.
The form of this function is given below.
It is not typically necessary (or even feasible) to define 
rmeasure 
optional; the measurement model simulator. This can be specified in one of four ways:

dmeasure 
optional; the measurement model probability density function. This can be specified in one of four ways:
The last is typically the preferred option, as it results in much faster code execution.
As might be expected, if 
measurement.model 
optional; a formula or list of formulae, specifying the measurement model.
These formulae are parsed internally to generate 
skeleton, skeleton.type, skelmap.delta.t 
The function The skeleton function can be specified in one of three ways:

initializer 
The initializer gives the parameterization of the initial state of the unobserved Markov process.
Specifically, given a vector of parameters, By default, any parameters in A custom initializer can be supplied here in one of two formats:

rprior 
optional; function drawing a sample from a prior distribution on parameters. This can be specified in one of three ways:
As above, the latter is typically preferable. 
dprior 
optional; function evaluating the prior distribution. This can be specified in one of three ways:
As above, the latter is typically preferable. 
params 
optional named numeric vector of parameters.
This will be coerced internally to storage mode 
covar, tcovar 
An optional matrix or data frame of covariates:
If a covariate table is supplied, then the value of each of the covariates is interpolated as needed.
The resulting interpolated values are passed to the corresponding functions as a numeric vector named 
obsnames, statenames, paramnames, covarnames 
Optional character vectors specifying the names of observables, state variables, parameters, and covariates, respectively.
These are only used in the event that one or more of the basic functions ( 
zeronames 
optional character vector specifying the names of accumulator variables (see below). 
PACKAGE 
An optional string giving the name of the dynamically loaded library in which any native routines are to be found. 
fromEstimationScale, toEstimationScale 
Optional functions specifying parameter transformations.
Many algorithms for parameter estimation search an unconstrained space of parameters.
When working with such an algorithm and a model for which the parameters are constrained, it can be useful to transform parameters.
Note that it is the user's responsibility to make sure that these transformations are mutually inverse.
If x < coef(obj,transform=TRUE) obj1 < obj coef(obj1,transform=TRUE) < x identical(coef(obj),coef(obj1)) identical(coef(obj1,transform=TRUE),x). By default, both functions are the identity transformation. See the demos, demo(package="pomp"),

globals 
optional character;
C code that will be included in the source for (and therefore hardcoded into) the sharedobject library created when the call to 
... 
Any additional arguments given to 
pomp
returns an object of class pomp
.
If data
is an object of class pomp
, then by default the returned pomp
object is identical to data
.
If additional arguments are given, these override the defaults.
It is not typically necessary (or even feasible) to define all of the components rprocess
, dprocess
, rmeasure
, dmeasure
, and skeleton
in any given problem.
Each algorithm makes use of only a subset of these components.
Any algorithm requiring a component that has not been defined will return an informative error.
Specification of processmodel codes rprocess
and/or dprocess
in most cases is facilitated by pomp's socalled plugins
, which have been developed to handle common usecases.
Currently, if one's process model evolves in discrete time or one is willing to make such an approximation (e.g., via an Euler approximation), then the euler.sim
, discrete.time.sim
, and onestep.sim
plugins for rprocess
and onestep.dens
plugin for dprocess
are available.
In addition, for exact simulation of certain continuoustime Markov chains, an implementation of Gillespie's algorithm is available (see gillespie.sim
).
To learn more about the use of plugins, consult the help documentation (plugins
) and the tutorials on the package website.
Several of the demos and examples make use of these as well.
In specific cases, it may be possible to obtain increased computational efficiency by writing custom versions of rprocess
and/or dprocess
instead of using the plugins.
If such custom versions are desired, the following describes how these functions should be written.
rprocess
If the plugins are not used rprocess
must be an R function with at least the following arguments:
xstart
, times
, params
, and ...
.
It can also take additional arguments.
It is guaranteed that these will be filled with the corresponding elements the user has included as additional arguments in the construction of the pomp
object.
In calls to rprocess
, xstart
can be assumed to be an nvar
x nrep
matrix;
its rows correspond to components of the state vector and columns correspond to independent realizations of the process.
params
will similarly be an npar
x nrep
matrix with rows corresponding to parameters and columns corresponding to independent realizations.
Note that the columns of params
correspond to those of xstart
;
in particular, they will agree in number.
Both xstart
and params
are guaranteed to have rownames.
rprocess
must return a rank3 array with rownames.
Suppose x
is the array returned.
Then dim(x)=c(nvars,nrep,ntimes)
, where ntimes
is the length of the vector times
.
x[,j,k]
is the value of the state process in the j
th realization at time times[k]
.
In particular, x[,,1]
must be identical to xstart
.
The rownames of x
must correspond to those of xstart
.
dprocess
If the plugins are not used, dprocess
must have at least the following arguments:
x
, times
, params
, log
, and ...
.
It may take additional arguments: again, these will be filled with the corresponding elements the user defines when the pomp
object is constructed.
In calls to dprocess
, x
may be assumed to be an nvars
x nrep
x ntimes
array, where these terms have the same meanings as above.
params
will be a matrix with rows corresponding to individual parameters and columns corresponding to independent realizations.
The columns of params
correspond to those of x
; in particular, they will agree in number.
Both x
and params
are guaranteed to have rownames.
dprocess
must return a nrep
x ntimes1
matrix.
Suppose d
is the array returned.
d[j,k]
is the probability density of the transition from state x[,j,k1]
at time times[k1]
to state x[,j,k]
at time times[k]
.
If log=TRUE
, then the log of the pdf must be returned.
In writing this function, you may assume that the transitions are consecutive.
It should be clear that, but for this assumption, it will in general be impossible to write the transition probabilities explicitly.
In such cases, algorithms that make no use of dprocess
, which are said to have the “plug and play” property, are useful.
Most of the algorithms in pomp have this property.
In particular, at present, no methods in pomp make use of dprocess
.
The following is a guide to writing the measurement model components as R functions.
For a description on how to write these components using Csnippet
s, see the tutorials on the package website.
rmeasure
if provided, must take at least the arguments x
, t
, params
, and ...
.
It may take additional arguments, which will be filled with userspecified data as above.
x
will be a named numeric vector of length nvars
(which has the same meaning as above).
t
will be a scalar quantity, the time at which the measurement is made.
params
will be a named numeric vector of length npars
.
The rmeasure
function may take additional arguments which will be filled with userspecified data as above.
rmeasure
must return a named numeric vector of length nobs
, the number of observable variables.
dmeasure
if provided, must take at least the arguments y
, x
, t
, params
, log
, and ...
.
y
will be a named numeric vector of length nobs
containing (actual or simulated) values of the observed variables;
x
will be a named numeric vector of length nvar
containing state variables;
params
will be a named numeric vector containing parameters;
and t
will be a scalar, the corresponding observation time.
The dmeasure
function may take additional arguments which will be filled with userspecified data as above.
dmeasure
must return a single numeric value, the probability density of y
given x
at time t
.
If log=TRUE
, then dmeasure
should return the log of the probability density.
The following describes how to specify the deterministic skeleton as an R function.
For a description on how to write this component using Csnippet
s, see the tutorials on the package website and the Csnippet
help.
If skeleton
if provided, must have at least the arguments x
, t
, params
, and ...
.
x
is a numeric vector containing the coordinates of a point in state space at which evaluation of the skeleton is desired.
t
is a numeric value giving the time at which evaluation of the skeleton is desired.
Of course, these will be irrelevant in the case of an autonomous skeleton.
params
is a numeric vector holding the parameters.
skeleton
may take additional arguments, which will be filled, as above, with userspecified data.
skeleton
must return a numeric vector of the same length as x
, which contains the value vectorfield (if the dynamical system is continuous) or the value of the map (if the dynamical system is discrete), at the point x
at time t
.
if provided, must have at least the arguments params
, t0
, and ...
.
params
will be a named numeric vector of parameters.
t0
will be the time at which initial conditions are desired.
initializer
must return a named numeric vector of initial states.
If the pomp
object contains covariates (via the covar
argument; see above), then whenever any of the R functions described above are called, they will each be supplied with an additional argument covars
.
This will be a named numeric vector containing the (interpolated) values of the covariates at the time t
.
In particular, covars
will have one value for each column of the covariate table.
In formulating models, one often wishes to define a state variable that will accumulate some quantity over the interval between successive observations.
pomp provides a facility to make such features more convenient.
Specifically, variables named in the pomp
's zeronames
argument will be set to zero immediately following each observation.
See euler.sir
and the tutorials on the package website for examples.
Some error checking is done by pomp
, but complete error checking is impossible.
If the userspecified functions do not conform to the above specifications, then the results may be invalid.
In particular, if both rmeasure
and dmeasure
are specified, the user should verify that these two functions correspond to the same probability distribution.
If skeleton
is specified, the user is responsible for verifying that it corresponds to a deterministic skeleton of the model.
Each pomppackage algorithm uses some subset of the five basic functions (rprocess
, dprocess
, rmeasure
, dmeasure
, skeleton
).
If an algorithm requires a component that has not been specified, an informative error will be generated.
Aaron A. King kingaa at umich dot edu
pomp methods, pomp lowlevel interface, process model plugins
1 2 3 4 5 6 7 8 9 10  ## Not run:
pompExample()
pomp.home < system.file("examples",package="pomp")
pomp.examples < list.files(pomp.home)
file.show(
file.path(pomp.home,pomp.examples),
header=paste("======",pomp.examples,"=======")
)
## End(Not run)

Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.
Please suggest features or report bugs with the GitHub issue tracker.
All documentation is copyright its authors; we didn't write any of that.