pomp {pomp} | R Documentation

## Constructor of the basic pomp object

### Description

This function constructs a ‘pomp’ object, encoding a partially-observed Markov process (POMP) model together with a uni- or multi-variate time series. As such, it is central to all the package's functionality. One implements the POMP model by specifying some or all of its basic components. These comprise:

rinit,

  which samples from the distribution of the state process at the zero-time;

rprocess,

  the simulator of the unobserved Markov state process;

dprocess,

  the evaluator of the probability density function for transitions of the unobserved Markov state process;

rmeasure,

  the simulator of the observed process, conditional on the unobserved state;

dmeasure,

  the evaluator of the measurement model probability density function;

rprior,

  which samples from a prior probability distribution on the parameters;

dprior,

  which evaluates the prior probability density function;

skeleton,

  which computes the deterministic skeleton of the unobserved state process;

partrans,

  which performs parameter transformations.

The basic structure and its rationale are described in the Journal of Statistical Software paper, an updated version of which is to be found on the package website.

### Usage

    pomp(data, times, t0, ..., rinit, rprocess, dprocess, rmeasure, dmeasure,
      skeleton, rprior, dprior, partrans, covar, params, accumvars, obsnames,
      statenames, paramnames, covarnames, PACKAGE, globals,
      cdir = getOption("pomp_cdir", NULL), cfile, shlib.args,
      compile = TRUE, verbose = getOption("verbose", FALSE))

### Arguments

`data` | either a data frame holding the time series data, or an object of class ‘pomp’, i.e., the output of another pomp calculation.
`times` | the times at which observations are made. `times` must indicate the column of observation times by name or index. The time vector must be numeric and non-decreasing. Internally, `data` will be internally coerced to an array with storage-mode `double`.
`t0` | The zero-time, i.e., the time of the initial state. This must be no later than the time of the first observation, i.e., `t0 <= times[1]`.

`...`

additional arguments supply new or modify existing model characteristics or components. See `pomp` for a full list of recognized arguments.

When named arguments not recognized by `pomp` are provided, these are made available to all basic components via the so-called userdata facility. This allows the user to pass information to the basic components outside of the usual routes of covariates (`covar`) and model parameters (`params`). See ?userdata for information on how to use this facility.

`rinit` | simulator of the initial-state distribution. This can be furnished either as a C snippet, an R function, or the name of a pre-compiled native routine available in a dynamically loaded library. Setting `rinit=NULL` sets the initial-state simulator to its default. For more information, see ?rinit_spec.
`rprocess` | simulator of the latent state process, specified using one of the rprocess plugins. Setting `rprocess=NULL` removes the latent-state simulator. For more information, see ?rprocess_spec for the documentation on these plugins.
`dprocess` | optional; specification of the probability density evaluation function of the unobserved state process. Setting `dprocess=NULL` removes the latent-state density evaluator. For more information, see ?dprocess_spec.
`rmeasure` | simulator of the measurement model, specified either as a C snippet, an R function, or the name of a pre-compiled native routine available in a dynamically loaded library. Setting `rmeasure=NULL` removes the measurement model simulator. For more information, see ?rmeasure_spec.
`dmeasure` | evaluator of the measurement model density, specified either as a C snippet, an R function, or the name of a pre-compiled native routine available in a dynamically loaded library. Setting `dmeasure=NULL` removes the measurement density evaluator. For more information, see ?dmeasure_spec.
`skeleton` | optional; the deterministic skeleton of the unobserved state process. Depending on whether the model operates in continuous or discrete time, this is either a vectorfield or a map. Accordingly, this is supplied using either the `vectorfield` or `map` fnctions. For more information, see ?skeleton_spec. Setting `skeleton=NULL` removes the deterministic skeleton.
`rprior` | optional; prior distribution sampler, specified either as a C snippet, an R function, or the name of a pre-compiled native routine available in a dynamically loaded library. For more information, see ?prior_spec. Setting `rprior=NULL` removes the prior distribution sampler.
`dprior` | optional; prior distribution density evaluator, specified either as a C snippet, an R function, or the name of a pre-compiled native routine available in a dynamically loaded library. For more information, see ?prior_spec. Setting `dprior=NULL` resets the prior distribution to its default, which is a flat improper prior.

