pomp_constructor {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;

dinit

which evaluates the density 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;

emeasure

the expectation of the measurements, conditional on the latent state;

vmeasure

the covariance matrix of the measurements, conditional on the latent state;

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,
  dinit,
  rprocess,
  dprocess,
  rmeasure,
  dmeasure,
  emeasure,
  vmeasure,
  skeleton,
  rprior,
  dprior,
  partrans,
  covar,
  params,
  accumvars,
  obsnames,
  statenames,
  paramnames,
  covarnames,
  nstatevars,
  PACKAGE,
  globals,
  on_load,
  userdata,
  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. Internally, data will be coerced to an array with storage-mode double.

times

the sequence of observation times. times must indicate the column of observation times by name or index. The time vector must be numeric and non-decreasing.

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 will be added to the userdata list, with a warning. In a future release, this warning will become an error.

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 specification.

dinit

evaluator of the initial-state density. 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 dinit=NULL removes this basic component. For more information, see dinit specification.

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 specification for the documentation on these plugins.

dprocess

evaluator of the probability density of transitions of the unobserved state process. Setting dprocess=NULL removes the latent-state density evaluator. For more information, see dprocess specification.

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 specification.

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 specification.

emeasure

the expectation of the measured variables, conditional on the latent state. This can be specified as a C snippet, an R function, or the name of a pre-compiled native routine available in a dynamically loaded library. Setting emeasure=NULL removes the emeasure component. For more information, see emeasure specification.

vmeasure

the covariance of the measured variables, conditional on the latent state. This can be specified as a C snippet, an R function, or the name of a pre-compiled native routine available in a dynamically loaded library. Setting vmeasure=NULL removes the vmeasure component. For more information, see vmeasure specification.

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 specification. 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 specification. 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 specification. 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 accumvars 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. See also nstatevars.

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.

nstatevars

optional integer scalar; If C snippets or native routines are used, one can specify the number of state variables with this argument. By default, nstatevars = length(statenames).

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 or C snippet; 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.

on_load

optional character or C snippet: arbitrary C code that will be executed when the C snippet file is loaded. If no C snippets are used, on_load has no effect.

userdata

optional list; the elements of this list will be available to basic model components. 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.

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 global 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. One can, for example, specify libraries against which the C snippets are to be linked. In doing so, take care to make sure the appropriate header files are available to the C snippets, e.g., using the globals argument. See Csnippet for more information.

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 feasible) to define all of the basic components for any given purpose. However, each pomp algorithm makes use of only a subset of these components. When an algorithm requires a basic component that has not been furnished, an error is generated to let you know that you must provide the needed component to use the algorithm.

Note for Windows users

Some Windows users report problems when using C snippets in parallel computations. These appear to arise when the temporary files created during the C snippet compilation process are not handled properly by the operating system. To circumvent this problem, use the cdir and cfile options to cause the C snippets to be written to a file of your choice, thus avoiding the use of temporary files altogether.

Author(s)

Aaron A. King

References

A. A. King, D. Nguyen, and E. L. Ionides. Statistical inference for partially observed Markov processes via the R package pomp. Journal of Statistical Software 69(12), 1–43, 2016. doi:10.18637/jss.v069.i12. An updated version of this paper is available on the pomp package website.

See Also

More on implementing POMP models: Csnippet, accumvars, basic_components, betabinomial, covariates, dinit_spec, dmeasure_spec, dprocess_spec, emeasure_spec, eulermultinom, parameter_trans(), pomp-package, prior_spec, rinit_spec, rmeasure_spec, rprocess_spec, skeleton_spec, transformations, userdata, vmeasure_spec


[Package pomp version 5.11.0.0 Index]