From d5f7ffe3a22e4175e9bfad98ec016bc8043282f8 Mon Sep 17 00:00:00 2001 From: Isaac Kinley Date: Tue, 19 Nov 2024 18:31:38 -0500 Subject: [PATCH] Consistent use of periods in documentation --- R/data-docs.R | 4 +- R/generics.R | 105 +++++++++++++++++++-------------------- R/methods.R | 28 +++++------ R/td_bclm.R | 4 +- R/td_bcnm.R | 2 +- R/td_fn.R | 14 +++--- R/td_ipm.R | 12 ++--- R/utils.R | 9 ++-- R/validation-functions.R | 2 +- 9 files changed, 90 insertions(+), 90 deletions(-) diff --git a/R/data-docs.R b/R/data-docs.R index 41afef1..646177c 100644 --- a/R/data-docs.R +++ b/R/data-docs.R @@ -20,7 +20,7 @@ NULL #' Simulated indifference point data for a single participant #' -#' A dataframe containing simulated indifference points from a single participant exhibiting approximately hyperbolic discounting +#' A dataframe containing simulated indifference points from a single participant exhibiting approximately hyperbolic discounting. #' @name td_ip_simulated_ptpt #' @docType data #' @author Isaac Kinley \email{isaac.kinley@gmail.com} @@ -29,7 +29,7 @@ NULL #' Simulated adjusting amount procedure #' -#' A minimal example of data from a single participant for an adjusting amount procedure +#' A minimal example of data from a single participant for an adjusting amount procedure. #' @name adj_amt_sim #' @docType data #' @author Isaac Kinley \email{isaac.kinley@gmail.com} diff --git a/R/generics.R b/R/generics.R index 6f51a10..5408de1 100644 --- a/R/generics.R +++ b/R/generics.R @@ -76,13 +76,13 @@ predict_indiffs <- function(object, newdata) { #' Model Predictions #' -#' Generate predictions from a temporal discounting binary choice model +#' Generate predictions from a temporal discounting binary choice model. #' @param object A temporal discounting binary choice model. See \code{\link{td_bcnm}}. #' @param newdata Optionally, a data frame to use for prediction. If omitted, the data used to fit the model will be used for prediction. #' @param type The type of prediction required. As in predict.glm, \code{"link"} (default) and \code{"response"} give predictions on the scales of the linear predictors and response variable, respectively. \code{"indiff"} gives predicted indifference points. For predicting indifference points, \code{newdata} needs only a \code{del} column. #' @param ... Additional arguments currently not used. #' @family nonlinear binary choice model functions -#' @return A vector of predictions +#' @return A vector of predictions. #' @examples #' \dontrun{ #' data("td_bc_single_ptpt") @@ -124,13 +124,13 @@ predict.td_bcnm <- function(object, newdata = NULL, type = c('link', 'response', #' Model Predictions #' -#' Generate predictions from a temporal discounting binary choice linear model +#' Generate predictions from a temporal discounting binary choice linear model. #' @param object A temporal discounting binary choice linear model. See \code{td_bclm}. #' @param newdata Optionally, a data frame to use for prediction. If omitted, the data used to fit the model will be used for prediction. #' @param type The type of prediction required. For \code{'indiff'} (default) gives predicted indifference points. In this case, \code{newdata} needs only a \code{del} column. For all other values (e.g. \code{"link"}, \code{"response"}), this function is just a wrapper to \code{predict.glm()}. -#' @param ... Additional arguments passed to predict.glm if type != \code{'indiff'} +#' @param ... Additional arguments passed to predict.glm if type != \code{'indiff'}. #' @family linear binary choice model functions -#' @return A vector of predictions +#' @return A vector of predictions. #' @examples #' \dontrun{ #' data("td_bc_single_ptpt") @@ -163,10 +163,10 @@ predict.td_bclm <- function(object, newdata = NULL, type = c('indiff', 'link', ' #' Generate predictions from a temporal discounting indifference point model #' @param object A temporal discounting indifference point model. See \code{td_ipm}. #' @param newdata A data frame to use for prediction. If omitted, the data used to fit the model will be used for prediction. -#' @param type Type of prediction, either \code{'indiff'} (indifference points) or \code{'response'} (whether the participants would is predicted to choose the immediate (1) or delayed reward (0)) +#' @param type Type of prediction, either \code{'indiff'} (indifference points) or \code{'response'} (whether the participants would is predicted to choose the immediate (1) or delayed reward (0)). #' @param ... Additional arguments currently not used. #' @family indifference point model functions -#' @return A vector of predictions +#' @return A vector of predictions. #' @examples #' \dontrun{ #' data("td_ip_simulated_ptpt") @@ -204,13 +204,13 @@ predict.td_ipm <- function(object, newdata = NULL, type = c('indiff', 'response' #' Model Predictions #' -#' Generate predictions from a temporal discounting drift diffusion model +#' Generate predictions from a temporal discounting drift diffusion model. #' @param object A temporal discounting drift diffusion model. See \code{\link{td_ddm}}. #' @param newdata Optionally, a data frame to use for prediction. If omitted, the data used to fit the model will be used for prediction. #' @param type The type of prediction required. As in predict.glm, \code{"link"} (default) and \code{"response"} give predictions on the scales of the linear predictors and response variable, respectively. \code{"indiff"} gives predicted indifference points. For predicting indifference points, \code{newdata} needs only a \code{del} column. \code{"rt"} gives predicted reaction times. #' @param ... Additional arguments currently not used. #' @family drift diffusion model functions -#' @return A vector of predictions +#' @return A vector of predictions. #' @note #' When \code{type = 'rt'}, expected RTs are computed irrespective of which reward was selected, per equation 5 in \href{https://doi.org/10.1016/j.jmp.2009.01.006}{Grasman, Wagenmakers, & van der Maas (2009)}. #' @examples @@ -259,63 +259,63 @@ predict.td_ddm <- function(object, newdata = NULL, type = c('indiff', 'link', 'r #' Get fitted values #' -#' Get fitted values of a temporal discounting binary choice model +#' Get fitted values of a temporal discounting binary choice model. #' @param object An object of class \code{\link{td_bcnm}}. #' @param ... Additional arguments currently not used. #' @family nonlinear binary choice model functions -#' @return A named vector of fitted values +#' @return A named vector of fitted values. #' @export fitted.td_bcnm <- function(object, ...) {predict(object, type = 'response')} #' Get fitted values #' -#' Get fitted values of a temporal discounting indifference point model +#' Get fitted values of a temporal discounting indifference point model. #' @param object An object of class \code{\link{td_ipm}}. #' @param ... Additional arguments currently not used. #' @family indifference point model functions -#' @return A named vector of fitted values +#' @return A named vector of fitted values. #' @export fitted.td_ipm <- function(object, ...) {predict(object)} #' Get fitted values #' -#' Get fitted values of a temporal discounting drift diffusion model +#' Get fitted values of a temporal discounting drift diffusion model. #' @param object An object of class \code{\link{td_ddm}}. #' @param ... Additional arguments currently not used. #' @family drift diffusion model functions -#' @return A named vector of fitted values +#' @return A named vector of fitted values. #' @export fitted.td_ddm <- function(object, ...) {predict(object, type = 'response')} #' Extract model coefficients #' -#' Get coefficients of a temporal discounting drift diffusion model +#' Get coefficients of a temporal discounting drift diffusion model. #' @param object An object of class \code{\link{td_ddm}}. -#' @param type A string specifying which coefficients to extract. \code{'all'} extracts them all, \code{'ddm'} extracts only DDM-specific parameters, and \code{'df'} extracts only discount function parameters +#' @param type A string specifying which coefficients to extract. \code{'all'} extracts them all, \code{'ddm'} extracts only DDM-specific parameters, and \code{'df'} extracts only discount function parameters. #' @param ... Additional arguments currently not used. #' @family drift diffusion model functions -#' @return A named vector of coefficients +#' @return A named vector of coefficients. #' @export coef.td_ddm <- function(object, type = 'all', ...) {object$optim$par} #' Extract model coefficients #' -#' Get coefficients of a temporal discounting binary choice model -#' @param object An object of class \code{td_bcnm} +#' Get coefficients of a temporal discounting binary choice nonlinear model. +#' @param object An object of class \code{td_bcnm}. #' @param ... Additional arguments currently not used. #' @family nonlinear binary choice model functions -#' @return A named vector of coefficients +#' @return A named vector of coefficients. #' @export coef.td_bcnm <- function(object, ...) {object$optim$par} #' Extract model coefficients #' -#' Get coefficients of a temporal discounting binary choice model -#' @param object An object of class \code{td_bcnm} -#' @param df_par Boolean specifying whether the coefficients returned should be the parameters of a discount function (versus the beta parameters from the regression) +#' Get coefficients of a temporal discounting binary choice linear model. +#' @param object An object of class \code{td_bcnm}. +#' @param df_par Boolean specifying whether the coefficients returned should be the parameters of a discount function (versus the beta parameters from the regression). #' @param ... Additional arguments currently not used. -#' @family linear binary choice model functions -#' @return A named vector of coefficients +#' @family linear binary choice model functions. +#' @return A named vector of coefficients. #' @export coef.td_bclm <- function(object, df_par = TRUE, ...) { if (df_par) { @@ -352,22 +352,22 @@ coef.td_bclm <- function(object, df_par = TRUE, ...) { #' Extract model coefficients #' -#' Get coefficients of a temporal discounting indifference point model +#' Get coefficients of a temporal discounting indifference point model. #' @param object An object of class \code{td_ipm} #' @param ... Additional arguments currently not used. #' @family indifference point model functions -#' @return A named vector of coefficients +#' @return A named vector of coefficients. #' @export coef.td_ipm <- function(object, ...) {object$optim$par} #' Residuals from temporal discounting model #' -#' Get residuals from a temporal discounting binary choice model +#' Get residuals from a temporal discounting binary choice nonlinear model. #' @param object A temporal discounting binary choice model. See \code{td_bcnm}. #' @param type The type of residuals to be returned. See \code{residuals.glm}. #' @param ... Additional arguments currently not used. #' @family nonlinear binary choice model functions -#' @return A vector of residuals +#' @return A vector of residuals. #' @export residuals.td_bcnm <- function(object, type = c('deviance', 'pearson', 'response'), ...) { @@ -390,12 +390,12 @@ residuals.td_bcnm <- function(object, type = c('deviance', 'pearson', 'response' #' Residuals from temporal discounting model #' -#' Get residuals from a temporal discounting indifference point model +#' Get residuals from a temporal discounting indifference point model. #' @param object A temporal discounting model. See \code{td_bcnm}. #' @param type The type of residuals to be returned. See \code{residuals.nls}. #' @param ... Additional arguments currently not used. #' @family indifference point model functions -#' @return A vector of residuals +#' @return A vector of residuals. #' @export residuals.td_ipm <- function(object, type = c('response', 'pearson'), ...) { @@ -424,7 +424,7 @@ residuals.td_ipm <- function(object, type = c('response', 'pearson'), ...) { #' Extract log-likelihood #' -#' Compute log-likelihood for a temporal discounting binary choice model. +#' Compute log-likelihood for a temporal discounting binary choice nonlinear model. #' @param mod An object of class \code{td_bcnm} #' @param ... Additional arguments currently not used. #' @family nonlinear binary choice model functions @@ -465,8 +465,8 @@ logLik.td_ipm <- function(mod, ...) { #' Extract log-likelihood #' -#' Compute log-likelihood for a temporal discounting drift diffusion model -#' @param mod An object of class \code{td_bcnm} +#' Compute log-likelihood for a temporal discounting drift diffusion model. +#' @param mod An object of class \code{td_bcnm}. #' @param type Should probabilities /probability densities be computed for responses and RTs (\code{'resp_rt'}, default) or responses only (\code{'resp'})? #' @param ... Additional arguments currently not used. #' @family drift diffusion model functions @@ -491,7 +491,7 @@ logLik.td_ddm <- function(mod, type = c('resp_rt', 'resp', 'rt'), ...) { #' Model deviance #' #' Compute deviance for a temporal discounting binary choice model. -#' @param mod An object of class \code{td_bcnm} +#' @param mod An object of class \code{td_bcnm}. #' @param ... Additional arguments currently not used. #' @family nonlinear binary choice model functions #' @export @@ -499,8 +499,8 @@ deviance.td_bcnm <- function(mod, ...) return(-2*logLik.td_bcnm(mod)) #' Model deviance #' -#' Compute deviance for a temporal discounting drift diffusion model -#' @param mod An object of class \code{td_ddm} +#' Compute deviance for a temporal discounting drift diffusion model. +#' @param mod An object of class \code{td_ddm}. #' @param ... Additional arguments currently not used. #' @family drift diffusion model functions #' @export @@ -508,17 +508,17 @@ deviance.td_ddm <- function(mod, ...) return(-2*logLik.td_ddm(mod)) #' Plot models #' -#' Plot delay discounting models -#' @param x A delay discounting model. See \code{dd_prob_model} and \code{dd_det_model} -#' @param type Type of plot to generate -#' @param del Plots data for a particular delay -#' @param val_del Plots data for a particular delayed value -#' @param legend Logical: display a legend? Only relevant for \code{type = 'summary'} and \code{type = 'rt'} -#' @param p_lines Numerical vector. When \code{type = 'summary'} the discount curve, where the probability of selecting the immediate reward is 0.5, is plotted. \code{p_lines} allows you to specify other probabilities for which similar curves should be plotted (only applicable for probabilistic models, e.g. \code{td_bcnm}, \code{td_bclm} and \code{td_ddm}) -#' @param p_tol If \code{p_lines} is not \code{NULL}, what is the maximum distance that estimated probabilities can be from their true values? Smaller values results in slower plot generation -#' @param verbose Whether to print info about, e.g., setting del = ED50 when \code{type = 'endpoints'} -#' @param confint When \code{type = 'rt'}, what confidence interval should be plotted for RTs? Default is 0.95 (95\% confidence interval) -#' @param ... Additional arguments to \code{plot()} +#' Plot delay discounting models. +#' @param x A delay discounting model. See \code{dd_prob_model} and \code{dd_det_model}. +#' @param type Type of plot to generate. +#' @param del Plots data for a particular delay. +#' @param val_del Plots data for a particular delayed value. +#' @param legend Logical: display a legend? Only relevant for \code{type = 'summary'} and \code{type = 'rt'}. +#' @param p_lines Numerical vector. When \code{type = 'summary'} the discount curve, where the probability of selecting the immediate reward is 0.5, is plotted. \code{p_lines} allows you to specify other probabilities for which similar curves should be plotted (only applicable for probabilistic models, e.g. \code{td_bcnm}, \code{td_bclm} and \code{td_ddm}). +#' @param p_tol If \code{p_lines} is not \code{NULL}, what is the maximum distance that estimated probabilities can be from their true values? Smaller values results in slower plot generation. +#' @param verbose Whether to print info about, e.g., setting del = ED50 when \code{type = 'endpoints'}. +#' @param q_lines When \code{type = 'rt'}, plot dashed lines for which quantiles of the predicted RT distribution? Default is 0.025 and 0.975 (i.e., a quantile-based 95\% confidence interval). +#' @param ... Additional arguments to \code{plot()}. #' @examples #' \dontrun{ #' data("td_bc_single_ptpt") @@ -535,7 +535,7 @@ plot.td_um <- function(x, verbose = TRUE, del = NULL, val_del = NULL, - confint = 0.95, + q_lines = 0.95, ...) { type <- match.arg(type) @@ -760,9 +760,8 @@ plot.td_um <- function(x, pred_rts <- ddm_predicted_rts(plotting_linpreds, cf) lines(pred_rts ~ plotting_linpreds) - # Plot confidence interval - conf_extremum <- (1 - confint)/2 - for (p in c(conf_extremum, 1 - conf_extremum)) { + # Plot quantile lines + for (p in q_lines) { bounds <- vapply(plotting_linpreds, function(drift) { RWiener::qwiener(p = p, delta = drift, alpha = cf['alpha'], tau = cf['tau'], beta = cf['beta'], diff --git a/R/methods.R b/R/methods.R index 71e5b86..a59faee 100644 --- a/R/methods.R +++ b/R/methods.R @@ -1,10 +1,10 @@ #' Median effective delay #' -#' Compute the median effective delay +#' Compute the median effective delay. #' @param mod A temporal discounting model. -#' @param val_del Delayed value, if applicable (i.e., if magnitude effects are accounted for) -#' @return A vector of predictions +#' @param val_del Delayed value, if applicable (i.e., if magnitude effects are accounted for). +#' @return A vector of predictions. #' @examples #' \dontrun{ #' data("td_bc_single_ptpt") @@ -38,14 +38,14 @@ ED50 <- function(mod, val_del = NULL) { #' Area under the curve (AUC) #' -#' Compute the area under the curve using numerical integration -#' @param mod A temporal discounting model. See `td_gnlm` -#' @param min_del Lower limit to use for integration -#' @param max_del Upper limit to use for integration -#' @param val_del Delayed value to use for computing the indifference curve, if applicable -#' @param verbose Specifies whether to provide extra detail, if applicable -#' @param ... Further arguments passed to `integrate()` -#' @return AUC value +#' Compute the area under the curve using numerical integration. +#' @param mod A temporal discounting model. See \code{\link{td_bcnm}} and related functions. +#' @param min_del Lower limit to use for integration. +#' @param max_del Upper limit to use for integration. +#' @param val_del Delayed value to use for computing the indifference curve, if applicable. +#' @param verbose Specifies whether to provide extra detail, if applicable. +#' @param ... Further arguments passed to `integrate()`. +#' @return AUC value. #' @examples #' \dontrun{ #' data("td_bc_single_ptpt") @@ -159,9 +159,9 @@ nonsys <- function(obj) { #' Get discount function #' -#' Access the name of the discount function of a model -#' @param mod A temporal discounting model -#' @returns The name of the discount function +#' Access the name of the discount function of a model. +#' @param mod A temporal discounting model. +#' @returns The name of the discount function. #' @examples #' \dontrun{ #' data("td_bc_single_ptpt") diff --git a/R/td_bclm.R b/R/td_bclm.R index 42d637a..019436d 100644 --- a/R/td_bclm.R +++ b/R/td_bclm.R @@ -11,9 +11,9 @@ #' \code{'scaled-exponential'}: \eqn{\beta_1 \log (v_I/v_D) + \beta_2 t + \beta_3}; \eqn{k = \beta_2/\beta_1}, \eqn{w = \exp[-\beta_3/\beta_1]} #' \code{'nonlinear-time-hyperbolic'}: \eqn{\beta_1(\sigma^{-1}[v_I/v_D]) + \beta_2\log t + \beta_3}; \eqn{k = \exp[\beta_3/\beta_1]}, \eqn{s = \beta_2/\beta_1} \cr #' \code{'nonlinear-time-hyperbolic'}: \eqn{\beta_1(G^{-1}[v_I/v_D]) + \beta_2\log t + \beta_3}; \eqn{k = \exp[\beta_3/\beta_1]}, \eqn{s = \beta_2/\beta_1} \cr -#' where \eqn{\sigma^{-1}[\cdot]} is the quantile function of the standard logistic distribution \eqn{G^{-1}[\cdot]} is the quantile function of the standard Gumbel distribution +#' where \eqn{\sigma^{-1}[\cdot]} is the quantile function of the standard logistic distribution \eqn{G^{-1}[\cdot]} is the quantile function of the standard Gumbel distribution. #' @param data A data frame with columns \code{val_imm} and \code{val_del} for the values of the immediate and delayed rewards, \code{del} for the delay, and \code{imm_chosen} (Boolean) for whether the immediate reward was chosen. Other columns can also be present but will be ignored. -#' @param ... Additional arguments passed to \code{glm} +#' @param ... Additional arguments passed to \code{glm}. #' @family linear binary choice model functions #' @return An object of class \code{td_bclm}, nearly identical to a \code{glm} but with an additional \code{config} component. #' @examples diff --git a/R/td_bcnm.R b/R/td_bcnm.R index 55c998d..532c01e 100644 --- a/R/td_bcnm.R +++ b/R/td_bcnm.R @@ -6,7 +6,7 @@ #' @param discount_function A string specifying the name of the discount functions to use, or an object of class \code{td_fn} (used for creating custom discount functions), or a list of objects of class \code{td_fn}. #' @param choice_rule A string specifying whether the \code{'logistic'} (default), \code{'probit'}, or \code{'power'} choice rule should be used. #' @param fixed_ends A Boolean (false by default) specifying whether the model should satisfy the desiderata that subjects should always prefer something over nothing (i.e., nonzero delayed reward over nothing) and the same reward sooner rather than later. -#' @param fit_err_rate A Boolean (false by default) specifying whether the model should include an error rate (parameterized by "eps"). See Eq. 5 here: https://doi.org/10.3758/s13428-015-0672-2 +#' @param fit_err_rate A Boolean (false by default) specifying whether the model should include an error rate (parameterized by "eps"). See Eq. 5 here: https://doi.org/10.3758/s13428-015-0672-2. #' @param gamma_par_starts A vector of starting values to try for the "gamma" parameter (which controls the steepness of the choice rule) during optimization. #' @param eps_par_starts A vector of starting values to try for the "eps" parameter (which controls the error rate) during optimization. Ignored if `fit_err_rate = FALSE`. #' @param optim_args Additional arguments to pass to \code{optim()}. Default is \code{list(silent = T)}. diff --git a/R/td_fn.R b/R/td_fn.R index c75a7f4..e7de651 100644 --- a/R/td_fn.R +++ b/R/td_fn.R @@ -1,13 +1,13 @@ #' Temporal discount function #' -#' Get or create a discount function -#' @param predefined A string specifying one of the pre-defined discount functions -#' @param name Name of custom discount function -#' @param fn Function that takes a data.frame and a vector of named parameters and returns a vector of values between 0 and 1 -#' @param par_starts A named list of vectors, each specifying possible starting values for a parameter to try when running optimization -#' @param par_lims A named list of vectors, each specifying the bounds to impose of a parameter -#' @param ED50 A function which, given a named vector of parameters \code{p} and optionally a value of \code{del_val}, computes the ED50. If there is no closed-form solution, this should return the string "non-analytic". If the ED50 is not well-defined, this should return the string "none" +#' Get a predefined discount function or create a custom discount function. +#' @param predefined A string specifying one of the pre-defined discount functions. +#' @param name Name of custom discount function. +#' @param fn Function that takes a data.frame and a vector of named parameters and returns a vector of values between 0 and 1. +#' @param par_starts A named list of vectors, each specifying possible starting values for a parameter to try when running optimization. +#' @param par_lims A named list of vectors, each specifying the bounds to impose of a parameters. Any parameter for which bounds are unspecified are assumed to be unbounded. +#' @param ED50 A function which, given a named vector of parameters \code{p} and optionally a value of \code{del_val}, computes the ED50. If there is no closed-form solution, this should return the string "non-analytic". If the ED50 is not well-defined, this should return the string "none". #' @param par_chk Optionally, this is a function that checks the parameters to ensure they meet some criteria. E.g., for the dual-systems-exponential discount function, we require k1 < k2. #' @return An object of class `td_fn`. #' @examples diff --git a/R/td_ipm.R b/R/td_ipm.R index 7bceb2b..e448206 100644 --- a/R/td_ipm.R +++ b/R/td_ipm.R @@ -11,14 +11,14 @@ get_rss_fn <- function(data, discount_function) { #' Temporal discounting indifference point model #' -#' Compute a model of a single subject's indifference points -#' @param data A data frame with columns \code{indiff} for the pre-computed indifference points and \code{del} for the delay +#' Compute a model of a single subject's indifference points. +#' @param data A data frame with columns \code{indiff} for the pre-computed indifference points and \code{del} for the delay. #' @param discount_function A vector of strings specifying the name of the discount functions to use, or an object of class \code{td_fn} (used for creating custom discount functions), or a list of objects of class \code{td_fn}. #' @param na.action Action to take when data contains \code{NA} values. Default is \code{na.omit}. -#' @param optim_args A list of additional args to pass to \code{optim} -#' @param silent A Boolean specifying whether the call to \code{optim} (which occurs in a \code{try} block) should be silent on error -#' @family indifference point model functions -#' @return A list from \code{optim} with additional components specifying the AIC, the ED50, the discount function, and the probabilistic model +#' @param optim_args A list of additional args to pass to \code{optim}. +#' @param silent A Boolean specifying whether the call to \code{optim} (which occurs in a \code{try} block) should be silent on error. +#' @family indifference point model functions. +#' @return An object of class \code{td_ipm} with components \code{data} (containing the data used for fitting), \code{config} (containing the internal configuration of the model, including the \code{discount_function}), and \code{optim} (the output of \code{optim()}). #' @examples #' \dontrun{ #' # Basic usage diff --git a/R/utils.R b/R/utils.R index ec7506a..6bb40f2 100644 --- a/R/utils.R +++ b/R/utils.R @@ -133,11 +133,11 @@ run_optimization <- function(fn, par_starts, par_lims, optim_args, silent = F) { #' Indifference points from adjusting amount procedure #' -#' Compute indifference points for data from an adjusting amount procedure (also called a "titrating procedure"). +#' Compute indifference points for data from an adjusting amount procedure (also called a "titrating procedure"). #' @param data A dataframe where each row corresponds to a binary choice, with at least columns \code{val_imm}, \code{val_del}, and \code{imm_chosen}, along with a block indicator and (if applicable) an order indicator. #' @param block_indic Column name of the block indicator---i.e., the column that will identify a block of trials for which an indifference point should be computed. If unspecified, defaults to \code{'del'}, which assumes that each block corresponds to a different delay. #' @param order_indic Column name of the order indicator---i.e., the column that specifies the order in which trials were completed. Sorting by this column within a block should sort the rows in chronological order. If unspecified, the rows are assumed to already be in chronological order. -#' @returns A dataframe with two columns: one for the block indicator and another for the corresponding indifference point +#' @returns A dataframe with two columns: one for the block indicator and another for the corresponding indifference point. #' @examples #' \dontrun{ #' data("adj_amt_sim") @@ -233,7 +233,7 @@ kirby_score <- function(data, discount_function = c('hyperbolic', 'exponential') #' Compute the consistency score per the method of \href{10.1037//0096-3445.128.1.78}{Kirby et al. (1999)}. This is described in detail in \href{https://doi.org/10.1007/s40614-016-0070-9}{Kaplan et al. (2016)}, where it's suggested that a consistency score below 0.75 might be a sign of inattentive responding. #' @param data Responses to score. #' @param discount_function Should \eqn{k} values be computed according to the hyperbolic or exponential discount function? The original method uses the hyperbolic, but in principle the exponential is also possible. -#' @return A consistency score +#' @return A consistency score between 0 and 1. #' @examples #' \dontrun{ #' data("td_bc_single_ptpt") @@ -290,7 +290,8 @@ wileyto_score <- function(data) { #' Experimental method for computing indifference points #' -#' @param data Responses to score +#' @param data Responses to score. +#' @returns A dataframe with two columns: one for the block indicator and another for the corresponding indifference point. #' @export most_consistent_indiffs <- function(data) { diff --git a/R/validation-functions.R b/R/validation-functions.R index 4c771c7..f4f25d7 100644 --- a/R/validation-functions.R +++ b/R/validation-functions.R @@ -45,7 +45,7 @@ attention_checks <- function(data, warn = F, ppn = F) { #' Check for invariant responding #' -#' Check whether participants always chose the immediate reward or always chose the delayed reward +#' Check whether participants always chose the immediate reward or always chose the delayed reward. #' @param data A \code{data.frame} with columns \code{val_imm}, \code{val_del} and \code{del_chosen}, representing data from a single participant. #' @param warn Logical: give a warning for invariant responding? #' @returns Named vector specifying whether the participant chose only immediate rewards (\code{all_imm}) or chose all delayed rewards (\code{all_del}).