`partrans`

optional parameter transformations, constructed using `parameter_trans`.

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. One should supply the `partrans` argument via a call to `parameter_trans`. For more information, see ?parameter_trans. Setting `partrans=NULL` removes the parameter transformations, i.e., sets them to the identity transformation.

`covar` | optional covariate table, constructed using `covariate_table`. If a covariate table is supplied, then the value of each of the covariates is interpolated as needed. The resulting interpolated values are made available to the appropriate basic components. See the documentation for `covariate_table` for details.
`params` | optional; named numeric vector of parameters. This will be coerced internally to storage mode `double`.
`accumvars` | optional character vector; contains the names of accumulator variables. See ?accumulators for a definition and discussion of accumulator variables.
`obsnames` | optional character vector; names of the observables. It is not usually necessary to specify `obsnames` since, by default, these are read from the names of the data variables.
`statenames` | optional character vector; names of the latent state variables. It is typically only necessary to supply `statenames` when C snippets are in use.
`paramnames` | optional character vector; names of model parameters. It is typically only necessary to supply `paramnames` when C snippets are in use.
`covarnames` | optional character vector; names of the covariates. It is not usually necessary to specify `covarnames` since, by default, these are read from the names of the covariates.
`PACKAGE` | optional character; the name (without extension) of the external, dynamically loaded library in which any native routines are to be found. This is only useful if one or more of the model components has been specified using a precompiled dynamically loaded library; it is not used for any component specified using C snippets. `PACKAGE` can name at most one library.
`globals` | optional character; arbitrary C code that will be hard-coded into the shared-object library created when C snippets are provided. If no C snippets are used, `globals` has no effect.
`cdir` | optional character variable. `cdir` specifies the name of the directory within which C snippet code will be compiled. By default, this is in a temporary directory specific to the R session. One can also set this directory using the `pomp_cdir` option.
`cfile` | optional character variable. `cfile` gives the name of the file (in directory `cdir`) into which C snippet codes will be written. By default, a random filename is used. If the chosen filename would result in over-writing an existing file, an error is generated.
`shlib.args` | optional character variables. Command-line arguments to the `R CMD SHLIB` call that compiles the C snippets.
`compile` | logical; if `FALSE`, compilation of the C snippets will be postponed until they are needed.
`verbose` | logical; if `TRUE`, diagnostic messages will be printed to the console.

### Details

Each basic component is supplied via an argument of the same name. These can be given in the call to `pomp`, or to many of the package's other functions. In any case, the effect is the same: to add, remove, or modify the basic component.

Each basic component can be furnished using C snippets, R functions, or pre-compiled native routine available in user-provided dynamically loaded libraries.

### Value

The `pomp` constructor function returns an object, call it `P`, of class ‘pomp’. `P` contains, in addition to the data, any elements of the model that have been specified as arguments to the `pomp` constructor function. One can add or modify elements of `P` by means of further calls to `pomp`, using `P` as the first argument in such calls. One can pass `P` to most of the pomp package methods via their `data` argument.

### Note

It is not typically necessary (or indeed often feasible) to define all of the basic components for any given purpose. Each pomp algorithm makes use of only a subset of these components. Any algorithm requiring a component that is not present will generate an error letting you know that you have not provided a needed component. FIXME

### Author(s)

Aaron A. King

### References

A. A. King, D. Nguyen, and E. L. Ionides (2016) Statistical Inference for Partially Observed Markov Processes via the Package pomp. Journal of Statistical Software 69(12): 1–43.

[Package pomp version 2.3 Index]