Improve roxygen2 documentation

R/make-data.R

@@ -7,7 +7,7 @@
 ##'   element of \code{y}.
 ##' @param site an \code{vector} indicating the sites associated to each element
 ##'   of \code{y}.
-##' @param init_data an optional vector (of lengh n_ages - 1) to initialize the
+##' @param init_data an optional vector (of length n_ages - 1) to initialize the
 ##'   population dynamics.
 ##' @param f_mort an optional \code{matrix} informing the instantaneous fishing
 ##'   mortality rates at each age (columns) and timepoint (rows).
@@ -23,13 +23,6 @@
 ##' @param age_selectivity an \code{numeric vector} with \code{n_ages} elements,
 ##'   where each element indicates the selectivity of a respective age. All the
 ##'   elements of this vector must lie between 0 and 1.
-##' @param ages_movement a \code{integer} indicating the age at which
-##'   individuals from the focal species start moving. In this case, individuals
-##'   below this age threshold remain "static". Alternatively, we can input a
-##'   \code{vector} of length \code{n_ages}. This vector will have a \code{0}
-##'   for age-groups that cannot move and \code{1} for those age-groups that
-##'   move. For example, the following vector \code{c(0, 0, 1, 1, 0)} indicates
-##'   that ages 1, 2, and 5 are static, while ages 3 and 4 are allowed to move.
 ##' @param ages_movement An \code{integer} or a \code{numeric vector} specifying
 ##'   the ages at which individuals of the focal species are assumed to move. If
 ##'   \code{ages_movement} is an integer, individuals younger than this age are
@@ -43,24 +36,28 @@
 ##'   \eqn{\times} \code{sites}. Its elements are 1 if two sites are neighbors
 ##'   and zero otherwise.
 ##' @param .toggles a \code{list} of toggles for model components. The
-##'   components are: \itemize{ \item \code{rho_mu}: 1 to use explicitly relates
-##'   rho to mu and 0 otherwise. \item \code{cloglog}: 1 to use the
-##'   complementary log-log and 0 for the logit link function for the absence
-##'   probabilities.  \item \code{movement}: 1 to allow for (adjacent) moviment;
-##'   0 for static.  \item \code{est_surv}: 1 to estimate mortality and 0
-##'   otherwise.  \item \code{est_init}: 1 to estimate initial values for lambda
-##'   and 0 otherwise.  \item \code{minit}: 1 to use mortality to estimate
-##'   initial age classes and 0 otherwise.  \item \code{ar_re}: a
-##'   \code{character}. It assumes one of the following values: "none" - no AR,
-##'   "rec" AR(1) for recruitment, "surv" - AR(1) for survival (only works when
-##'   \code{est_surv} is on), "dens" - AR(1) for density.  \item \code{iid_re}:
-##'   a \code{character}. It assumes one of the following values: "none" - no
-##'   iid re, "rec" iid re for recruitment, "surv" - iir re for survival (only
-##'   works when \code{est_surv} is on), "dens" - iid_re for density.  \item
-##'   \code{sp_re}: a \code{character}. It assumes one of the following values:
-##'   "none" - no ICAR re, "rec" ICAR re for recruitment, "surv" - ICAR re for
-##'   survival (only works when \code{est_surv} is on), "dens" - ICAR_re for
-##'   density.}
+##'   components are: \itemize{
+##'   \item \code{rho_mu}: 1 to use explicitly relates rho to mu and 0 otherwise.
+##'   \item \code{cloglog}: 1 to use the complementary log-log and 0 for the
+##'   logit link function for the absence probabilities.
+##'   \item \code{movement}: 1 to allow for (adjacent) moviment; 0 for static.
+##'   \item \code{est_surv}: 1 to estimate mortality and 0 otherwise.
+##'   \item \code{est_init}: 1 to estimate initial values for lambda and 0
+##'   otherwise.
+##'   \item \code{minit}: 1 to use mortality to estimate initial age classes and
+##'   0 otherwise.
+##'   \item \code{ar_re}: a \code{character}. It assumes one of the following
+##'   values: "none" - no AR, "rec" AR(1) for recruitment, "surv" - AR(1) for
+##'   survival (only works when \code{est_surv} is on), "dens" - AR(1) for
+##'   density.
+##'   \item \code{iid_re}: a \code{character}. It assumes one of the following
+##'   values: "none" - no iid re, "rec" iid re for recruitment, "surv" - iir re
+##'   for survival (only works when \code{est_surv} is on), "dens" - iid_re for
+##'   density.
+##'   \item \code{sp_re}: a \code{character}. It assumes one of the following
+##'   values: "none" - no ICAR re, "rec" ICAR re for recruitment, "surv" - ICAR
+##'   re for survival (only works when \code{est_surv} is on), "dens" - ICAR_re
+##'   for density.}
 ##' @param .priors a \code{list} of priors hyperparameters.
 ##' @param reorder a \code{boolean} telling whether the data needs to be
 ##'   reordered. The default is TRUE and means the data points will be ordered
