From d2f1de207dc4ba178aa883cc440cf0d1512289b9 Mon Sep 17 00:00:00 2001 From: Paul Regular Date: Mon, 18 Sep 2023 17:23:36 -0230 Subject: [PATCH] Ensure that all functions include a description of the values returned --- CRAN-SUBMISSION | 4 ++-- R/helper.R | 4 ++++ R/icc.R | 2 ++ R/plot_sim.R | 2 ++ R/run_strat.R | 5 +++++ R/sim_dist.R | 6 ++++++ R/sim_dist_spde.R | 2 ++ R/sim_pop.R | 8 +++++++- R/sim_survey.R | 8 ++++++++ R/test_surveys.R | 2 ++ R/vis_sim.R | 2 ++ man/convert_N.Rd | 2 +- man/expand_surveys.Rd | 3 +++ man/fibonacci.Rd | 3 +++ man/group_lengths.Rd | 3 +++ man/icc.Rd | 3 +++ man/make_mesh.Rd | 3 +++ man/object_size.Rd | 3 +++ man/plot_trend.Rd | 3 +++ man/round_sim.Rd | 3 +++ man/sim_R.Rd | 3 +++ man/sim_ays_covar.Rd | 3 +++ man/sim_logistic.Rd | 3 +++ man/sim_nlf.Rd | 3 +++ man/sim_parabola.Rd | 3 +++ man/sim_sets.Rd | 3 +++ man/sim_survey_parallel.Rd | 3 +++ man/sim_vonB.Rd | 3 +++ man/strat_data.Rd | 4 ++++ man/strat_means.Rd | 3 +++ man/vis_sim.Rd | 3 +++ 31 files changed, 101 insertions(+), 4 deletions(-) diff --git a/CRAN-SUBMISSION b/CRAN-SUBMISSION index 1aa32a0..0e8b391 100644 --- a/CRAN-SUBMISSION +++ b/CRAN-SUBMISSION @@ -1,3 +1,3 @@ Version: 0.1.6 -Date: 2023-09-15 18:15:02 UTC -SHA: 03782485a4ec155145da49da0476c498a1b019e2 +Date: 2023-09-18 14:42:04 UTC +SHA: 28daf1f7c21db3a333d9752661e1771ca4d259bb diff --git a/R/helper.R b/R/helper.R index 59b8e79..85763c8 100644 --- a/R/helper.R +++ b/R/helper.R @@ -6,6 +6,8 @@ #' #' @export #' +#' @return Returns a Fibonacci sequence as a vector. +#' #' @examples #' #' fibonacci(2, 200) @@ -44,6 +46,8 @@ fibonacci <- function(from, to) { #' @param x an \code{R} object #' @param units the units to be used in printing the size #' +#' @return Returns a character with the object size followed by the unit. +#' #' @export #' diff --git a/R/icc.R b/R/icc.R index 4e150df..4e1961d 100644 --- a/R/icc.R +++ b/R/icc.R @@ -9,6 +9,8 @@ #' @param x Response variable #' @param group Group #' +#' @return Returns estimate of intraclass correlation. +#' #' @export #' diff --git a/R/plot_sim.R b/R/plot_sim.R index faf2111..1f65bdb 100644 --- a/R/plot_sim.R +++ b/R/plot_sim.R @@ -29,6 +29,8 @@ #' @import plotly #' @importFrom rlang .data #' +#' @return Returns a plot of class \code{plotly}. +#' #' @export #' @rdname plot_trend plot_trend <- function(sim, sum_ages = sim$ages, col = viridis::viridis(1), ...) { diff --git a/R/run_strat.R b/R/run_strat.R index b4ea94d..3001831 100644 --- a/R/run_strat.R +++ b/R/run_strat.R @@ -30,6 +30,9 @@ error_stats <- function(error) { #' @param alk_scale Spatial scale at which to construct and apply age-length-keys: #' "division", "strat" or "set". #' +#' @return Returns a list including set details (\code{setdet}), length-frequencies (\code{lf}), +#' and age-frequencies (\code{af}). +#' #' @export #' @@ -124,6 +127,8 @@ strat_data <- function(sim, length_group = 3, alk_scale = "division") { #' @param survey_groups Grouping variables for large-scale summary calculations. e.g. ("year","species") #' @param confidence Percent for confidence limits #' +#' @return Returns a data.table including stratified estimates of abundance. +#' #' @export #' diff --git a/R/sim_dist.R b/R/sim_dist.R index f6723c0..80bd264 100644 --- a/R/sim_dist.R +++ b/R/sim_dist.R @@ -41,6 +41,8 @@ #' @param group_years Make space-age-year noise equal across these years #' @param model String indicating either "exponential" or "matern" as the correlation function #' +#' @return Returns a function for use inside \code{\link{sim_distribution}}. +#' #' @export sim_ays_covar <- function(sd = 2.8, range = 300, lambda = 1, model = "matern", @@ -169,6 +171,8 @@ sim_ays_covar <- function(sd = 2.8, range = 300, lambda = 1, model = "matern", #' forces very low values near zero. #' @param plot Produce a simple plot of the simulated values? #' +#' @return Returns a function for use inside \code{\link{sim_distribution}}. +#' #' @examples #' #' parabola_fun <- sim_parabola(mu = 50, sigma = 5, plot = TRUE) @@ -242,6 +246,8 @@ sim_parabola <- function(alpha = 0, mu = 200, sigma = 70, sigma_right = NULL, #' included in argument \code{coeff} as a named list. #' @param coeff Named list of coefficient values used in \code{formula}. #' +#' @return Returns a function for use inside \code{\link{sim_distribution}}. +#' #' @export #' #' @examples diff --git a/R/sim_dist_spde.R b/R/sim_dist_spde.R index 5efdae8..1fcfe98 100644 --- a/R/sim_dist_spde.R +++ b/R/sim_dist_spde.R @@ -227,6 +227,8 @@ sim_ays_covar_spde <- function(sd = 2.8, #' @param cutoff Minimum distance allowed between points #' @param ... Other options to pass to inla.mesh.2d #' +#' @return Returns an object of class \code{inla.mesh}. +#' #' @examples #' #' \donttest{ diff --git a/R/sim_pop.R b/R/sim_pop.R index 33dea2a..c20ee3a 100644 --- a/R/sim_pop.R +++ b/R/sim_pop.R @@ -19,6 +19,8 @@ #' sim_Z does the same as sim_R when phi_age and phi_year are both 0, otherwise values are correlated #' in the age and/or year dimension. The covariance structure follows that described in Cadigan (2015). #' +#' @return Returns a function for use inside \code{\link{sim_abundance}}. +#' #' @references Cadigan, Noel G. 2015. A State-Space Stock Assessment Model for Northern Cod, #' Including Under-Reported Catches and Variable Natural Mortality Rates. Canadian Journal of #' Fisheries and Aquatic Sciences 73 (2): 296-308. @@ -138,6 +140,8 @@ sim_N0 <- function(N0 = "exp", plot = FALSE) { #' @param length Interval from \code{\link[base]{findInterval}} #' @param group Length group used to cut the length data #' +#' @return Returns a vector indicating the mid-point of the length group. +#' #' @export #' @@ -168,6 +172,8 @@ group_lengths <- function(length, group) { #' @param digits Integer indicating the number of decimal places to round the values to #' @param plot Produce a simple plot of the simulated values? #' +#' @return Returns a function for use inside \code{\link{sim_abundance}}. +#' #' @examples #' growth_fun <- sim_vonB(Linf = 100, L0 = 5, K = 0.2, log_sd = 0.05, length_group = 1, plot = TRUE) #' growth_fun(age = rep(1:15, each = 100)) @@ -223,7 +229,7 @@ sim_vonB <- function(Linf = 120, L0 = 5, K = 0.1, log_sd = 0.1, #' @param N_at_age Abundance-at-age matrix #' @param lak Length-age-key (i.e. probability of being in a specific length group given age) #' -#' @return Returns abundance-at-length matrix +#' @return Returns abundance-at-length matrix. #' #' @export #' diff --git a/R/sim_survey.R b/R/sim_survey.R index 8ccb025..9200134 100644 --- a/R/sim_survey.R +++ b/R/sim_survey.R @@ -8,6 +8,8 @@ #' @param x0 The x-value of the sigmoid's midpoint #' @param plot Plot relationship #' +#' @return Returns a function for use in \code{\link{sim_survey}}. +#' #' @examples #' logistic_fun <- sim_logistic(k = 2, x0 = 3, plot = TRUE) #' logistic_fun(x = 1:10) @@ -28,6 +30,8 @@ sim_logistic <- function(k = 2, x0 = 3, plot = FALSE) { #' #' @param sim Simulation from \code{\link{sim_distribution}} #' +#' @return Returns a rounded simulation object. Largely used as a helper in \code{\link{sim_survey}}. +#' #' @export #' @@ -60,6 +64,8 @@ round_sim <- function(sim) { #' (Note: allowing resampling may create bias because #' depletion is imposed at the cell level) #' +#' @return Returns a data.table including details of each set location. +#' #' @export #' #' @examples @@ -317,6 +323,8 @@ sim_survey <- function(sim, n_sims = 1, q = sim_logistic(), trawl_dim = c(1.5, 0 #' #' @details \code{\link{sim_survey}} is hard-wired here to be "light" to minimize object size. #' +#' @return Returns an object of the same structure as \code{\link{sim_survey}}. +#' #' @examples #' #' \donttest{ diff --git a/R/test_surveys.R b/R/test_surveys.R index 6bb5ca4..d27920e 100644 --- a/R/test_surveys.R +++ b/R/test_surveys.R @@ -10,6 +10,8 @@ #' @param ages_cap Vector of maximum number of otoliths to collect per length group #' per division per year #' +#' @return Returns a data.frame including all combinations of the supplied vectors. +#' #' @export #' diff --git a/R/vis_sim.R b/R/vis_sim.R index 5683dee..c41aabe 100644 --- a/R/vis_sim.R +++ b/R/vis_sim.R @@ -6,6 +6,8 @@ #' \code{\link{sim_survey}} or \code{\link{test_surveys}}. #' @param ... Additional arguments to send to \link[rmarkdown]{run} #' +#' @return No value returned; function produces an interactive dashboard. +#' #' @examples #' #' \donttest{ diff --git a/man/convert_N.Rd b/man/convert_N.Rd index 42e1a6d..1f18aca 100644 --- a/man/convert_N.Rd +++ b/man/convert_N.Rd @@ -12,7 +12,7 @@ convert_N(N_at_age = NULL, lak = NULL) \item{lak}{Length-age-key (i.e. probability of being in a specific length group given age)} } \value{ -Returns abundance-at-length matrix +Returns abundance-at-length matrix. } \description{ Function for converting abundance-at-age matrix to abundance-at-length given diff --git a/man/expand_surveys.Rd b/man/expand_surveys.Rd index 83eba5e..d7dbe8c 100644 --- a/man/expand_surveys.Rd +++ b/man/expand_surveys.Rd @@ -18,6 +18,9 @@ expand_surveys( \item{ages_cap}{Vector of maximum number of otoliths to collect per length group per division per year} } +\value{ +Returns a data.frame including all combinations of the supplied vectors. +} \description{ Function is simply a wrapper for \code{\link[base]{expand.grid}} that adds a survey number to the returned object diff --git a/man/fibonacci.Rd b/man/fibonacci.Rd index 68b75b9..924a370 100644 --- a/man/fibonacci.Rd +++ b/man/fibonacci.Rd @@ -9,6 +9,9 @@ fibonacci(from, to) \arguments{ \item{from, to}{Approximate start and end values of the sequence} } +\value{ +Returns a Fibonacci sequence as a vector. +} \description{ Generate Fibonacci sequence } diff --git a/man/group_lengths.Rd b/man/group_lengths.Rd index 715470a..11c5efc 100644 --- a/man/group_lengths.Rd +++ b/man/group_lengths.Rd @@ -11,6 +11,9 @@ group_lengths(length, group) \item{group}{Length group used to cut the length data} } +\value{ +Returns a vector indicating the mid-point of the length group. +} \description{ Helper function for converting lengths to length groups (Note: this isn't a general function; the output midpoints defining the diff --git a/man/icc.Rd b/man/icc.Rd index f4a31f3..85483e1 100644 --- a/man/icc.Rd +++ b/man/icc.Rd @@ -11,6 +11,9 @@ icc(x, group) \item{group}{Group} } +\value{ +Returns estimate of intraclass correlation. +} \description{ This is a simple function for calculating intraclass correlation. It uses \code{\link[lme4]{lmer}} to run the formula described here: diff --git a/man/make_mesh.Rd b/man/make_mesh.Rd index 2c3bc6a..bc8702c 100644 --- a/man/make_mesh.Rd +++ b/man/make_mesh.Rd @@ -26,6 +26,9 @@ make_mesh( \item{...}{Other options to pass to inla.mesh.2d} } +\value{ +Returns an object of class \code{inla.mesh}. +} \description{ This will make a mesh based off a given grid. Ideally the mesh construction and validation should be done by hand, but this exists diff --git a/man/object_size.Rd b/man/object_size.Rd index 992064e..901d1f6 100644 --- a/man/object_size.Rd +++ b/man/object_size.Rd @@ -11,6 +11,9 @@ object_size(x, units = "Mb") \item{units}{the units to be used in printing the size} } +\value{ +Returns a character with the object size followed by the unit. +} \description{ A wrapper for \code{\link[utils]{object.size}} that prints in Mb by default diff --git a/man/plot_trend.Rd b/man/plot_trend.Rd index 58beca4..2da68d7 100644 --- a/man/plot_trend.Rd +++ b/man/plot_trend.Rd @@ -96,6 +96,9 @@ plot_survey_rank(sim, which_strat = "age") \item{which_strat}{Which strat values to focus on? (total, length, or age)} } +\value{ +Returns a plot of class \code{plotly}. +} \description{ These functions are simple plotting helpers to get some quick visuals of values produced by \code{\link{sim_abundance}}, diff --git a/man/round_sim.Rd b/man/round_sim.Rd index 6d396af..9464798 100644 --- a/man/round_sim.Rd +++ b/man/round_sim.Rd @@ -9,6 +9,9 @@ round_sim(sim) \arguments{ \item{sim}{Simulation from \code{\link{sim_distribution}}} } +\value{ +Returns a rounded simulation object. Largely used as a helper in \code{\link{sim_survey}}. +} \description{ Round simulated population } diff --git a/man/sim_R.Rd b/man/sim_R.Rd index 4845f48..e8b4d8f 100644 --- a/man/sim_R.Rd +++ b/man/sim_R.Rd @@ -35,6 +35,9 @@ rows equaling the number of ages and columns equaling the number of years for \c \item{N0}{Either specify "exp" or numeric vector of starting abundance excluding the first age. If "exp" is specified using sim_N0, then abundance at age are calculated using exponential decay.} } +\value{ +Returns a function for use inside \code{\link{sim_abundance}}. +} \description{ These functions return a function to use inside \code{\link{sim_abundance}}. Given parameters, it generates N0, R and Z values. diff --git a/man/sim_ays_covar.Rd b/man/sim_ays_covar.Rd index a84bf89..9c69bf7 100644 --- a/man/sim_ays_covar.Rd +++ b/man/sim_ays_covar.Rd @@ -34,6 +34,9 @@ length as years} \item{group_years}{Make space-age-year noise equal across these years} } +\value{ +Returns a function for use inside \code{\link{sim_distribution}}. +} \description{ These functions return a function to use inside \code{\link{sim_distribution}}. } diff --git a/man/sim_logistic.Rd b/man/sim_logistic.Rd index a115b65..a6e5e51 100644 --- a/man/sim_logistic.Rd +++ b/man/sim_logistic.Rd @@ -13,6 +13,9 @@ sim_logistic(k = 2, x0 = 3, plot = FALSE) \item{plot}{Plot relationship} } +\value{ +Returns a function for use in \code{\link{sim_survey}}. +} \description{ This closure is useful for simulating q inside the \code{\link{sim_survey}} function diff --git a/man/sim_nlf.Rd b/man/sim_nlf.Rd index 5266115..3b04e4d 100644 --- a/man/sim_nlf.Rd +++ b/man/sim_nlf.Rd @@ -18,6 +18,9 @@ included in argument \code{coeff} as a named list.} \item{coeff}{Named list of coefficient values used in \code{formula}.} } +\value{ +Returns a function for use inside \code{\link{sim_distribution}}. +} \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} diff --git a/man/sim_parabola.Rd b/man/sim_parabola.Rd index 9917b5d..2ed09f4 100644 --- a/man/sim_parabola.Rd +++ b/man/sim_parabola.Rd @@ -28,6 +28,9 @@ forces very low values near zero.} \item{plot}{Produce a simple plot of the simulated values?} } +\value{ +Returns a function for use inside \code{\link{sim_distribution}}. +} \description{ Closure to be used in \code{\link{sim_distribution}}. Form is based on the bi-gaussian function described here: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2993707/. } diff --git a/man/sim_sets.Rd b/man/sim_sets.Rd index 0d7b3f1..104b2a0 100644 --- a/man/sim_sets.Rd +++ b/man/sim_sets.Rd @@ -33,6 +33,9 @@ division, strat, year}) of the survey grid to keep (e.g., \code{cell (Note: allowing resampling may create bias because depletion is imposed at the cell level)} } +\value{ +Returns a data.table including details of each set location. +} \description{ Simulate survey sets } diff --git a/man/sim_survey_parallel.Rd b/man/sim_survey_parallel.Rd index 2740967..f8862ba 100644 --- a/man/sim_survey_parallel.Rd +++ b/man/sim_survey_parallel.Rd @@ -62,6 +62,9 @@ automated if \code{custom_sets = NULL}.} \item{\code{light}}{Drop some objects from the output to keep object size low?} }} } +\value{ +Returns an object of the same structure as \code{\link{sim_survey}}. +} \description{ This function is a wrapper for \code{\link{sim_survey}} except it allows for many more total iterations to be run than \code{\link{sim_survey}} before running diff --git a/man/sim_vonB.Rd b/man/sim_vonB.Rd index 3aa8a31..aaf65ba 100644 --- a/man/sim_vonB.Rd +++ b/man/sim_vonB.Rd @@ -32,6 +32,9 @@ stratified analysis run by \code{\link{run_strat}}.} \item{plot}{Produce a simple plot of the simulated values?} } +\value{ +Returns a function for use inside \code{\link{sim_abundance}}. +} \description{ This function outputs a function which holds the parameter values supplied and the function either simulates lengths given ages or generates a length age key diff --git a/man/strat_data.Rd b/man/strat_data.Rd index 3ae4383..bea6bab 100644 --- a/man/strat_data.Rd +++ b/man/strat_data.Rd @@ -14,6 +14,10 @@ strat_data(sim, length_group = 3, alk_scale = "division") \item{alk_scale}{Spatial scale at which to construct and apply age-length-keys: "division", "strat" or "set".} } +\value{ +Returns a list including set details (\code{setdet}), length-frequencies (\code{lf}), +and age-frequencies (\code{af}). +} \description{ Generate set details (setdet), length-frequency (lf) and age-frequency (af) data for stratified analysis diff --git a/man/strat_means.Rd b/man/strat_means.Rd index 9f33c68..bce494c 100644 --- a/man/strat_means.Rd +++ b/man/strat_means.Rd @@ -26,6 +26,9 @@ means (strat and strat_area are required). e.g. c("year", "species", \item{confidence}{Percent for confidence limits} } +\value{ +Returns a data.table including stratified estimates of abundance. +} \description{ Calculate stratified means, variances and confidence intervals across groups } diff --git a/man/vis_sim.Rd b/man/vis_sim.Rd index a8c594d..13235c5 100644 --- a/man/vis_sim.Rd +++ b/man/vis_sim.Rd @@ -12,6 +12,9 @@ vis_sim(sim, ...) \item{...}{Additional arguments to send to \link[rmarkdown]{run}} } +\value{ +No value returned; function produces an interactive dashboard. +} \description{ Assumes the working directory is the project directory }