change userdata interface

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: pomp
 Type: Package
 Title: Statistical Inference for Partially Observed Markov Processes
-Version: 5.8.3.0
-Date: 2024-05-22
+Version: 5.8.4.0
+Date: 2024-05-24
 Authors@R: c(person(given=c("Aaron","A."),family="King",role=c("aut","cre"),email="kingaa@umich.edu",comment=c(ORCID="0000-0001-6159-3207")),
 	  person(given=c("Edward","L."),family="Ionides",role="aut",comment=c(ORCID="0000-0002-4190-0174"))	,
 	  person(given="Carles",family="Bretó",role="aut",comment=c(ORCID="0000-0003-4695-4902")),

R/abc.R

@@ -14,10 +14,9 @@
 ##' @family MCMC methods
 ##' @family Bayesian methods
 ##' @concept approximate Bayesian computation
-##'
-##' @inheritParams pomp
 ##' @inheritParams probe
 ##' @inheritParams pmcmc
+##' @inheritParams pomp
 ##' @param Nabc the number of ABC iterations to perform.
 ##' @param scale named numeric vector of scales.
 ##' @param epsilon ABC tolerance.

R/blowflies.R

@@ -117,9 +117,11 @@ blowflies1 <- function (
     ),
     paramnames=c("P","N0","delta","sigma.P","sigma.d","sigma.y"),
     statenames=c("N1","R","S","e","eps"),
-    y.init=with( ## initial data
-      dat,
-      approx(x=day,y=y,xout=seq(from=0,to=14,by=1),rule=2)$y
+    userdata=list(
+      y.init=with( ## initial data
+        dat,
+        approx(x=day,y=y,xout=seq(from=0,to=14,by=1),rule=2)$y
+      )
     ),
     ## y.init=c(948, 948, 942, 930, 911, 885, 858, 833.7, 801, 748.3, 676, 589.8, 504, 434.9, 397),
     rinit=function (params, t0, y.init, ...) {
@@ -173,11 +175,13 @@ blowflies2 <- function (
     partrans=parameter_trans(
       log=c("P","delta","N0","sigma.P","sigma.d","sigma.y")
     ),
-    y.init=with( ## initial data
-      dat,
-      approx(x=day,y=y,xout=seq(from=0,to=14,by=2),rule=2)$y
+    userdata=list(
+      y.init=with( ## initial data
+        dat,
+        approx(x=day,y=y,xout=seq(from=0,to=14,by=2),rule=2)$y
+      )
+      ## y.init=c(948, 942, 911, 858, 801, 676, 504, 397),
     ),
-    ## y.init=c(948, 942, 911, 858, 801, 676, 504, 397),
     paramnames=c("P","N0","delta","sigma.P","sigma.d","sigma.y"),
     statenames=c("N1","R","S","e","eps"),
     rinit=function (params, t0, y.init, ...) {

R/bsmc2.R

@@ -18,30 +18,23 @@
 ##' @family full-information methods
 ##' @family particle filter methods
 ##' @family estimation methods
-##'
 ##' @importFrom mvtnorm rmvnorm
 ##' @importFrom stats median cov
-##'
-##' @inheritParams pomp
 ##' @inheritParams pfilter
-##'
+##' @inheritParams pomp
 ##' @param smooth Kernel density smoothing parameter.
 ##' The compensating shrinkage factor will be \code{sqrt(1-smooth^2)}.
 ##' Thus, \code{smooth=0} means that no noise will be added to parameters.
 ##' The general recommendation is that the value of \code{smooth} should be chosen close to 0 (e.g., \code{shrink} ~ 0.1).
-##'
 ##' @return
 ##' An object of class \sQuote{bsmcd_pomp}.
 ##' The following methods are avaiable:
 ##' \describe{
 ##' \item{\code{\link[=plot,bsmcd_pomp-method]{plot}}}{produces diagnostic plots}
 ##' \item{\code{\link{as.data.frame}}}{puts the prior and posterior samples into a data frame}
 ##' }
-##'
 ##' @inheritSection pomp Note for Windows users
-##' 
 ##' @author Michael Lavine, Matthew Ferrari, Aaron A. King, Edward L. Ionides
-##'
 ##' @references
 ##'
 ##' \Liu2001b

R/kalman.R

@@ -14,13 +14,12 @@
 ##' @family particle filter methods
 ##' @family elementary algorithms
 ##' @inheritSection pomp Note for Windows users
-##' 
+##' @inheritParams pfilter
 ##' @inheritParams pomp
 ##' @param Np integer; the number of particles to use, i.e., the size of the ensemble.
 ##' 
 ##' @return
 ##' An object of class \sQuote{kalmand_pomp}.
-##'
 ##' @references
 ##'
 ##' \Evensen1994

R/mif2.R

@@ -6,7 +6,6 @@
 ##' This extra variability effectively smooths the likelihood surface and combats particle depletion by introducing diversity into particle population.
 ##' As the iterations progress, the magnitude of the perturbations is diminished according to a user-specified cooling schedule.
 ##' The algorithm is presented and justified in Ionides et al. (2015).
-##'
 ##' @name mif2
 ##' @rdname mif2
 ##' @include pfilter.R workhorses.R pomp_class.R safecall.R continue.R
@@ -17,8 +16,8 @@
 ##' @family estimation methods
 ##' @family methods based on maximization
 ##' @importFrom utils head
-##' @inheritParams pomp
 ##' @inheritParams pfilter
+##' @inheritParams pomp
 ##' @param Nmif The number of filtering iterations to perform.
 ##' @param rw.sd specification of the magnitude of the random-walk perturbations that will be applied to some or all model parameters.
 ##' Parameters that are to be estimated should have positive perturbations specified here.

R/pfilter.R

@@ -22,27 +22,21 @@
 ##' \code{Np(1)}, from \code{timezero(object)} to \code{time(object)[1]},
 ##' and so on,
 ##' while when \code{T=length(time(object))}, \code{Np(T)} is the number of particles to sample at the end of the time-series.
-##'
 ##' @param pred.mean logical; if \code{TRUE}, the prediction means are calculated for the state variables and parameters.
-##'
 ##' @param pred.var logical; if \code{TRUE}, the prediction variances are calculated for the state variables and parameters.
-##'
 ##' @param filter.mean logical; if \code{TRUE}, the filtering means are calculated for the state variables and parameters.
-##'
 ##' @param filter.traj logical; if \code{TRUE}, a filtered trajectory is returned for the state variables and parameters.
 ##' See \code{\link{filter_traj}} for more information.
-##'
 ##' @param save.states character;
 ##' If \code{save.states="unweighted"}, the state-vector for each unweighted particle at each time is saved.
 ##' If \code{save.states="weighted"}, the state-vector for each weighted particle at each time is saved, along with the corresponding weight.
 ##' If \code{save.states="no"}, information on the latent states is not saved.
 ##' \code{"FALSE"} is a synonym for \code{"no"} and \code{"TRUE"} is a synonym for \code{"unweighted"}.
 ##' To retrieve the saved states, applying \code{\link{saved_states}} to the result of the \code{pfilter} computation.
-##'
+##' @param ... additional arguments are passed to \code{\link{pomp}}.
 ##' @return
 ##' An object of class \sQuote{pfilterd_pomp}, which extends class \sQuote{pomp}.
 ##' Information can be extracted from this object using the methods documented below.
-##' 
 ##' @section Methods:
 ##' \describe{
 ##' \item{\code{\link{logLik}}}{ the estimated log likelihood  }
@@ -59,15 +53,12 @@
 ##' \item{\code{\link{as.data.frame}}}{coerce to a data frame}
 ##' \item{\code{\link{plot}}}{diagnostic plots}
 ##' }
-##'
 ##' @references
 ##'
 ##' \Arulampalam2002
 ##'
 ##' \Bhadra2016
-##'
 ##' @example examples/pfilter.R
-##'
 NULL
 
 setClass(

R/pmcmc.R

@@ -17,8 +17,8 @@
 ##' @family Bayesian methods
 ##' 
 ##' @importFrom stats runif
-##' @inheritParams pomp
 ##' @inheritParams pfilter
+##' @inheritParams pomp
 ##' @param Nmcmc The number of PMCMC iterations to perform.
 ##' @param proposal optional function that draws from the proposal
 ##' distribution.  Currently, the proposal distribution must be symmetric for

R/pomp.R

@@ -5,18 +5,18 @@
 ##' One implements the \acronym{POMP} model by specifying some or all of its \emph{basic components}.
 ##' These comprise:
 ##' \describe{
-##' \item{rinit,}{which samples from the distribution of the state process at the zero-time;}
-##' \item{dinit,}{which evaluates the density of the state process at the zero-time;}
-##' \item{rprocess,}{the simulator of the unobserved Markov state process;}
-##' \item{dprocess,}{the evaluator of the probability density function for transitions of the unobserved Markov state process;}
-##' \item{rmeasure,}{the simulator of the observed process, conditional on the unobserved state;}
-##' \item{dmeasure,}{the evaluator of the measurement model probability density function;}
-##' \item{emeasure,}{the expectation of the measurements, conditional on the latent state;}
-##' \item{vmeasure,}{the covariance matrix of the measurements, conditional on the latent state;}
-##' \item{rprior,}{which samples from a prior probability distribution on the parameters;}
-##' \item{dprior,}{which evaluates the prior probability density function;}
-##' \item{skeleton,}{which computes the deterministic skeleton of the unobserved state process;}
-##' \item{partrans,}{which performs parameter transformations.}
+##' \item{rinit}{which samples from the distribution of the state process at the zero-time;}
+##' \item{dinit}{which evaluates the density of the state process at the zero-time;}
+##' \item{rprocess}{the simulator of the unobserved Markov state process;}
+##' \item{dprocess}{the evaluator of the probability density function for transitions of the unobserved Markov state process;}
+##' \item{rmeasure}{the simulator of the observed process, conditional on the unobserved state;}
+##' \item{dmeasure}{the evaluator of the measurement model probability density function;}
+##' \item{emeasure}{the expectation of the measurements, conditional on the latent state;}
+##' \item{vmeasure}{the covariance matrix of the measurements, conditional on the latent state;}
+##' \item{rprior}{which samples from a prior probability distribution on the parameters;}
+##' \item{dprior}{which evaluates the prior probability density function;}
+##' \item{skeleton}{which computes the deterministic skeleton of the unobserved state process;}
+##' \item{partrans}{which performs parameter transformations.}
 ##' }
 ##' The basic structure and its rationale are described in the \emph{Journal of Statistical Software} paper, an updated version of which is to be found on the \href{https://kingaa.github.io/pomp/}{package website}.
 ##'
@@ -118,12 +118,11 @@
 ##' @param accumvars optional character vector;
 ##' contains the names of accumulator variables.
 ##' See \link{accumvars} for a definition and discussion of accumulator variables.
-##' @param ... additional arguments supply new or modify existing model characteristics or components.
-##' See \code{\link{pomp}} for a full list of recognized arguments.
-##'
-##' When named arguments not recognized by \code{\link{pomp}} are provided, these are made available to all basic components via the so-called \dfn{userdata} facility.
+##' @param userdata optional list; the elements of this list will be available to basic model components.
 ##' This allows the user to pass information to the basic components outside of the usual routes of covariates (\code{covar}) and model parameters (\code{params}).
 ##' See \link[=userdata]{userdata} for information on how to use this facility.
+##' @param ... additional arguments will be added to the \code{userdata} list, with a warning.
+##' In a future release, this warning will become an error.
 ##' @param verbose logical; if \code{TRUE}, diagnostic messages will be printed to the console.
 ##' @return
 ##' The \code{pomp} constructor function returns an object, call it \code{P}, of class \sQuote{pomp}.
@@ -159,6 +158,7 @@ pomp <- function (data, times, t0, ...,
   covar, params, accumvars,
   obsnames, statenames, paramnames, covarnames,
   nstatevars, PACKAGE, globals, on_load,
+  userdata,
   cdir = getOption("pomp_cdir", NULL), cfile,
   shlib.args, compile = TRUE,
   verbose = getOption("verbose", FALSE)) {
@@ -180,7 +180,7 @@ pomp <- function (data, times, t0, ...,
       missing(rprior) && missing(dprior) && missing(partrans) &&
       missing(covar) && missing(params) && missing(accumvars) &&
       missing(nstatevars) &&
-      ...length() == 0
+      missing(userdata) && ...length() == 0
   )
     return(as(data,"pomp"))
 
@@ -197,7 +197,7 @@ pomp <- function (data, times, t0, ...,
       params=params,covar=covar,accumvars=accumvars,
       obsnames=obsnames,statenames=statenames,paramnames=paramnames,
       covarnames=covarnames,nstatevars=nstatevars,PACKAGE=PACKAGE,
-      globals=globals,on_load=on_load,
+      globals=globals,on_load=on_load,userdata=userdata,
       cdir=cdir,cfile=cfile,shlib.args=shlib.args,
       compile=compile,verbose=verbose
     ),
@@ -284,11 +284,14 @@ setMethod(
 setMethod(
   "construct_pomp",
   signature=signature(data="array", times="numeric"),
-  definition = function (data, times, ...,
+  definition = function (
+    data, times,
+    ..., userdata,
     rinit, dinit, rprocess, dprocess,
     rmeasure, dmeasure, emeasure, vmeasure,
     skeleton, rprior, dprior,
-    partrans, params, covar) {
+    partrans, params, covar
+  ) {
 
     if (missing(rinit)) rinit <- NULL
     if (missing(dinit)) dinit <- NULL
@@ -318,6 +321,7 @@ setMethod(
     if (is.list(params)) params <- unlist(params)
 
     if (missing(covar)) covar <- covariate_table()
+    if (missing(userdata)) userdata <- list()
 
     pomp_internal(
       data=data,
@@ -336,6 +340,7 @@ setMethod(
       partrans=partrans,
       params=params,
       covar=covar,
+      userdata=userdata,
       ...
     )
 
@@ -354,11 +359,14 @@ setMethod(
 setMethod(
   "construct_pomp",
   signature=signature(data="pomp", times="NULL"),
-  definition = function (data, times, t0, timename, ...,
+  definition = function (
+    data, times, t0, timename,
+    ..., userdata,
     rinit, dinit, rprocess, dprocess,
     rmeasure, dmeasure, emeasure, vmeasure,
     skeleton, rprior, dprior, partrans, params, covar,
-    accumvars, nstatevars, cfile) {
+    accumvars, nstatevars, cfile
+  ) {
 
     times <- data@times
     if (missing(t0)) t0 <- data@t0
@@ -392,6 +400,8 @@ setMethod(
     if (missing(nstatevars)) nstatevars <- data@nstatevars
     else nstatevars <- max(nstatevars[1L],data@nstatevars,na.rm=TRUE)
 
+    if (missing(userdata)) userdata <- list()
+
     if (missing(cfile)) cfile <- NULL
     if (!is.null(cfile)) {
       cfile <- as.character(cfile)
@@ -421,6 +431,7 @@ setMethod(
       covar=covar,
       accumvars=accumvars,
       nstatevars=nstatevars,
+      userdata=userdata,
       params=params,
       .solibs=data@solibs,
       .userdata=data@userdata,
@@ -431,15 +442,20 @@ setMethod(
   }
 )
 
-pomp_internal <- function (data, times, t0, timename, ...,
+pomp_internal <- function (
+  data, times, t0, timename,
+  ...,
   rinit, dinit, rprocess, dprocess,
   rmeasure, dmeasure, emeasure, vmeasure,
   skeleton, rprior, dprior,
   partrans, params, covar, accumvars, obsnames, statenames,
   paramnames, covarnames, nstatevars,
   PACKAGE, globals, on_load, cdir, cfile, shlib.args,
-  compile, .userdata, .solibs = list(),
-  verbose = getOption("verbose", FALSE)) {
+  compile,
+  userdata = list(), .userdata = list(),
+  .solibs = list(),
+  verbose = getOption("verbose", FALSE)
+) {
 
   ## check times
   if (missing(times) || !is.numeric(times) || !all(is.finite(times)) ||
@@ -459,17 +475,20 @@ pomp_internal <- function (data, times, t0, timename, ...,
   else
     timename <- as.character(timename)
 
-  if (missing(.userdata)) .userdata <- list()
   added.userdata <- list(...)
-  if (length(added.userdata)>0) {
-    pMess_("The provided ",
+  if (length(added.userdata)>0L) {
+    pWarn_("The provided ",
       ngettext(length(added.userdata),"object","objects")," ",
       paste(sQuote(names(added.userdata)),collapse=","),
       ngettext(length(added.userdata)," is"," are"),
-      " available for use by POMP basic components."
+      " available for use by POMP basic components.\n",
+      "This option is deprecated: use ",sQuote("userdata"),
+      " to specify the list of such objects explicitly.\n",
+      "In a future release, this warning will become an error."
     )
     .userdata[names(added.userdata)] <- added.userdata
   }
+  .userdata[names(userdata)] <- userdata
 
   if (!is(rprocess,"rprocPlugin")) {
     pStop_(sQuote("rprocess"),

R/probe.R

@@ -23,26 +23,20 @@
 ##' @concept synthetic likelihood
 ##' @family elementary algorithms
 ##' @family summary statistic-based methods
-##'
 ##' @inheritSection pomp Note for Windows users
-##' 
 ##' @include pomp_class.R pomp_fun.R pomp.R
 ##' @importFrom stats quantile
-##'
 ##' @param probes a single probe or a list of one or more probes.
 ##' A probe is simply a scalar- or vector-valued function of one argument that can be applied to the data array of a \sQuote{pomp}.
 ##' A vector-valued probe must always return a vector of the same size.
 ##' A number of useful probes are provided with the package:
 ##' see \link[=basic_probes]{basic probes}.
 ##' @param nsim the number of model simulations to be computed.
-##' @param seed optional integer;
-##' if non-\code{NULL}, the random number generator will be initialized with this seed for simulations.
-##' See \code{\link{simulate}}.
+##' @inheritParams pfilter
+##' @inheritParams simulate
 ##' @inheritParams pomp
-##'
 ##' @return
 ##' \code{probe} returns an object of class \sQuote{probed_pomp}, which contains the data and the model, together with the results of the \code{probe} calculation.
-##'
 ##' @section Methods:
 ##' The following methods are available.
 ##' \describe{