Consistent use of periods in documentation

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}

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,34 +491,34 @@ 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
 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
 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'],

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")

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