Migrate all MARSS docs to Roxygen2 (bulk .Rd → Roxygen2 conversion)

R/CSEGriskfigure.R

@@ -1,3 +1,52 @@
+#' Plot Extinction Risk Metrics
+#'
+#' @description
+#' Generates a six-panel plot of extinction risk metrics used in Population Viability Analysis (PVA). This is a function used by one of the vignettes in the [MARSS-package()].
+#'
+#' @param data A data matrix with 2 columns; time in first column and counts in second column. Note time is down rows, which is different than the base [MARSS-package()] functions.
+#' @param te Length of forecast period (positive integer)
+#' @param absolutethresh Is extinction threshold an absolute number? (T/F)
+#' @param threshold Extinction threshold either as an absolute number, if `absolutethresh=TRUE`, or as a fraction of current population count, if `absolutethresh=FALSE`.
+#' @param datalogged Are the data already logged? (T/F)
+#' @param silent Suppress printed output? (T/F)
+#' @param return.model Return state-space model as [marssMLE()] object? (T/F)
+#' @param CI.method Confidence interval method: "hessian", "parametric", "innovations", or "none". See [MARSSparamCIs()].
+#' @param CI.sim Number of simulations for bootstrap confidence intervals (positive integer).
+#'
+#' @details
+#' * Panel 1: Time-series plot of the data.
+#' * Panel 2: CDF of extinction risk.
+#' * Panel 3: PDF of time to reach threshold.
+#' * Panel 4: Probability of reaching different thresholds during forecast period.
+#' * Panel 5: Sample projections.
+#' * Panel 6: TMU plot (uncertainty as a function of the forecast).
+#'
+#' @return
+#' If `return.model=TRUE`, an object of class [marssMLE()].
+#'
+#' @references
+#' Holmes, E. E., E. J. Ward, and M. D. Scheuerell (2012) Analysis of multivariate time-series using the MARSS package. NOAA Fisheries, Northwest Fisheries Science
+#' Center, 2725 Montlake Blvd E., Seattle, WA 98112   Type `RShowDoc("UserGuide",package="MARSS")` to open a copy.
+#'
+#' (theory behind the figure) Holmes, E. E., J. L. Sabo, S. V. Viscido, and W. F. Fagan. (2007) A statistical approach to quasi-extinction forecasting. Ecology Letters 10:1182-1198.
+#'
+#' (CDF and PDF calculations) Dennis, B., P. L. Munholland, and J. M. Scott. (1991) Estimation of growth and extinction parameters for endangered species. Ecological Monographs 61:115-143.
+#'
+#' (TMU figure) Ellner, S. P. and E. E. Holmes. (2008) Resolving the debate on when extinction risk is predictable. Ecology Letters 11:E1-E5.
+#'
+#' @author
+#' Eli Holmes, NOAA, Seattle, USA, and Steve Ellner, Cornell Univ.
+#'
+#' @seealso [MARSSboot()], [marssMLE()], [CSEGtmufigure()]
+#'
+#' @examples
+#' d <- harborSeal[, 1:2]
+#' kem <- CSEGriskfigure(d, datalogged = TRUE)
+#'
+#' @name CSEGriskfigure
+#' @aliases CSEGriskfigure
+#' @keywords experimental hplot
+#' @export
 CSEGriskfigure <- function(data, te = 100, absolutethresh = FALSE, threshold = 0.1, datalogged = FALSE, silent = FALSE, return.model = FALSE, CI.method = "hessian", CI.sim = 1000) {
   if (!(CI.method %in% c("hessian", "parametric", "innovations", "none"))) {
     stop("Stopped in CSEGriskfigure(): Allowed values of 'CI.method' are \"none\", \"hessian\", \"parametric\", and \"innovations\".\n", call. = FALSE)

R/CSEGtmufigure.R

@@ -1,3 +1,56 @@
+#' Plot Forecast Uncertainty
+#'
+#' @description
+#' Plot the uncertainty in the probability of hitting a percent threshold
+#' (quasi-extinction) for a single random walk trajectory. This is the
+#' quasi-extinction probability used in Population Viability Analysis. The
+#' uncertainty is shown as a function of the forecast, where the forecast is
+#' defined in terms of the forecast length (number of time steps) and
+#' forecasted decline (percentage). This is a function used by one of the
+#' vignettes in the [MARSS-package].
+#'
+#' @param N Time steps between the first and last population data point (positive integer)
+#' @param u Per time-step decline (-0.1 means a 10\% decline per time step; 1 means a doubling per time step.)
+#' @param s2p Process variance (Q). (a positive number)
+#' @param make.legend Add a legend to the plot? (T/F)
+#'
+#' @details
+#' This figure shows the region of high uncertainty in dark grey. In this
+#' region, the minimum 95 percent confidence intervals on the probability of
+#' quasi-extinction span 80 percent of the 0 to 1 probability. Green hashing
+#' indicates where the 95 percent upper bound does not exceed 5\% probability
+#' of quasi-extinction. The red hashing indicates, where the 95 percent lower
+#' bound is above 95\% probability of quasi-extinction. The light grey lies
+#' between these two certain/uncertain extremes. The extinction calculation is
+#' based on Dennis et al. (1991). The minimum theoretical confidence interval
+#' is based on Fieberg and Ellner (2000). This figure was developed in Ellner
+#' and Holmes (2008).
+#'
+#' Examples using this figure are shown in the
+#' [User Guide](https://cran.r-project.org/package=MARSS/vignettes/UserGuide.pdf)
+#' in the PVA chapter.
+#'
+#' @references
+#' Dennis, B., P. L. Munholland, and J. M. Scott. (1991) Estimation of growth
+#' and extinction parameters for endangered species. Ecological Monographs
+#' 61:115-143.
+#'
+#' Fieberg, J. and Ellner, S.P. (2000) When is it meaningful to estimate an
+#' extinction probability? Ecology, 81, 2040-2047.
+#'
+#' Ellner, S. P. and E. E. Holmes. (2008) Resolving the debate on when
+#' extinction risk is predictable. Ecology Letters 11:E1-E5.
+#'
+#' @author
+#' Eli Holmes, NOAA, Seattle, USA, and Steve Ellner, Cornell Univ.
+#'
+#' @seealso [CSEGriskfigure()]
+#'
+#' @examples
+#' CSEGtmufigure(N = 20, u = -0.1, s2p = 0.01)
+#'
+#' @keywords experimental hplot
+#' @export
 # This is a figure of the theoretical minimum uncertainty regions
 # sensu Ellner and Holmes figure 1
 # Code written by Steven Ellner and Eli Holmes