hitch: Hitching C snippets and R functions to pomp_fun objects

In pomp: Statistical Inference for Partially Observed Markov Processes

Hitching C snippets and R functions to pomp_fun objects

Description

The algorithms in pomp are formulated using R functions that access the basic model components (rprocess, dprocess, rmeasure, dmeasure, etc.). For short, we refer to these elementary functions as “workhorses”. In implementing a model, the user specifies basic model components using functions, procedures in dynamically-linked libraries, or C snippets. Each component is then packaged into a ‘pomp_fun’ objects, which gives a uniform interface. The construction of ‘pomp_fun’ objects is handled by the hitch function, which conceptually “hitches” the workhorses to the user-defined procedures.

Usage

hitch(
  ...,
  templates,
  obsnames,
  statenames,
  paramnames,
  covarnames,
  PACKAGE,
  globals,
  cfile,
  cdir = getOption("pomp_cdir", NULL),
  on_load,
  shlib.args,
  compile = TRUE,
  verbose = getOption("verbose", FALSE)
)

Arguments

...	named arguments representing the user procedures to be hitched. These can be functions, character strings naming routines in external, dynamically-linked libraries, C snippets, or NULL. The first three are converted by hitch to ‘pomp_fun’ objects which perform the indicated computations. NULL arguments are translated to default ‘pomp_fun’ objects. If any of these procedures are already ‘pomp_fun’ objects, they are returned unchanged.
templates	named list of templates. Each workhorse must have a corresponding template. See pomp:::workhorse_templates for a list.
obsnames, statenames, paramnames, covarnames	character vectors specifying the names of observable variables, latent state variables, parameters, and covariates, respectively. These are only needed if one or more of the horses are furnished as C snippets.
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.
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.
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.
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.
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. Setting verbose=TRUE will cause additional information to be displayed.

Value

hitch returns a named list of length two. The element named “funs” is itself a named list of ‘pomp_fun’ objects, each of which corresponds to one of the horses passed in. The element named “lib” contains information on the shared-object library created using the C snippets (if any were passed to hitch). If no C snippets were passed to hitch, lib is NULL. Otherwise, it is a length-3 named list with the following elements:

name

The name of the library created.

dir

The directory in which the library was created. If this is NULL, the library was created in the session's temporary directory.

src

A character string with the full contents of the C snippet file.

Author(s)

Aaron A. King

See Also

pomp, spy

pomp documentation built on Sept. 13, 2024, 1:08 a.m.