fix documentation problem with 'filter.traj' and other 'pfilter' auxi…

…liary functions

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: pomp
 Type: Package
 Title: Statistical Inference for Partially Observed Markov Processes
-Version: 2.3.0.4
+Version: 2.3.0.5
 Date: 2019-09-16
 Authors@R: c(person(given=c("Aaron","A."),family="King",
 		role=c("aut","cre"),email="[email protected]"),

R/cond_logLik.R

@@ -3,11 +3,11 @@
 ##' The estimated conditional log likelihood from a fitted model.
 ##'
 ##' The conditional likelihood is defined to be the value of the density
-##' of \deqn{Y_t | Y_1,\dots,Y_{t-1}}{Yt | Y1,\dots,Y(t-1)} evaluated at \eqn{Y_t = y^*_t}{Yt = yt*}.
-##' Here, \eqn{Y_t}{Yt} is the observable process and \eqn{y^*_t}{yt*} is the data, at time \eqn{t}.
+##' of \deqn{Y(t_k) | Y(t_1),\dots,Y(t_{k-1})}{Yk | Y1,\dots,Y(k-1)} evaluated at \eqn{Y(t_k) = y^*_k}{Yk = yk*}.
+##' Here, \eqn{Y(t_k)}{Yk} is the observable process, and \eqn{y^*_k}{yk*} the data, at time \eqn{t_k}.
 ##'
-##' Thus the conditional log likelihood at time \eqn{t} is
-##' \deqn{\ell_t(\theta) = \log f[Y_t=y^*_t \vert Y_1=y^*_1, \dots, Y_{t-1}=y^*_{t-1}],}{ell_t(theta)=log f[Yt = yt*t | Y1=y1*, \dots, Y(t-1)=y(t-1)*],}
+##' Thus the conditional log likelihood at time \eqn{t_k} is
+##' \deqn{\ell_k(\theta) = \log f[Y(t_k)=y^*_k \vert Y(t_1)=y^*_1, \dots, Y(t_{k-1})=y^*_{k-1}],}{ell_k(theta)=log f[Yk = yk* | Y1=y1*, \dots, Y(k-1)=y(k-1)*],}
 ##' where \eqn{f} is the probability density above.
 ##'
 ##' @name cond.logLik

R/filter_mean.R

@@ -3,11 +3,11 @@
 ##' The mean of the filtering distribution
 ##'
 ##' The filtering distribution is that of
-##' \deqn{X_t \vert Y_1=y^*_1,\dots,Y_t=y^*_t,}{Xt | Y1=y1*,\dots,Yt=yt*,}
-##' where \eqn{X_t}{Xt}, \eqn{Y_t}{Yt} are the latent state and observable processes, respectively, and \eqn{y^*_t}{yt*} is the data, at time \eqn{t}.
+##' \deqn{X(t_k) \vert Y(t_1)=y^*_1,\dots,Y(t_k)=y^*_k,}{Xk | Y1=y1*,\dots,Yk=yk*,}
+##' where \eqn{X(t_k)}{Xk}, \eqn{Y(t_k)}{Yk} are the latent state and observable processes, respectively, and \eqn{y^*_t}{yt*} is the data, at time \eqn{t_k}{tk}.
 ##'
 ##' The filtering mean is therefore the expectation of this distribution
-##' \deqn{E[X_t \vert Y_1=y^*_1,\dots,Y_t=y^*_t].}{E[Xt | Y1=y1*,\dots,Yt=yt*].}
+##' \deqn{E[X(t_k) \vert Y(t_1)=y^*_1,\dots,Y(t_k)=y^*_k].}{E[Xk | Y1=y1*,\dots,Yk=yk*].}
 ##'
 ##' @name filter.mean
 ##' @docType methods

R/filter_traj.R

@@ -1,19 +1,18 @@
 ##' Filtering trajectories
 ##'
-##' Trajectories drawn from the smoothing distribution
+##' Drawing from the smoothing distribution
 ##'
 ##' The smoothing distribution is the distribution of
-##' \deqn{X_t | Y_1=y^*_1, \dots, Y_T=y^*_T,}{Xt | Y1=y1*, \dots, YT=yT*,}
-##' where \eqn{X_t}{Xt} is the latent state process, \eqn{Y_t}{Yt} is the observable process, \eqn{t} is time, and \eqn{T} is the time of the final observation.
+##' \deqn{X(t_k) | Y(t_1)=y^*_1, \dots, Y(t_n)=y^*_n,}{Xk | Y1=y1*, \dots, Yn=yn*,}
+##' where \eqn{X(t_k)}{Xk} is the latent state process and \eqn{Y(t_k)}{Yk} is the observable process at time \eqn{t_k}{tk}, and \eqn{n} is the number of observations.
 ##'
-##' In a particle filter, the trajectories of the individual particles are not independent of one another, since they share ancestry.
-##' However, a randomly sampled particle trajectory \eqn{X_1,\dots,X_T} is a draw from the smoothing distribution.
-##' Seting \code{filter.traj = TRUE} in \code{\link{pfilter}} causes one such trajectory to be sampled.
-##' By running multiple independent \code{pfilter} operations, one can thus build up a picture of the smoothing distribution.
+##' To draw samples from this distribution, one can run a number of independent particle filter (\code{\link{pfilter}}) operations, sampling the full trajectory of \emph{one} randomly-drawn particle from each one.
+##' One should view these as \emph{weighted} samples from the smoothing distribution, where the weights are the \emph{likelihoods} returned by each of the \code{\link{pfilter}} computations.
 ##'
-##' In particle MCMC (\code{\link{pmcmc}}), this operation is performed at each MCMC iteration.
-##' Assuming the MCMC chain has converged, and after proper measures are taken to assure approximate independence of samples, \code{filter.traj} allows one to extract a sample from the smoothing distribution.
+##' One accomplishes this by setting \code{filter.traj = TRUE} in each \code{\link{pfilter}} computation and extracting the trajectory using the \code{filter.traj} command.
 ##'
+##' In particle MCMC (\code{\link{pmcmc}}), the tracking of an individual trajectory is performed automatically.
+##' 
 ##' @name filter.traj
 ##' @aliases filter.traj filter.traj,ANY-method filter.traj,missing-method
 ##' @include pfilter.R pmcmc.R

R/pred_mean.R

@@ -3,11 +3,11 @@
 ##' The mean of the prediction distribution
 ##'
 ##' The prediction distribution is that of
-##' \deqn{X_t \vert Y_1=y^*_1,\dots,Y_{t-1}=y^*_{t-1},}{Xt | Y1=y1*,\dots,Y(t-1)=y(t-1)*,}
-##' where \eqn{X_t}{Xt}, \eqn{Y_t}{Yt} are the latent state and observable processes, respectively, and \eqn{y^*_t}{yt*} is the data, at time \eqn{t}.
+##' \deqn{X(t_k) \vert Y(t_1)=y^*_1,\dots,Y(t_{k-1})=y^*_{k-1},}{Xk | Y1=y1*,\dots,Y(k-1)=y(k-1)*,}
+##' where \eqn{X(t_k)}{Xk}, \eqn{Y(t_k)}{Yk} are the latent state and observable processes, respectively, and \eqn{y^*_k}{yk*} is the data, at time \eqn{t_k}{tk}.
 ##'
 ##' The prediction mean is therefore the expectation of this distribution
-##' \deqn{E[X_t \vert Y_1=y^*_1,\dots,Y_{t-1}=y^*_{t-1}].}{E[Xt | Y1=y1*,\dots,Y(t-1)=y(t-1)*].}
+##' \deqn{E[X(t_k) \vert Y(t_1)=y^*_1,\dots,Y(t_{k-1})=y^*_{k-1}].}{E[Xk | Y1=y1*,\dots,Y(k-1)=y(k-1)*].}
 ##'
 ##' @name pred.mean
 ##' @aliases pred.mean pred.mean,ANY-method pred.mean,missing-method

R/pred_var.R

@@ -3,11 +3,11 @@
 ##' The variance of the prediction distribution
 ##'
 ##' The prediction distribution is that of
-##' \deqn{X_t \vert Y_1=y^*_1,\dots,Y_{t-1}=y^*_{t-1},}{Xt | Y1=y1*,\dots,Y(t-1)=y(t-1)*,}
-##' where \eqn{X_t}{Xt}, \eqn{Y_t}{Yt} are the latent state and observable processes, respectively, and \eqn{y^*_t}{yt*} is the data, at time \eqn{t}.
+##' \deqn{X(t_k) \vert Y(t_1)=y^*_1,\dots,Y(t_{k-1})=y^*_{k-1},}{Xk | Y1=y1*,\dots,Y(k-1)=y(k-1)*,}
+##' where \eqn{X(t_k)}{Xk}, \eqn{Y(t_k)}{Yk} are the latent state and observable processes, respectively, and \eqn{y^*_k}{yk*} is the data, at time \eqn{t_k}{tk}.
 ##'
 ##' The prediction variance is therefore the variance of this distribution
-##' \deqn{\mathrm{Var}[X_t \vert Y_1=y^*_1,\dots,Y_{t-1}=y^*_{t-1}].}{Var[Xt | Y1=y1*,\dots,Y(t-1)=y(t-1)*].}
+##' \deqn{\mathrm{Var}[X(t_k) \vert Y(t_1)=y^*_1,\dots,Y(t_{k-1})=y^*_{k-1}].}{Var[Xk | Y1=y1*,\dots,Y(k-1)=y(k-1)*].}
 ##'
 ##' @name pred.var
 ##' @aliases pred.var pred.var,ANY-method pred.var,missing-method

TODO.md

@@ -2,7 +2,6 @@
 
 ## For pomp 2:
 
-- correct documentation vis-a-vis smoothing distribution via filter.traj
 - add documentation for existing "todo" issues
 - for log-barycentric transformations, check that parameters are contiguous
 - do we need basic-component arguments at higher levels of the calling hierarchy for documentation purposes?  PROBABLY YES.

inst/NEWS

@@ -7,6 +7,9 @@ _C_h_a_n_g_e_s _i_n '_p_o_m_p' _v_e_r_s_i_o_n _2._3._0:
           reliance on deep ‘PROTECT’ stacks.  Thanks to Thomas Kalibera
           for showing the way!
 
+        • A bug in the documentation for ‘filter.traj’, pointed out by
+          Pierre Jacob, has been fixed.
+
 _C_h_a_n_g_e_s _i_n '_p_o_m_p' _v_e_r_s_i_o_n _2._2._2:
 
         • The C API for ‘pomp’ is no longer explained only in comments

inst/NEWS.Rd

@@ -4,6 +4,7 @@
   \itemize{
     \item The source codes underlying specification of basic model components via \R functions has been reworked to remove reliance on deep \code{PROTECT} stacks.
     Thanks to Thomas Kalibera for showing the way!
+    \item A bug in the documentation for \code{filter.traj}, pointed out by Pierre Jacob, has been fixed.
   }
 }
 \section{Changes in \pkg{pomp} version 2.2.2}{