skeleton_spec {pomp}

skeleton specification

Description

Specification of the deterministic skeleton.

Usage

vectorfield(f)

map(f, delta.t = 1)

Arguments

f

procedure for evaluating the deterministic skeleton This can be a C snippet, an R function, or the name of a native routine in a dynamically linked library.

delta.t

positive numerical value; the size of the discrete time step corresponding to an application of the map

Details

The skeleton is a dynamical system that expresses the central tendency of the unobserved Markov state process. As such, it is not uniquely defined, but can be both interesting in itself and useful in practice. In pomp, the skeleton is used by trajectory and traj_objfun.

If the state process is a discrete-time stochastic process, then the skeleton is a discrete-time map. To specify it, provide

  skeleton = map(f, delta.t)

to pomp, where f implements the map and delta.t is the size of the timestep covered at one map iteration.

If the state process is a continuous-time stochastic process, then the skeleton is a vectorfield (i.e., a system of ordinary differential equations). To specify it, supply

  skeleton = vectorfield(f)

to pomp, where f implements the vectorfield, i.e., the right-hand-size of the differential equations.

In either case, f can be furnished either as a C snippet (the preferred choice), or an R function. General rules for writing C snippets can be found here. In writing a skeleton C snippet, be aware that:

1. For each state variable, there is a corresponding component of the deterministic skeleton. The goal of such a snippet is to compute all the components.

2. When the skeleton is a map, the component corresponding to state variable x is named Dx and is the new value of x after one iteration of the map.

3. When the skeleton is a vectorfield, the component corresponding to state variable x is named Dx and is the value of dx/dt.

4. As with the other C snippets, all states, parameters and covariates, as well as the current time, t, will be defined in the context within which the snippet is executed.

5. NB: When the skeleton is a map, the duration of the timestep will not be defined in the context within which the snippet is executed. When the skeleton is a vectorfield, of course, no timestep is defined. In this regard, C snippets for the skeleton and rprocess components differ.

The tutorials on the package website give some examples.

If f is an R function, its arguments should be taken from among the state variables, parameters, covariates, and time. It must also take the argument ‘...’. As with the other basic components, f may take additional arguments, provided these are passed along with it in the call to pomp. The function f must return a numeric vector of the same length as the number of state variables, which contains the value of the map or vectorfield at the required point and time.

Masking of map

Other packages (most notably the tidyverse package purrr) have functions named ‘map’. Beware that, if you load one of these packages after you load pomp, the pomp function map described here will be masked. You can always access the pomp function by calling pomp::map.

Default behavior

The default skeleton is undefined. It will yield missing values (NA) for all state variables.

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.

See Also

skeleton

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

More on methods for deterministic process models: flow(), skeleton(), traj_match, trajectory()

Examples

  ## Starting with an existing pomp object,
  ## e.g., the continuous-time Verhulst-Pearl model,

  verhulst() -> po
  
  ## we add or change the deterministic skeleton
  ## using the 'skeleton' argument in any 'pomp'
  ## elementary or estimation function
  ## (or in the 'pomp' constructor itself).
  ## Here, we pass the skeleton specification
  ## to 'trajectory' as an R function.
  ## Since this is a continuous-time POMP, the
  ## skeleton is a vectorfield.

  po |>
    trajectory(
      skeleton=vectorfield(
        function(r, K, n, ...) {
          c(n=r*n*(1-n/K))
        }
      ),
      format="data.frame"
    ) -> traj

  ## We can also pass it as a C snippet:

  po |>
    traj_objfun(
      skeleton=vectorfield(Csnippet("Dn=r*n*(1-n/K);")),
      paramnames=c("r","K"),
      statenames="n"
    ) -> ofun

  ofun()

  ## For a discrete-time POMP, the deterministic skeleton
  ## is a map.  For example,

  gompertz() -> po

  po |>
    traj_objfun(
      skeleton=map(
        Csnippet("
          double dt = 1.0;
          double s = exp(-r*dt);
          DX = pow(K,(1-s))*pow(X,s);"
        ), delta.t=1
      ),
      paramnames=c("r","K"),
      statenames=c("X")
    ) -> ofun

  ofun()