@@ -70,10 +67,10 @@
 ##'   \code{"gamma"} (default): gamma parametrized in terms of its mean; \item
 ##'   \code{"lognormal"}: log-normal parametrized in terms of its mean; \item
 ##'   \code{"loglogistic"}: log-logistic parametrized in terms of its mean.
-##'   \item \code{"lognormal_legacy"} (default): log-normal with its usual
+##'   \item \code{"lognormal_legacy"}: log-normal with its usual
 ##'   parametrization; }
 ##' @param phi_hat a \code{boolean} indicating whether the prior on \code{phi}
-##'   should be determined through the data.
+##'   should be determined through the data (using [get_phi_hat()]).
 ##' @return a \code{list} to be used as the input for a \code{stan} model
 ##' @author lcgodoy
 ##' @export
@@ -308,10 +305,10 @@ make_data <- function(y,
 ##'   \code{"gamma"} (default): gamma parametrized in terms of its mean; \item
 ##'   \code{"lognormal"}: log-normal parametrized in terms of its mean; \item
 ##'   \code{"loglogistic"}: log-logistic parametrized in terms of its mean.
-##'   \item \code{"lognormal_legacy"} (default): log-normal with its usual
+##'   \item \code{"lognormal_legacy"}: log-normal with its usual
 ##'   parametrization; }
 ##' @param phi_hat a \code{boolean} indicating whether the prior on \code{phi}
-##'   should be determined through the data.
+##'   should be determined through the data (using [get_phi_hat()]).
 ##' @return a \code{list} to be used as the input for a \code{stan} model
 ##' @author lcgodoy
 ##' @export

R/model-run.R

@@ -11,12 +11,12 @@
 ##' @param site_col A \code{character} specifying the name of the column in
 ##'   `.data` that contains the site variable.
 ##' @param family a \code{character} specifying the family of the probability
-##'   distribution assumed for density. The options are: \itemize{ \item
-##'   \code{"gamma"} (default): gamma parametrized in terms of its mean; \item
-##'   \code{"lognormal"}: log-normal parametrized in terms of its mean; \item
-##'   \code{"loglogistic"}: log-logistic parametrized in terms of its mean.
-##'   \item \code{"lognormal_legacy"} (default): log-normal with its usual
-##'   parametrization; }
+##'   distribution assumed for density. The options are: \itemize{
+##'   \item \code{"gamma"} (default): gamma parametrized in terms of its mean;
+##'   \item \code{"lognormal"}: log-normal parametrized in terms of its mean;
+##'   \item \code{"loglogistic"}: log-logistic parametrized in terms of its mean.
+##'   \item \code{"lognormal_legacy"}: log-normal with its usual parametrization;
+##'    }
 ##' @param formula_zero A \code{formula} specifying the model for the zero
 ##'   inflation component. Defaults to `~ 1` (intercept only).
 ##' @param formula_rec A \code{formula} specifying the model for the recruitment
@@ -40,10 +40,12 @@
 ##'   \code{list} for our \code{cmdstanr} model.
 ##' @return A \code{list} containing the MCMC draws, the model data, the linear
 ##'   predictors formulas, and the (response, time, site) column names.
-##'   Specifically: \itemize{ \item \code{stanfit}: The MCMC draws from the
-##'   fitted model.  \item\code{data}: The data used to fit the model (as a
-##'   list).  \item\code{formulas}: The formulas used to create design matrices.
-##'   \item\code{cols}: Important column names.  }
+##'   Specifically: \itemize{
+##'    \item \code{stanfit}: The MCMC draws from the fitted model.
+##'    \item \code{data}: The data used to fit the model (as a list).
+##'    \item \code{formulas}: The formulas used to create design matrices.
+##'    \item \code{cols}: Important column names.
+##'   }
 ##' @seealso [make_data()]
 ##' @examples
 ##' if (instantiate::stan_cmdstan_exists()) {
@@ -157,7 +159,7 @@ fit_drm <- function(.data,
 ##'   \item \code{"gamma"} (default): gamma parametrized in terms of its mean;
 ##'   \item \code{"lognormal"}: log-normal parametrized in terms of its mean;
 ##'   \item \code{"loglogistic"}: log-logistic parametrized in terms of its mean.
-##'   \item \code{"lognormal_legacy"} (default): log-normal with its usual parametrization;
+##'   \item \code{"lognormal_legacy"}: log-normal with its usual parametrization;
 ##'    }
 ##' @param formula_zero A \code{formula} specifying the model for the zero
 ##'   inflation component. Defaults to `~ 1` (intercept only).
@@ -183,9 +185,9 @@ fit_drm <- function(.data,
 ##'   predictors formulas, and the (response, time, site) column names.
 ##'    \itemize{
 ##'     \item \code{stanfit}: The MCMC draws from the fitted model.
-##'     \item\code{data}: The data used to fit the model (as a list).
-##'     \item\code{formulas}: The data used to fit the model (as a list).
-##'     \item\code{cols}: Important column names.
+##'     \item \code{data}: The data used to fit the model (as a list).
+##'     \item \code{formulas}: The formulas used to create design matrices.
+##'     \item \code{cols}: Important column names.
 ##'   }
 ##' @seealso [make_data()]
 ##' @examples

R/predict.R

@@ -182,14 +182,8 @@ predict.adrm <- function(x,
 ##' @description Considering a new dataset (across the same patches), computes
 ##'   forecasts based on the SDM passed as \code{sdm}.
 ##'
-##' @description Consider a linear predictor having linear and square terms
-##'   associated with a variable \eqn{x}. Assume this variable was centered
-##'   before being included in the linear predictor. This functions returns the
-##'   value of \eqn{x} (on its original scale) such that the linear predictor is
-##'   maximized (or minimized).
+##' @param sdm A \code{list} object containing the output of a [fit_sdm] call.
 ##'
-##' @param x A \code{adrm} (or \code{sdm}) object containing the output from the
-##'   [fit_drm()] (or [fit_sdm()]) function.
 ##' @param new_data a \code{data.frame} with the dataset at which we wish to
 ##'   obtain predictions.
 ##' @param seed a seed used for the forecasts. Forecasts are obtained through
@@ -205,8 +199,9 @@ predict.adrm <- function(x,
 ##'
 ##' @author lcgodoy
 ##'
-##' @return an object of class \code{"CmdStanGQ"} containing samples for the
-##'   posterior predictive distribution for forecasting.
+##' @return An object of class \code{CmdStanGQ} (from the \code{instantiate}
+##'   package) containing samples for the posterior predictive distribution for
+##'   forecasting.
 ##'
 ##' @rdname predsdm
 predict.sdm <- function(x,

R/utils.R

@@ -1,12 +1,12 @@
 ##' @title Regression coefficient for non-centered variable
 ##' @description Consider a linear predictor having linear and square terms
 ##'   associated with a variable \eqn{x}. Assume this variable was centered
-##'   before being included in the linear predictor. This functions recovers the
-##'   regression coefficient associated to the linear term as if the variable
+##'   before being included in the linear predictor. This function recovers the
+##'   regression coefficient associated with the linear term as if the variable
 ##'   was not centered.
-##' @param beta1 A \code{numeric} regression coefficient associated to the
+##' @param beta1 A \code{numeric} regression coefficient associated with the
 ##'   linear term.
-##' @param beta2 A \code{numeric} regression coefficient associated to the
+##' @param beta2 A \code{numeric} regression coefficient associated with the
 ##'   quadratic term.
 ##' @param offset a \code{numeric} representing the "center" of \eqn{x}.
 ##' @return a \code{numeric} representing the regression coefficient of the
@@ -21,12 +21,12 @@ fix_linbeta <- function(beta1, beta2, offset) {
 ##'   quadratic model.
 ##' @description Consider a linear predictor having linear and square terms
 ##'   associated with a variable \eqn{x}. Assume this variable was centered
-##'   before being included in the linear predictor. This functions returns the
+##'   before being included in the linear predictor. This function returns the
 ##'   value of \eqn{x} (on its original scale) such that the linear predictor is
 ##'   maximized (or minimized).
-##' @param beta1 A \code{numeric} regression coefficient associated to the
+##' @param beta1 A \code{numeric} regression coefficient associated with the
 ##'   linear term.
-##' @param beta2 A \code{numeric} regression coefficient associated to the
+##' @param beta2 A \code{numeric} regression coefficient associated with the
 ##'   quadratic term.
 ##' @param offset a \code{numeric} representing the "center" of \eqn{x}.
 ##' @return a \code{numeric} representing the uncentered \eqn{x} that maximizes
@@ -72,7 +72,7 @@ gen_adj <- function(x) {
 ##' @title Modifying a named list
 ##' @param original a named \code{list} with "original" parameters.
 ##' @param replacements a named \code{list} containing elements to be modified
-##'   in the \code{original} \code{list}
+##'   in the \code{original} \code{list}.
 ##' @return an updated \code{original list}.
 ##' @author lcgodoy
 safe_modify <- function(original, replacements) {
@@ -262,7 +262,7 @@ marg_surv <- function(drm, newdata) {
 ##' @title Random effects verbose to code
 ##' @param x a \code{character}
 ##' @return a \code{integer}
-##' @author lcgogoy
+##' @author lcgodoy
 fix_re <- function(x) {
   if (!x %in% c(0:3)) {
     switch(x,