[Pomp-commits] r132 - pkg/man

[noreply at r-forge.r-project.org]

Author: kingaa
Date: 2009-05-21 05:09:36 +0200 (Thu, 21 May 2009)
New Revision: 132

Modified:
   pkg/man/pomp-package.Rd
   pkg/man/pomp.Rd
Log:
clarify the documentation on pomp object construction

Modified: pkg/man/pomp-package.Rd
===================================================================
--- pkg/man/pomp-package.Rd	2009-05-14 14:27:59 UTC (rev 131)
+++ pkg/man/pomp-package.Rd	2009-05-21 03:09:36 UTC (rev 132)
@@ -4,7 +4,7 @@
 \title{Partially-observed Markov processes}
 \description{
   The \code{pomp} package provides facilities for inference using partially-observed Markov processes (AKA state-space models or nonlinear stochastic dynamical systems).
-  The user provides functions specifying the model's process and measurement components.
+  The user provides functions specifying some or all of the model's process and measurement components.
   The package's algorithms are built on top of these functions.
   At the moment, algorithms are provided for particle filtering (AKA sequential Monte Carlo or sequential importance sampling) and the likelihood maximization by iterated filtering (MIF) method of Ionides, Breto, and King (PNAS, 103:18438-18443, 2006).
   Future support for a variety of other algorithms is envisioned.

Modified: pkg/man/pomp.Rd
===================================================================
--- pkg/man/pomp.Rd	2009-05-14 14:27:59 UTC (rev 131)
+++ pkg/man/pomp.Rd	2009-05-21 03:09:36 UTC (rev 132)
@@ -26,13 +26,13 @@
     This must be no later than the time of the first observation, \code{times[1]}.
   }
   \item{rprocess}{
-    Function of prototype \code{rprocess(xstart,times,params,\dots)} which simulates from the unobserved process.
+    optional; a function of prototype \code{rprocess(xstart,times,params,\dots)} which simulates from the unobserved process.
   }
   \item{dprocess}{
-    Function of prototype \code{dprocess(x,times,params,log,\dots)} which evaluates the likelihood of a sequence of consecutive state transitions.
+    optional; a function of prototype \code{dprocess(x,times,params,log,\dots)} which evaluates the likelihood of a sequence of consecutive state transitions.
   }
   \item{rmeasure}{
-    The measurement model simulator.
+    optional; the measurement model simulator.
     This can be specified in one of three ways:
     (1) as a function of prototype \code{rmeasure(x,t,params,\dots)} which makes a draw from the observation process given states \code{x}, time \code{t}, and parameters \code{params}.
     (2) as the name of a native (compiled) routine with prototype "pomp\_measure\_model\_simulator" as defined in the header file "pomp.h".
@@ -40,7 +40,7 @@
     (3) using the formula-based \code{measurement.model} facility (see below).
   }
   \item{dmeasure}{
-    The measurement model probability density function.
+    optional; the measurement model probability density function.
     This can be specified in one of three ways:
     (1) as a function of prototype \code{dmeasure(y,x,t,params,log,\dots)} which computes the p.d.f. of \code{y} given \code{x}, \code{t}, and \code{params}.
     (2) as the name of a native (compiled) routine with prototype "pomp\_measure\_model\_density" as defined in the header file "pomp.h".
@@ -49,24 +49,26 @@
     As might be expected, if \code{log=TRUE}, this function should return the log likelihood.
   }
   \item{measurement.model}{
-    An optional formula or list of formulae, specifying the measurement model.
+    optional; a formula or list of formulae, specifying the measurement model.
     These formulae are parsed and used to generate \code{rmeasure} and \code{dmeasure} functions.
     If \code{measurement.model} is given it overrides any specification of \code{rmeasure} or \code{dmeasure}.
     See below for an example.
     NB: it will typically be possible to acclerate measurement model computations by writing \code{dmeasure} and/or \code{rmeasure} functions directly.
   }
   \item{skeleton.map}{
+    optional.
     If we are dealing with a discrete-time Markov process, its deterministic skeleton is a map and can be specified using \code{skeleton.map} in one of two ways:
     (1) as a function of prototype \code{skeleton(x,t,params,\dots)} which evaluates the deterministic skeleton (whether vectorfield or map) of at state \code{x} and time \code{t} given the parameters \code{params}, or
     (2) as the name of a native (compiled) routine with prototype "pomp\_vectorfield\_map" as defined in the header file "pomp.h".
     If the deterministic skeleton depends on covariates, the optional argument \code{covars} will be filled with interpolated values of the covariates at the time \code{t}.
   }
   \item{skeleton.vectorfield}{
+    optional.
     If we are dealing with a continuous-time Markov process, its deterministic skeleton is a vectorfield and can be specified using \code{skeleton.vectorfield} in either of the two ways described above, under \code{skeleton.map}.
     Note that it makes no sense to specify the deterministic skeleton both as a map and as a vectorfield: an attempt to do so will generate an error.
   }
   \item{initializer}{
-    Function of prototype \code{initializer(params,t0,\dots)} which yields initial conditions for the state process when given a vector, \code{params}, of parameters.
+    optional; a function of prototype \code{initializer(params,t0,\dots)} which yields initial conditions for the state process when given a vector, \code{params}, of parameters.
     By default, i.e., if it is unspecified when \code{pomp} is called, the initializer assumes any names in \code{params} that end in ".0" correspond to initial value parameters.
     These are simply copied over as initial conditions when \code{init.state} is called (see \code{\link{init.state-pomp}}).
     The names of the state variables are the same as the corresponding initial value parameters, but with the ".0" dropped.
@@ -97,7 +99,7 @@
   
   \describe{
     \item{\code{rprocess}}{
-      must have at least the following arguments:
+      if provided, must have at least the following arguments:
       \code{xstart}, \code{times}, \code{params}, and \code{\dots}.
       It can also take additional arguments.
       It is guaranteed that these will be filled with the corresponding elements the user has included as additional arguments in the construction of the \code{pomp} object.
@@ -116,7 +118,7 @@
       The rownames of \code{x} must correspond to those of \code{xstart}.
     }
     \item{\code{dprocess}}{
-      must have at least the following arguments:
+      if provided, must have at least the following arguments:
       \code{x}, \code{times}, \code{params}, \code{log}, and \code{\dots}.
       It may take additional arguments.
       It is guaranteed that these will be filled with the corresponding elements the user has included as additional arguments in the construction of the \code{pomp} object.
@@ -134,7 +136,7 @@
       \strong{In writing this function, you may assume that the transitions are consecutive.}
     }
     \item{\code{rmeasure}}{
-      must take at least the arguments \code{x}, \code{t}, \code{params}, and \code{\dots}.
+      if provided, must take at least the arguments \code{x}, \code{t}, \code{params}, and \code{\dots}.
       It may take additional arguments, which will be filled with user-specified data as above.
       \code{x} may be assumed to be a named vector of length \code{nvars}, (which has the same meanings as above).
       \code{t} is a scalar quantity, the time at which the measurement is made.
@@ -144,7 +146,7 @@
       If \code{y} is the returned vector, then \code{length(y)=nobs}, where \code{nobs} is the number of observable variables.
     }
     \item{\code{dmeasure}}{
-      must take at least the arguments \code{y}, \code{x}, \code{times}, \code{params}, \code{log}, and \code{\dots}.
+      if provided, must take at least the arguments \code{y}, \code{x}, \code{times}, \code{params}, \code{log}, and \code{\dots}.
       \code{y} may be assumed to be a named vector of length \code{nobs} containing (actual or simulated) values of the observed variables;
       \code{x} will be a named vector of length \code{nvar} containing state variables
       \code{params}, a named vector containing parameters;
@@ -169,7 +171,7 @@
       If \code{skeleton} is the name of a native routine, this routine must be of prototype "pomp\_vectorfield\_map" as defined in the header "pomp.h" (see the "include" directory in the installed package directory).
     }
     \item{\code{initializer}}{
-      must have at least the arguments \code{params}, \code{t0}, and \code{\dots}.
+      if provided, must have at least the arguments \code{params}, \code{t0}, and \code{\dots}.
       \code{params} is a named vector of parameters.
       \code{t0} will be the time at which initial conditions are desired.
       \code{initializer} must return a named vector of initial conditions.
@@ -277,6 +279,8 @@
 \section{Warning}{
   Some error checking is done, but complete error checking is impossible.  
   If the user-specified functions do not conform to the above specifications (see Details), then the results may be invalid.
+  Each algorithm that uses a \code{pomp} object uses some subset of the four basic components (\code{rprocess}, \code{dprocess}, \code{rmeasure}, \code{dmeasure}).
+  It is unlikely that any algorithm will use all of these.
 }
 \references{}
 \author{Aaron A. King (kingaa at umich dot edu)}