spatPomp: Constructor of the spatPomp object

In spatPomp: Inference for Spatiotemporal Partially Observed Markov Processes

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

2020

\king

2016

spatPomp documentation built on Aug. 10, 2023, 1:10 a.m.