Update and improve roxygen2 documentation

R/defaults.R

@@ -1,7 +1,7 @@
 ##' Returns default priors' hyperparameters for the DRM model.
 ##'
 ##' @title Default priors' hyperparameters
-##' @return a `list` with (explain values)
+##' @return A \code{list} containing the default hyperparameter values for the priors.
 ##' @author lcgodoy
 ##' @export
 default_priors <- function() {
@@ -32,7 +32,7 @@ default_priors <- function() {
 ##' Returns default toggles for the DRM model.
 ##'
 ##' @title Default toggles
-##' @return a `list` with (explain values)
+##' @return A \code{list} containing the default values for model toggles.
 ##' @author lcgodoy
 ##' @export
 default_toggles <- function() {
@@ -49,8 +49,8 @@ default_toggles <- function() {
 
 ##' Returns default for NUTS
 ##'
-##' @title Default nuts arguments
-##' @return a `list` with (explain values)
+##' @title Default NUTS arguments
+##' @return A \code{list} containing the default arguments for the NUTS algorithm.
 ##' @author lcgodoy
 ##' @export
 default_nuts <- function() {
@@ -83,7 +83,7 @@ default_nuts <- function() {
 ##' Returns default for Variational Bayes
 ##'
 ##' @title Default VB arguments
-##' @return a `list` with (explain values)
+##' @return A \code{list} containing the default arguments for the Variational Bayes algorithm.
 ##' @author lcgodoy
 ##' @export
 default_vb <- function() {
@@ -108,7 +108,7 @@ default_vb <- function() {
 ##' Returns default for Pathfinder
 ##'
 ##' @title Default Pathfinder arguments
-##' @return a `list` with (explain values)
+##' @return A \code{list} containing the default arguments for the Pathfinder algorithm.
 ##' @author lcgodoy
 ##' @export
 default_pf <- function() {
@@ -137,7 +137,7 @@ default_pf <- function() {
 ##' Returns default for Laplace
 ##'
 ##' @title Default Laplace arguments
-##' @return a `list` with (explain values)
+##' @return A \code{list} containing the default arguments for the Laplace algorithm.
 ##' @author lcgodoy
 ##' @export
 default_laplace <- function() {
@@ -152,10 +152,10 @@ default_laplace <- function() {
        save_cmdstan_config = NULL)
 }
 
-##' Returns default for Laplace
+##' Returns default for Optimization
 ##'
-##' @title Default Laplace arguments
-##' @return a `list` with (explain values)
+##' @title Default Optimization arguments
+##' @return A \code{list} containing the default arguments for the Optimization algorithm.
 ##' @author lcgodoy
 ##' @export
 default_opt <- function() {
@@ -180,7 +180,7 @@ default_opt <- function() {
 ##'
 ##' @title Default arguments for inference algorithm
 ##' @inheritParams fit_drm
-##' @return a `list` with (explain values)
+##' @return A \code{list} containing the default arguments for the specified algorithm.
 ##' @author lcgodoy
 ##' @export
 default_algo <- function(algorithm = "nuts",

R/generics.R

@@ -49,7 +49,7 @@ validate_sdm <- function(x) {
 ##'
 ##' Constructs an object of class `sdm` from a list, after validating its
 ##' structure. Note that, this function is mostly for internal usage. `sdm`
-##' stands for age-structured dynamic range model.
+##' stands for species distribution model.
 ##'
 ##' @param x A `list` that has the required fields for an 'sdm' object.
 ##'   Defaults to an empty `list`.

R/make-data.R

@@ -3,9 +3,9 @@
 ##'
 ##' @title Make data for DRM stan models
 ##' @param y a \code{numeric vector} of species' densities.
-##' @param time an \code{vector} indicating the time point associated to each
+##' @param time a \code{vector} indicating the time point associated to each
 ##'   element of \code{y}.
-##' @param site an \code{vector} indicating the sites associated to each element
+##' @param site a \code{vector} indicating the sites associated to each element
 ##'   of \code{y}.
 ##' @param init_data an optional vector (of length n_ages - 1) to initialize the
 ##'   population dynamics.
@@ -20,7 +20,7 @@
 ##' @param x_r a design \code{matrix} of variables associated to recruitment.
 ##' @param n_ages an \code{integer} indicating the number of ages for the
 ##'   underlying population dynamic model.
-##' @param age_selectivity an \code{numeric vector} with \code{n_ages} elements,
+##' @param age_selectivity a \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 An \code{integer} or a \code{numeric vector} specifying
@@ -36,10 +36,10 @@
 ##'   \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
+##'   components are: \itemize{ \item \code{rho_mu}: 1 to explicitly relate
 ##'   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;
+##'   probabilities.  \item \code{movement}: 1 to allow for (adjacent) movement;
 ##'   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
@@ -67,7 +67,8 @@
 ##'   its usual parametrization; }
 ##' @param phi_hat a \code{boolean} indicating whether the prior on \code{phi}
 ##'   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
+##' @return A \code{list} containing the data and settings to be used as input
+##'   for the Stan model.
 ##' @author lcgodoy
 ##' @export
 make_data <- function(y,
@@ -269,9 +270,9 @@ make_data <- function(y,
 ##'
 ##' @title Make data for SDM stan models
 ##' @param y a \code{numeric vector} of species' densities.
-##' @param time an \code{vector} indicating the time point associated to each
+##' @param time a \code{vector} indicating the time point associated to each
 ##'   element of \code{y}.
-##' @param site an \code{vector} indicating the sites associated to each element
+##' @param site a \code{vector} indicating the sites associated to each element
 ##'   of \code{y}.
 ##' @param z a design \code{matrix} of variables associated to the probability
 ##'   of absence at each site/time.
@@ -281,12 +282,10 @@ make_data <- function(y,
 ##'   \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 relate
+##'   components are: \itemize{\item \code{rho_mu}: 1 to explicitly relate
 ##'   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 survival rates and 0
-##'   otherwise. \item \code{ar_re}: 1 to incorporate an AR(1) process to
+##'   probabilities. \item \code{ar_re}: 1 to incorporate an AR(1) process to
 ##'   density and 0 otherwise. \item \code{iid_re}: 1 to incorporate a patch
 ##'   specific IID random effect to density and 0 otherwise. \item \code{sp_re}:
 ##'   1 to incorporate a patch specific ICAR random effect to density and 0
@@ -304,7 +303,8 @@ make_data <- function(y,
 ##'   its usual parametrization; }
 ##' @param phi_hat a \code{boolean} indicating whether the prior on \code{phi}
 ##'   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
+##' @return A \code{list} containing the data and settings to be used as input
+##'   for the Stan model.
 ##' @author lcgodoy
 ##' @export
 make_data_sdm <- function(y,

R/methods.R

@@ -220,13 +220,12 @@ print.summary.sdm <- function(x, digits = 3, ...) {
 ##'   to retrieve the samples from the posterior distribution of the models'
 ##'   parameters.
 ##'
-##' @param x A \code{list} object containing the output from the [fit_drm()] (or
-##'   [fit_sdm()]) function.
+##' @param x An object of class \code{adrm} or \code{sdm}.
 ##' @param variables a string vector with the name of the variables for which we
 ##'   want to obtain posteriors samples (defaults to the same variables as the
-##'   \code{summary} methods.
+##'   \code{summary} methods).
 ##' @param inc_warmup a boolean indicating whether the warmup samples should be
-##'   retrieved as well. Defaults to \code{FALSE}
+##'   retrieved as well. Defaults to \code{FALSE}.
 ##' @param format A string. See cmdstanr [$draws
 ##'   documentation](https://mc-stan.org/cmdstanr/reference/fit-method-draws.html).
 ##' @param ... currently ignored.
@@ -235,7 +234,6 @@ print.summary.sdm <- function(x, digits = 3, ...) {
 ##' @return an object of class \code{"draws"} containing the posterior samples
 ##'   from specified parameters.
 ##' @name draws
-##' @author lcgodoy
 ##' @export
 draws <- function(x, ...) UseMethod("draws", x)
 

R/model-run.R

@@ -2,7 +2,7 @@
 ##' @export
 ##' @family models
 ##' @description Fit the DRM Stan model (this function is not stable yet and
-##'   have not been fully tested).
+##'   has not been fully tested).
 ##' @param .data A \code{data frame} containing the data for the model.
 ##' @param y_col A \code{character} specifying the name of the column in `.data`
 ##'   that contains the response variable.
@@ -25,22 +25,24 @@
 ##'   component. If `NULL` (the default), no survival component is included.
 ##' @param seed An \code{integer} specifying the random number seed.
 ##' @param init A scalar specifying the initialization method. The default
-##'   (NULL) represents the \code{cmdstan} default, a scalar greater than zero,
-##'   say \code{x}, initialized all parameters from a uniform between \code{-x}
-##'   and \code{x}, a \code{0} initialize all parameters at \code{0}, or "prior"
-##'   (to initialize the model parameters using samples from their prior)
+##'   ("cmdstan_default") lets \code{cmdstan} initialize parameters.
+##'   Other options include: a scalar greater than zero, say \code{x}, which
+##'   initializes all parameters uniformly between \code{-x} and \code{x};
+##'   \code{0}, which initializes all parameters at \code{0}; or "prior",
+##'   which initializes parameters by sampling from their priors.
 ##' @param algorithm a \code{character} specifying the algorithm used for
 ##'   inference. Default is \code{nuts} (the default MCMC in Stan). The
 ##'   remaining options are different flavors of variational bayes algorithms:
 ##'   "vb" (for ADVI), "pathfinder" (for Pathfinder), "laplace" (normal
 ##'   approximation centered at the mode of the posterior) or "optimize" for
 ##'   (penalized) MLEs.
 ##' @param algo_args a \code{list} with arguments for the sampling
-##'   algorithms. For instance, \code{tol_rel_obj} for variational .
+##'   algorithms. For instance, \code{tol_rel_obj} for variational inference.
 ##' @param ... Passed on to the [make_data()] function used to build the input
 ##'   \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.
+##' @return An object of class \code{adrm} which is 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
@@ -151,7 +153,7 @@ fit_drm <- function(.data,
 ##' @export
 ##' @family models
 ##' @description Fit the SDM Stan model (this function is not stable yet and
-##'   have not been fully tested).
+##'   has not been fully tested).
 ##' @param .data A \code{data frame} containing the data for the model.
 ##' @param y_col A \code{character} specifying the name of the column in `.data`
 ##'   that contains the response variable.
@@ -173,29 +175,31 @@ fit_drm <- function(.data,
 ##'   density component. Defaults to `~ 1` (intercept only).
 ##' @param seed An \code{integer} specifying the random number seed.
 ##' @param init A scalar specifying the initialization method. The default
-##'   (NULL) represents the \code{cmdstan} default, a scalar greater than zero,
-##'   say \code{x}, initialized all parameters from a uniform between \code{-x}
-##'   and \code{x}, a \code{0} initialize all parameters at \code{0}, or "prior"
-##'   (to initialize the model parameters using samples from their prior)
+##'   ("cmdstan_default") lets \code{cmdstan} initialize parameters.
+##'   Other options include: a scalar greater than zero, say \code{x}, which
+##'   initializes all parameters uniformly between \code{-x} and \code{x};
+##'   \code{0}, which initializes all parameters at \code{0}; or "prior",
+##'   which initializes parameters by sampling from their priors.
 ##' @param algorithm a \code{character} specifying the algorithm used for
 ##'   inference. Default is \code{nuts} (the default MCMC in Stan). The
 ##'   remaining options are different flavors of variational bayes algorithms:
 ##'   "vb" (for ADVI), "pathfinder" (for Pathfinder), "laplace" (normal
 ##'   approximation centered at the mode of the posterior) or "optimize" for
 ##'   (penalized) MLEs.
 ##' @param algo_args a \code{list} with arguments for the sampling
-##'   algorithms. For instance, \code{tol_rel_obj} for variational .
+##'   algorithms. For instance, \code{tol_rel_obj} for variational inference.
 ##' @param ... Passed on to the [make_data()] function used to build the input
 ##'   \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.
+##' @return An object of class \code{sdm} which is a \code{list} containing the
+##'   MCMC draws, the model data, the linear 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 formulas used to create design matrices.
 ##'     \item \code{cols}: Important column names.
 ##'   }
-##' @seealso [make_data()]
+##' @seealso [make_data_sdm()]
 ##' @examples
 ##' if (instantiate::stan_cmdstan_exists()) {
 ##'   data(sum_fl)

R/predict.R

@@ -69,22 +69,22 @@ get_fitted_pars <- function(data_list, model = "drm") {
 ##' @description Considering a new dataset (across the same patches), computes
 ##'   predictions based on the DRM passed as \code{drm}.
 ##'
-##' @param object A \code{adrm} (or \code{sdm}) object containing the output from the
-##'   [fit_drm()] (or [fit_sdm()]) function.
+##' @param object An \code{adrm} object containing the output from the
+##'   [fit_drm()] function.
 ##' @param new_data a \code{data.frame} with the dataset at which we wish to
 ##'   obtain predictions.
-##' @param past_data a \code{data.frame} with the dataset last year used in
-##'   model fitting. Only needed when \code{f_test} is not missing or when
-##'   estimating survival.
+##' @param past_data a \code{data.frame} with the dataset from the last year
+##'   used in model fitting. Only needed when \code{f_test} is not missing or
+##'   when estimating survival.
 ##' @param f_test a \code{matrix} informing the instantaneous fishing mortality
 ##'   rates at each age (columns) and timepoint (rows).
 ##' @param type type of predictions to be computed. Admitted values are
 ##' \itemize{
 ##' \item `"predictive"` (default): posterior predictive distribution;
 ##' \item `"expected"`: theoretical mean of the posterior predictive distribution;
-##' \item `"latent"`: latent density (i.e., disconsidering the observation error);
+##' \item `"latent"`: latent density (i.e., disregarding the observation error);
 ##' }
-##' @param seed a seed used for the predictions. predictiosn are obtained
+##' @param seed a seed used for the predictions. predictions are obtained
 ##'   through Monte Carlo samples from the posterior predictive
 ##'   distribution. Therefore, a \code{seed} is needed to ensure the results'
 ##'   reproducibility.
@@ -103,6 +103,7 @@ get_fitted_pars <- function(data_list, model = "drm") {
 ##' @author lcgodoy
 ##'
 ##' @name preddrm
+##' @seealso [fit_drm()]
 ##' 
 ##' @return an object of class \code{"CmdStanGQ"} containing samples for the
 ##'   posterior predictive distribution for predictions.
@@ -203,7 +204,7 @@ predict.adrm <- function(object,
 ##' @description Considering a new dataset (across the same patches), computes
 ##'   predictions based on the SDM passed as \code{sdm}.
 ##'
-##' @param object A \code{list} object containing the output of a [fit_sdm] call.
+##' @param object An \code{sdm} object containing the output of a [fit_sdm] call.
 ##'
 ##' @param new_data a \code{data.frame} with the dataset at which we wish to
 ##'   obtain predictions.
@@ -215,10 +216,10 @@ predict.adrm <- function(object,
 ##' \itemize{
 ##' \item `"predictive"` (default): posterior predictive distribution;
 ##' \item `"expected"`: theoretical mean of the posterior predictive distribution;
-##' \item `"latent"`: latent density (i.e., disconsidering the observation error);
+##' \item `"latent"`: latent density (i.e., disregarding the observation error);
 ##' }
 ##' @param cores number of threads used to compute the predictions. If four
-##'   chains were used in the \code{drm}, then four (or less) threads are
+##'   chains were used in the \code{sdm}, then four (or less) threads are
 ##'   recommended.
 ##' @param ... additional parameters to be passed to
 ##'   \code{$generated_quantities}
@@ -235,6 +236,7 @@ predict.adrm <- function(object,
 ##'   predictions.
 ##'
 ##' @rdname predsdm
+##' @seealso [fit_sdm()]
 predict.sdm <- function(object,
                         new_data,
                         type = "predictive",