R/rmeasure_spec.R

In marvellous122/R-to-JS: Statistical Inference for Partially Observed Markov Processes

##' The measurement-model simulator
##'
##' Specification of rmeasure
##'
##' @name rmeasure_spec
##' @rdname rmeasure_spec
##' @family information on model implementation
##'
##' @details
##' The measurement model is the link between the data and the unobserved state process.
##' It can be specified either by using one or both of the \code{rmeasure} and \code{dmeasure} arguments.
##'
##' Suppose you have a procedure to simulate observations given the value of the latent state variables.
##' Then you can furnish \preformatted{
##'   rmeasure = f}
##' to \pkg{pomp} algorithms,
##' where \code{f} is a C snippet or \R function that implements your procedure.
##'
##' Using a C snippet is much preferred, due to its much greater computational efficiency.
##' See \code{\link{Csnippet}} for general rules on writing C snippets.
##'
##' In writing an \code{rmeasure} C snippet, bear in mind that:
##'   \enumerate{
##'     \item The goal of such a snippet is to fill the observables with random values drawn from the measurement model distribution.
##'     Accordingly, each observable should be assigned a new value.
##'     \item In addition to the states, parameters, covariates (if any), and observables, the variable \code{t}, containing the time of the observation, will be defined in the context in which the snippet is executed.
##'   }
##'
##' The demos and the tutorials on the \href{https://kingaa.github.io/pomp/}{package website} give examples as well.
##'
##' It is also possible, though far less efficient, to specify \code{rmeasure} using an \R function.
##' In this case, specify the measurement model simulator by furnishing \preformatted{
##'   rmeasure = f}
##' to \code{pomp}, where \code{f} is an \R function with prototype \preformatted{
##'   f(x, t, params, \dots)}
##' It can also take any additional arguments if these are passed along with it in the call to \code{pomp}.
##' When \code{f} is called,
##' \itemize{
##'   \item \code{x} will be a named numeric vector of length \code{nvar}, the number of state variables.
##'   \item \code{t} will be a scalar quantity, the time at which the measurement is made.
##'   \item \code{params} will be a named numeric vector of length \code{npar}, the number of parameters.
##' }
##' \code{f} must return a named numeric vector of length \code{nobs}, the number of observable variables.
##'
##' @section Default behavior:
##' The default \code{rmeasure} is undefined.
##' It will yield missing values (\code{NA}).
NULL