Add missing roxygen coverage for FLCore generics, helpers, and I/O entry points

R/FLModelDeriv.R

@@ -11,6 +11,14 @@
 # http://cran.r-project.org/web/packages/numDeriv/index.html
 
 # computeHessian {{{
+#' @rdname computeHessian
+#' @aliases computeHessian,FLModel-method
+#' @param eps A small perturbation used in the numerical approximation.
+#' @param d Relative step size used to initialise perturbations.
+#' @param zero.tol Threshold used to treat values as zero.
+#' @param r Number of Richardson extrapolation steps.
+#' @param v Reduction factor applied to the perturbation at each Richardson
+#'   iteration.
 setMethod("computeHessian", signature(object="FLModel"),
   function(object, eps=1e-4, d=0.0001,
     zero.tol=sqrt(.Machine$double.eps/7e-7), r=4, v=2) {
@@ -40,6 +48,13 @@ setMethod("computeHessian", signature(object="FLModel"),
 )  # }}}
 
 # computeD  {{{
+#' @rdname computeD
+#' @aliases computeD,FLModel-method
+#' @param params Parameter values passed to the model likelihood. Defaults to
+#'   `as(object@params, "list")`.
+#' @param method Numerical differentiation method. Currently only Richardson
+#'   extrapolation is implemented.
+#' @inheritParams computeHessian
 setMethod("computeD", signature(object="FLModel"),
     function(object, params=as(object@params, 'list'), method="Richardson",
     eps=1e-4, d=0.0001, zero.tol=sqrt(.Machine$double.eps/7e-7), r=4, v=2) {
@@ -134,6 +149,13 @@ setMethod("computeD", signature(object="FLModel"),
 
 # gradient {{{
 # TODO: check and polish
+#' @rdname gradient
+#' @aliases gradient,function,FLPar-method
+#' @param method Numerical differentiation method. Currently only Richardson
+#'   extrapolation is implemented.
+#' @inheritParams computeHessian
+#' @param show.details Should intermediate Richardson approximations be printed?
+#' @param ... Additional arguments passed to `func`.
 setMethod('gradient', signature(func='function', x='FLPar'),
   function(func, x, method="Richardson", eps=1e-4, d=0.0001,
       zero.tol=sqrt(.Machine$double.eps/7e-7), r=4, v=2, show.details=FALSE, ...)
@@ -203,4 +225,3 @@ setMethod('gradient', signature(func='function', x='FLPar'),
   }
 ) # }}}
 
-

R/FLQuant.R

@@ -743,6 +743,24 @@ setMethod("quantile", signature(x="FLQuant"),
 ) # }}}
 
 # iters     {{{
+#' Display the iterations stored in an FLQuant
+#'
+#' `iters()` prints each iteration contained in an [`FLQuant`] together with the
+#' units stored in the object. It is intended as a compact inspection helper
+#' when working with iterated FLR objects.
+#'
+#' @name iters
+#' @rdname iters
+#' @aliases iters iters-methods iters,FLQuant-method
+#' @param object An [`FLQuant`] object.
+#' @return `iters()` is called for its side effect of printing each iteration
+#'   and returns `NULL` invisibly.
+#' @seealso [`iter()`], [`propagate()`], [`FLQuant`]
+#' @author The FLR Team
+#' @keywords methods
+#' @examples
+#' flq <- FLQuant(1:8, dim=c(2, 2, 1, 1, 1, 2))
+#' iters(flq)
 setGeneric("iters", function(object, ...) {
 value  <-  standardGeneric("iters")
 value
@@ -997,6 +1015,24 @@ setMethod("mvrnorm",
 )# }}}
 
 # PV{{{
+#' Calculate plotless variance for a yearly FLQuant time series
+#'
+#' `pv()` calculates the plotless variance index described by Heath (2006) for
+#' a yearly time series stored in an [`FLQuant`].
+#'
+#' @name pv
+#' @rdname pv
+#' @aliases pv pv-methods pv,FLQuant-method
+#' @param object An [`FLQuant`] containing a yearly time series.
+#' @param dist Should the distribution of pairwise distances be returned instead
+#'   of the scalar plotless variance summary?
+#' @return If `dist = FALSE`, a numeric scalar containing plotless variance. If
+#'   `dist = TRUE`, a numeric vector with pairwise scaled distances.
+#' @seealso [`FLQuant`], [`yearVars()`]
+#' @references Heath MR. 2006. Plotted and tabulated indices of change in the
+#'   state of marine ecosystems. *Oikos* 115:573-581.
+#' @author The FLR Team
+#' @keywords methods
 setGeneric("pv", function(object, ...)
 standardGeneric("pv"))
 
@@ -1885,7 +1921,29 @@ setMethod("append", signature(x="FLQuant", values="numeric"),
 #' residuals
 #' @name residuals-FLQuant
 #' @rdname residuals-FLQuant
+#' @title Residual diagnostics for fitted [`FLQuant`] objects
+#'
+#' `residuals()` dispatches to one of the FLCore residual helper methods for an
+#' observed and fitted [`FLQuant`]. The related `rraw()`, `rlog()`,
+#' `rlogstandard()`, `rstandard()` and `rstudent()` methods return residuals on
+#' different scales.
 #'
+#' @aliases rraw rraw-methods rraw,FLQuant,FLQuant-method
+#' @aliases rlog rlog-methods rlog,FLQuant,FLQuant-method
+#' @aliases rlogstandard rlogstandard-methods rlogstandard,FLQuant,FLQuant-method
+#' @aliases rstandard rstandard-methods rstandard,FLQuant,ANY-method
+#' @aliases rstudent rstudent-methods rstudent,FLQuant,ANY-method
+#' @param object,obs,model Observed values as an [`FLQuant`].
+#' @param fit Fitted values as an [`FLQuant`] with dimensions compatible with
+#'   the observed values.
+#' @param type The residual scale to be used by `residuals()`: `"log"`,
+#'   `"logstandard"`, `"standard"` or `"pearson"`, `"student"`, or `"raw"`.
+#' @param sdlog,sd Optional dispersion inputs used by the standardised
+#'   residual methods.
+#' @param internal Should `rstudent()` return internally studentised residuals?
+#' @param ... Additional arguments passed to the selected residual method.
+#' @return An [`FLQuant`] containing residuals on the requested scale.
+#' @seealso [`FLQuant`], [`fitted()`], [`yearVars()`]
 #' @examples
 #' data(ple4)
 #' fit <- rlnorm(1, log(catch(ple4)), 0.1)

R/FLStock.R

@@ -219,6 +219,28 @@ setMethod("vb", signature(x="FLStock", sel="missing"),
   }
 )
 
+#' Calculate exploitable biomass
+#'
+#' `exb()` returns exploitable biomass for an [`FLStock`] object by applying the
+#' selected catchability pattern and weights to stock numbers.
+#'
+#' @name exb
+#' @rdname exb
+#' @aliases exb exb-methods exb,FLStock-method
+#' @param x An [`FLStock`] object.
+#' @param sel Selection pattern to apply, defaulting to `catch.sel(x)`.
+#' @param wt Mean weight to apply, defaulting to `catch.wt(x)`.
+#' @param byage Should exploitable biomass be returned by age rather than
+#'   aggregated over age?
+#' @param ... Additional named slot values temporarily used in the calculation.
+#' @return An [`FLQuant`] containing exploitable biomass.
+#' @details Exploitable biomass is the biomass available to the fishery after
+#'   stock numbers are weighted by mean catch weight and the chosen selectivity
+#'   pattern. Set `byage = TRUE` to keep the age structure instead of
+#'   aggregating over age.
+#' @seealso [`biomass()`], [`vb()`], [`ssb()`], [`FLStock`]
+#' @author The FLR Team
+#' @keywords methods
 # exb
 setGeneric("exb", function(x, ...) standardGeneric("exb"))
 

R/FLlst-methods.R

@@ -150,12 +150,39 @@ setMethod("lapply", signature(X="FLlst"),
 )  # }}}
 
 # lock/unlock {{{
+#' Lock an FLlst object against changes in length
+#'
+#' `lock()` prevents elements being added to or removed from an [`FLlst`]
+#' object by setting its internal lock flag to `TRUE`.
+#'
+#' @name lock
+#' @rdname lock
+#' @aliases lock lock-methods lock,FLlst-method
+#' @param object An [`FLlst`] object.
+#' @return A modified [`FLlst`] object with its `lock` slot updated.
+#' @seealso [`unlock()`], [`FLlst`], [`collapse()`]
+#' @author The FLR Team
+#' @keywords methods
 setGeneric("lock", function(object, ...){
 	standardGeneric("lock")
 })
 
 setMethod("lock", "FLlst", function(object){object@lock <- TRUE; object})
 
+#' Unlock an FLlst object so its length can be modified
+#'
+#' `unlock()` sets the internal `lock` slot to `FALSE`, reversing the effect of
+#' `lock()` and allowing the length of an [`FLlst`] object to be modified
+#' again.
+#'
+#' @name unlock
+#' @rdname unlock
+#' @aliases unlock unlock-methods unlock,FLlst-method
+#' @inheritParams lock
+#' @return A modified [`FLlst`] object with its `lock` slot updated.
+#' @seealso [`lock()`], [`collapse()`], [`FLlst`]
+#' @author The FLR Team
+#' @keywords methods
 setGeneric("unlock", function(object, ...){
 	standardGeneric("unlock")
 })
@@ -271,6 +298,20 @@ setMethod("as.data.frame", signature(x="FLComps", row.names="missing",
 ) # }}}
 
 # collapse {{{
+#' Collapse the iterations stored across an FLlst object
+#'
+#' `collapse()` concatenates the iterations contained in each element of an
+#' [`FLlst`] object into a single [`FLQuant`].
+#'
+#' @name collapse
+#' @rdname collapse
+#' @aliases collapse collapse-methods collapse,FLlst-method
+#' @param x An [`FLlst`] object whose elements share compatible dimensions.
+#' @param ... Unused.
+#' @return An [`FLQuant`] containing all iterations from the elements in `x`.
+#' @seealso [`FLlst`], [`lock()`], [`iter()`], [`propagate()`]
+#' @author The FLR Team
+#' @keywords methods
 setGeneric("collapse", function(x, ...) standardGeneric("collapse"))
 setMethod("collapse", signature(x='FLlst'),
   function(x) {

R/PlotDiagnostics.R

@@ -123,8 +123,26 @@ plotResidAll<-function(resid,obs,prd,hat,indVar,indVar.,Xttl="X",Yttl="Y")
     invisible()
     }
 
+#' Plot diagnostic panels for an FLSR fit
+#'
+#' `plotA()` draws a set of lattice-based diagnostic plots for an [`FLSR`]
+#' object, including fitted relationships, residual plots, autocorrelation
+#' checks and Q-Q plots.
+#'
+#' @name plotA
+#' @rdname plotA
+#' @aliases plotA plotA-methods plotA,FLSR,missing-method
+#' @param x An [`FLSR`] object.
+#' @param y Unused.
+#' @param ... Unused.
+#' @return `plotA()` is called for its side effect of producing diagnostic
+#'   plots and returns `NULL` invisibly.
+#' @seealso [`plot()`], [`residuals()`], [`fitted()`], [`FLSR`]
+#' @author The FLR Team
+#' @keywords methods
 setGeneric('plotA', function(x,y, ...)
 		standardGeneric('plotA'))
+#' @rdname plotA
 setMethod("plotA", signature(x="FLSR", y="missing"),
 
 function(x)

R/genericMethods.R

@@ -1105,6 +1105,21 @@ setGeneric("autoParscale", function(object, ...)
 setGeneric("sigma", function(object, ...)
   standardGeneric("sigma"))
 
+#' Numerically differentiate an FLModel likelihood
+#'
+#' `gradient()` approximates the gradient of a model function with respect to an
+#' [`FLPar`] parameter vector. The related `computeD()` and
+#' `computeHessian()` methods provide first- and second-order numerical
+#' derivatives for [`FLModel`] objects.
+#'
+#' @name gradient
+#' @rdname gradient
+#' @param func A function, generally the likelihood component to be evaluated.
+#' @param x An [`FLPar`] object containing parameter values.
+#' @return For `gradient()`, a numeric vector of first derivatives.
+#' @seealso [`computeD()`], [`computeHessian()`], [`FLModel`], [`FLPar`]
+#' @author The FLR Team
+#' @keywords methods
 # gradient
 setGeneric("gradient", function(func, x, ...)
   standardGeneric("gradient"))
@@ -1117,10 +1132,37 @@ setGeneric("surface", function(fitted, ...)
 setGeneric("parscale", function(object, ...)
   standardGeneric("parscale"))
 
+#' Compute the Hessian matrix for an FLModel
+#'
+#' `computeHessian()` numerically approximates the Hessian matrix of the
+#' likelihood for an [`FLModel`] object.
+#'
+#' @name computeHessian
+#' @rdname computeHessian
+#' @param object An [`FLModel`] object.
+#' @return An array containing the approximated Hessian matrix, with parameter
+#'   names used as dimnames.
+#' @seealso [`computeD()`], [`gradient()`], [`FLModel`]
+#' @author The FLR Team
+#' @keywords methods
 # computeHessian
 setGeneric("computeHessian", function(object, ...)
   standardGeneric("computeHessian"))
 
+#' Compute first and second derivative terms for an FLModel
+#'
+#' `computeD()` numerically approximates first derivatives and the lower
+#' triangle of the Hessian for an [`FLModel`] object, returning the intermediate
+#' matrix used by [`computeHessian()`].
+#'
+#' @name computeD
+#' @rdname computeD
+#' @param object An [`FLModel`] object.
+#' @return A numeric matrix containing first derivatives and second derivative
+#'   terms.
+#' @seealso [`computeHessian()`], [`gradient()`], [`FLModel`]
+#' @author The FLR Team
+#' @keywords methods
 # computeD
 setGeneric("computeD", function(object, ...)
   standardGeneric("computeD"))
@@ -1526,6 +1568,20 @@ setGeneric("uppq<-", function(x, value) standardGeneric("uppq<-"))
 setGeneric("lowq", function(x, ...) standardGeneric("lowq"))
 setGeneric("lowq<-", function(x, value) standardGeneric("lowq<-"))
 
+#' Return the plural class name associated with an object
+#'
+#' `getPlural()` maps an FLCore object class to the corresponding container
+#' class used to store multiple objects of that type.
+#'
+#' @name getPlural
+#' @rdname getPlural
+#' @param object An object for which the plural class name is required.
+#' @return A character vector of length one giving the name of the plural class,
+#'   or `"list"` when no FLCore plural class is defined.
+#' @seealso [`FLlst`], [`FLQuants`], [`FLCohorts`], [`FLStocks`],
+#'   [`FLIndices`], [`FLBiols`], [`FLSRs`], [`FLModelSims`]
+#' @author The FLR Team
+#' @keywords methods
 # getPlural
 setGeneric("getPlural", function(object, ...) standardGeneric("getPlural"))
 
@@ -2063,4 +2119,3 @@ setGeneric("se", function(x, ...) standardGeneric("se"))
 setGeneric("biomass", function(x, ...) standardGeneric("biomass"))
 
 setGeneric("depletion", function(x, ...) standardGeneric("depletion"))
-

R/getPlural.R

@@ -7,41 +7,57 @@
 
 
 # ANY -> list
+#' @rdname getPlural
+#' @aliases getPlural,ANY-method
 setMethod('getPlural', signature(object='ANY'),
 	function(object) {
 		return('list')})
 
 # FLQuant -> FLQuants
+#' @rdname getPlural
+#' @aliases getPlural,FLQuant-method
 setMethod('getPlural', signature(object='FLQuant'),
 	function(object) {
 		return('FLQuants')})
 
 # FLCohort -> FLCohorts
+#' @rdname getPlural
+#' @aliases getPlural,FLCohort-method
 setMethod('getPlural', signature(object='FLCohort'),
 	function(object) {
 		return('FLCohorts')})
 
 # FLStock -> FLStocks
+#' @rdname getPlural
+#' @aliases getPlural,FLS-method
 setMethod('getPlural', signature(object='FLS'),
 	function(object) {
 		return('FLStocks')})
 
 # FLIndex -> FLIndices
+#' @rdname getPlural
+#' @aliases getPlural,FLI-method
 setMethod('getPlural', signature(object='FLI'),
 	function(object) {
 		return('FLIndices')})
 
 # FLBiol -> FLBiols
+#' @rdname getPlural
+#' @aliases getPlural,FLBiol-method
 setMethod('getPlural', signature(object='FLBiol'),
 	function(object) {
 		return('FLBiols')})
 
 # FLSR -> FLSRs
+#' @rdname getPlural
+#' @aliases getPlural,FLSR-method
 setMethod('getPlural', signature(object='FLSR'),
 	function(object) {
 		return('FLSRs')})
 
 # FLModelSim -> FLModelSims
+#' @rdname getPlural
+#' @aliases getPlural,FLModelSim-method
 setMethod('getPlural', signature(object='FLModelSim'),
 	function(object) {
 		return('FLModelSims')})