diff --git a/R/make-data.R b/R/make-data.R index afeb73b..4688dd4 100644 --- a/R/make-data.R +++ b/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 diff --git a/R/model-run.R b/R/model-run.R index ee157a9..23b6ef6 100644 --- a/R/model-run.R +++ b/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 diff --git a/R/predict.R b/R/predict.R index 2685eea..852d39c 100644 --- a/R/predict.R +++ b/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, diff --git a/R/utils.R b/R/utils.R index 396e835..96c8af5 100644 --- a/R/utils.R +++ b/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,