From 1efe27c19aeb39cc41ee96603b4a22024e6c2f03 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 24 Feb 2026 23:51:55 +0000 Subject: [PATCH] Improve roxygen2 documentation in R files - Corrected typos and grammar in `R/model-run.R`, `R/make-data.R`, `R/predict.R`, `R/methods.R`, `R/generics.R`, `R/defaults.R`, and `R/utils.R`. - Clarified parameter descriptions, particularly for `init`, `.toggles`, `new_data`, and `past_data`. - Updated return value descriptions to be more specific, including class names where appropriate (`adrm`, `sdm`, `CmdStanGQ`). - Fixed incorrect documentation for `fit_sdm` toggles and `@seealso` links. - Standardized documentation for S3 methods and internal helper functions. - Addressed placeholder documentation in `R/defaults.R`. - Clarified `int_score` documentation regarding the `alpha` parameter. Co-authored-by: lcgodoy <24809942+lcgodoy@users.noreply.github.com> --- R/defaults.R | 22 +++++++++++----------- R/generics.R | 2 +- R/make-data.R | 26 +++++++++++++------------- R/methods.R | 8 +++----- R/model-run.R | 38 +++++++++++++++++++++----------------- R/predict.R | 22 ++++++++++++---------- R/utils.R | 26 +++++++++++++------------- 7 files changed, 74 insertions(+), 70 deletions(-) diff --git a/R/defaults.R b/R/defaults.R index cbb3919..9b3d014 100644 --- a/R/defaults.R +++ b/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", diff --git a/R/generics.R b/R/generics.R index 3056f75..3a92ae2 100644 --- a/R/generics.R +++ b/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`. diff --git a/R/make-data.R b/R/make-data.R index 7337c9c..882b1a7 100644 --- a/R/make-data.R +++ b/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, diff --git a/R/methods.R b/R/methods.R index 0e32ea2..ee20d69 100644 --- a/R/methods.R +++ b/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) diff --git a/R/model-run.R b/R/model-run.R index 1f44790..69cc0e9 100644 --- a/R/model-run.R +++ b/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,10 +25,11 @@ ##' 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: @@ -36,11 +37,12 @@ ##' 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,10 +175,11 @@ 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: @@ -184,18 +187,19 @@ fit_drm <- function(.data, ##' 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) diff --git a/R/predict.R b/R/predict.R index 9cca066..9464a4a 100644 --- a/R/predict.R +++ b/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", diff --git a/R/utils.R b/R/utils.R index eed36ad..5d4a6f6 100644 --- a/R/utils.R +++ b/R/utils.R @@ -9,7 +9,7 @@ ##' @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 +##' @return A \code{numeric} value representing the regression coefficient of the ##' linear term for the model where \eqn{x} is not centered. ##' @author Lucas Godoy ##' @export @@ -29,7 +29,7 @@ fix_linbeta <- function(beta1, beta2, offset) { ##' @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 +##' @return A \code{numeric} value representing the uncentered \eqn{x} that maximizes ##' (or minimizes) the linear predictor. ##' @author Lucas Godoy ##' @export @@ -43,7 +43,7 @@ max_quad_x <- function(beta1, beta2, offset = 0) { ##' Generates an adjacency matrix for "movement" ##' @title Generates an adjacency matrix ##' @param x an \code{sf} object representing the patches. -##' @return an adjacency \code{matrix} +##' @return An adjacency \code{matrix}. ##' @author lcgodoy ##' @export gen_adj <- function(x) { @@ -73,7 +73,7 @@ gen_adj <- function(x) { ##' @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}. -##' @return an updated \code{original list}. +##' @return The updated \code{original} list. ##' @author lcgodoy safe_modify <- function(original, replacements) { if (!missing(replacements)) { @@ -103,7 +103,7 @@ safe_modify <- function(original, replacements) { ##' @param lb A numeric vector of lower bounds. ##' @param ub A numeric vector of upper bounds. ##' -##' @return No return value. This function stops execution if any of the +##' @return Returns \code{NULL} invisibly. This function stops execution if any of the ##' following conditions are met: ##' * lb is greater than or equal to ub. ##' * The lengths of lb and ub are not equal. @@ -157,8 +157,8 @@ between <- function(x, lb, ub) { ##' @param y A numeric vector of observations. ##' @param l A numeric vector of lower bounds for the prediction intervals. ##' @param u A numeric vector of upper bounds for the prediction intervals. -##' @param alpha A numeric value specifying the penalty parameter for interval -##' width. +##' @param alpha A numeric value specifying the significance level (e.g., 0.05 +##' for a 95% interval). ##' ##' @return A numeric vector of interval scores. ##' @@ -174,7 +174,7 @@ int_score <- function(y, l, u, alpha) { ##' @title Random effects verbose to code ##' @param x a \code{character} -##' @return a \code{integer} +##' @return An \code{integer}. ##' @author lcgodoy fix_re <- function(x) { if (!x %in% c(0:3)) { @@ -188,7 +188,7 @@ fix_re <- function(x) { ##' @title Get nodes for ICAR spatial random effects ##' @param adj adjacency \code{matrix} -##' @return a \code{list}. +##' @return A \code{list} containing the number of edges and the neighbors. ##' @author lcgodoy get_nodes <- function(adj) { ladj <- apply(adj > 0, MARGIN = 1, @@ -210,7 +210,7 @@ get_nodes <- function(adj) { ##' ##' @param X A matrix we wish to invert. ##' @param tol A relative tolerance to detect zero singular values. -##' @return The generalized inverse of \code{X} +##' @return The generalized inverse of \code{X}. ginv <- function (X, tol = sqrt(.Machine$double.eps)) { if (length(dim(X)) > 2L || !(is.numeric(X) || is.complex(X))) stop("'X' must be a numeric or complex matrix") @@ -233,7 +233,7 @@ ginv <- function (X, tol = sqrt(.Machine$double.eps)) { ##' @description Using results from Rue and Held 2005 and Morris et al. 2019. ##' ##' @param adj adjacency \code{matrix} -##' @return a \code{scalar} +##' @return A \code{scalar} representing the scaling factor. ##' @author lcgodoy get_scaling <- function(adj) { Q <- matrix(0, nrow = nrow(adj), ncol = ncol(adj)) @@ -256,7 +256,7 @@ get_scaling <- function(adj) { ##' @title Estimate phi ##' @inheritParams make_data -##' @return a \code{numeric} scalar representing an estimate for phi +##' @return A \code{numeric} scalar representing an estimate for phi. ##' @author lcgodoy get_phi_hat <- function(y, family) { if (family == "gamma") { @@ -278,7 +278,7 @@ get_phi_hat <- function(y, family) { ##' @title Zeros and nonzeros ##' @inheritParams make_data -##' @return a \code{list} containing necessary input for stan to identify zeros +##' @return A \code{list} containing necessary input for stan to identify zeros ##' and nonzeros in the response variable. ##' @author lcgodoy get_zeros <- function(y) {