spatPomp {spatPomp}

Constructor of the spatPomp object

Description

This function constructs a class ‘spatPomp’ object, encoding a spatiotemporal partially observed Markov process (SpatPOMP) model together with a uni- or multi-variate time series on a collection of units. Users will typically develop a POMP model for a single unit before embarking on a coupled SpatPOMP analysis. Consequently, we assume some familiarity with pomp and its description by King, Nguyen and Ionides (2016). The spatPomp class inherits from pomp with the additional unit structure being a defining feature of the resulting models and inference algorithms.

Usage

spatPomp(
  data,
  units,
  times,
  covar,
  t0,
  ...,
  eunit_measure,
  munit_measure,
  vunit_measure,
  dunit_measure,
  runit_measure,
  rprocess,
  rmeasure,
  dprocess,
  dmeasure,
  skeleton,
  rinit,
  rprior,
  dprior,
  unit_statenames,
  unit_accumvars,
  shared_covarnames,
  globals,
  paramnames,
  params,
  cdir,
  cfile,
  shlib.args,
  PACKAGE,
  partrans,
  compile = TRUE,
  verbose = getOption("verbose", FALSE)
)

Arguments

data

either a dataframe holding the spatiotemporal data, or an object of class ‘spatPomp’, i.e., the output of another spatPomp calculation. If dataframe, the user must provide the name of the times column using the times argument and the spatial unit column name using the units argument. The dataframe provided should be sorted in increasing order of time and unit name respectively, i.e. observation 1 in unit A should come before observation 1 in unit B, which should come before observation 2 in unit A.

units

when data is a data.frame this is the name of the column containing the spatial units.

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.

covar

An optional dataframe for supplying covariate information. If provided, there must be two columns that provide the observation time and the observation spatial unit with the same names and arrangement as the data.

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

...

If there are arguments that the user would like to pass to pomp's basic constructor function's ... argument, this argument passes them along. Not recommended for this version of spatPomp.

eunit_measure

Evaluator of the expected measurement given the latent states and model parameters. The unit variable is pre-defined, which allows the user to specify differing specifications for each unit using if conditions. Only C snippets are accepted. The C snippet should assign the scalar approximation to the expected measurement to the pre-defined variable ey given the latent state and the parameters. For more information, see the examples section below.

munit_measure

Evaluator of a moment-matched parameter set (like the standard deviation parameter of a normal distribution or the size parameter of a negative binomial distribution) given an empirical variance estimate, the latent states and all model parameters. Only Csnippets are accepted. The Csnippet should assign the scalar approximation to the measurement variance parameter to the pre-defined variable corresponding to that parameter, which has been predefined with a M_ prefix. For instance, if the moment-matched parameter is psi, then the user should assign M_psi to the moment-matched value. For more information, see the examples section below.

vunit_measure

Evaluator of the theoretical measurement variance given the latent states and model parameters. The unit variable is pre-defined, which allows the user to specify differing specifications for each unit using if conditions. Only C snippets are accepted. The C snippet should assign the scalar approximation to the measurement variance to the pre-defined variable vc given the latent state and the parameters. For more information, see the examples section below.

dunit_measure

Evaluator of the unit measurement model density given the measurement, the latent states and model parameters. The unit variable is pre-defined, which allows the user to specify differing specifications for each unit using if conditions. Only Csnippets are accepted. The Csnippet should assign the scalar measurement density to the pre-defined variable lik. The user is encouraged to provide a logged density in an if condition that checks whether the predefined give_log variable is true. For more information, see the examples section below.

runit_measure

Simulator of the unit measurement model given the latent states and the model parameters. The unit variable is pre-defined, which allows the user to specify differing specifications for each unit using if conditions. Only Csnippets are accepted. The Csnippet should assign the scalar measurement density to the pre-defined which corresponds to the name of the observation for each unit (e.g. cases for the measles spatPomp example). For more information, see the examples section below.

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.

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.

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.

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.

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.

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.

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.

unit_statenames

The names of the components of the latent state. E.g. if the user is constructing an joint SIR model over many spatial units, c('S','I','R') would be passed.

unit_accumvars

a subset of the unit_statenames argument that are accumulator variables. See accumvars for more on the concept of pomp accumulator variables.

shared_covarnames

If covar is supplied, covariates that are shared must still be specified for each unit, i.e., rows with equal values for the same time over all units must be supplied. However, if such covariates exists, supply the names using this argument.

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.

paramnames

optional character vector; names of model parameters. It is typically only necessary to supply paramnames when C snippets are in use.

params

optional; named numeric vector of parameters. This will be coerced internally to storage mode double.

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.

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.

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.

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

One implements a SpatPOMP model by specifying some or all of its basic components, including:

rinit,

the simulator from the distribution of the latent state process at the zero-time;

rprocess,

the transition simulator of the latent state process;

dunit_measure,

the evaluator of the conditional density at a unit's measurement given the unit's latent state;

eunit_measure,

the evaluator of the expectation of a unit's measurement given the unit's latent state;

munit_measure,

the evaluator of the moment-matched parameter set given a unit's latent state and some empirical measurement variance;

vunit_measure,

the evaluator of the variance of a unit's measurement given the unit's latent state;

runit_measure,

the simulator of a unit's measurement conditional on the unit's latent state;

dprocess,

the evaluator of the density for transitions of the latent state process;

rmeasure,

the simulator of the measurements conditional on the latent state;

dmeasure,

the evaluator of the conditional density of the measurements given the latent state;

rprior,

the simulator from a prior distribution on the parameters;

dprior,

the evaluator of the prior density;

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 Asfaw et al. (2020).

Each basic component is supplied via an argument of the same name to spatPomp(). The five unit-level model components must be provided via C snippets. The remaining components, whose behaviors are inherited from pomp may be furnished using C snippets, R functions, or pre-compiled native routine available in user-provided dynamically loaded libraries.

Value

An object of class ‘spatPomp’ representing observations and model components from the spatiotemporal POMP model.

Author(s)

Kidus Asfaw, Edward L. Ionides, Aaron A. King

References

Asfaw, K., Park, J., Ho, A., King, A. A., and Ionides, E. L. (2020) Partially observed Markov processes with spatial structure via the R package spatPomp. ArXiv: 2101.01157. doi:10.48550/arXiv.2101.01157

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