hitch function

Hitching C snippets and R functions to pomp_fun objects

The algorithms in pomp are formulated using 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. methods

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

Returns

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.

See Also

pomp, spy

Author(s)

Aaron A. King