| Title: | Behavioral Economic Easy Discounting |
| Version: | 0.3.2 |
| Date: | 2025-01-08 |
| Maintainer: | Brent A. Kaplan <bkaplan.ku@gmail.com> |
| Description: | Facilitates some of the analyses performed in studies of behavioral economic discounting. The package supports scoring of the 27-Item Monetary Choice Questionnaire (see Kaplan et al., 2016; <doi:10.1007/s40614-016-0070-9>), calculating k values (Mazur's simple hyperbolic and exponential) using nonlinear regression, calculating various Area Under the Curve (AUC) measures, plotting regression curves for both fit-to-group and two-stage approaches, checking for unsystematic discounting (Johnson & Bickel, 2008; <doi:10.1037/1064-1297.16.3.264>) and scoring of the minute discounting task (see Koffarnus & Bickel, 2014; <doi:10.1037/a0035973>) using the Qualtrics 5-trial discounting template (see the Qualtrics Minute Discounting User Guide; <doi:10.13140/RG.2.2.26495.79527>), which is also available as a .qsf file in this package. |
| License: | GPL-2 | GPL-3 [expanded from: GPL (≥ 2)] |
| URL: | https://github.com/brentkaplan/beezdiscounting |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| Depends: | R (≥ 2.10) |
| Imports: | beezdemand, broom, dplyr, ggplot2, gtools, magrittr, minpack.lm, psych, purrr, stringr, tibble, tidyr |
| LazyData: | true |
| NeedsCompilation: | no |
| Packaged: | 2025-01-08 14:39:09 UTC; brent |
| Author: | Brent A. Kaplan 
[aut, cre, cph] |
| Repository: | CRAN |
| Date/Publication: | 2025-01-09 00:40:12 UTC |
beezdiscounting: Behavioral Economic Easy Discounting
Description
Facilitates some of the analyses performed in studies of behavioral economic discounting. The package supports scoring of the 27-Item Monetary Choice Questionnaire (see Kaplan et al., 2016; doi:10.1007/s40614-016-0070-9), calculating k values (Mazur's simple hyperbolic and exponential) using nonlinear regression, calculating various Area Under the Curve (AUC) measures, plotting regression curves for both fit-to-group and two-stage approaches, checking for unsystematic discounting (Johnson & Bickel, 2008; doi:10.1037/1064-1297.16.3.264) and scoring of the minute discounting task (see Koffarnus & Bickel, 2014; doi:10.1037/a0035973) using the Qualtrics 5-trial discounting template (see the Qualtrics Minute Discounting User Guide; doi:10.13140/RG.2.2.26495.79527), which is also available as a .qsf file in this package.
Author(s)
Maintainer: Brent Kaplan bkaplan.ku@gmail.com (ORCID) [copyright holder]
See Also
Useful links:
Pipe operator
Description
See magrittr::%>% for details.
Usage
lhs %>% rhs
Arguments
lhs |
A value or the magrittr placeholder. |
rhs |
A function call using the magrittr semantics. |
Value
The result of calling rhs(lhs).
Converts answers from 5.5 trial delay discounting from Qualtrics template
Description
Converts answers from 5.5 trial delay discounting from Qualtrics template
Usage
ans_dd(df)
Arguments
df |
A dataframe containing all the columns |
Value
A dataframe with the ResponseId, index, and response (ss or ll).
Examples
ans_dd(five.fivetrial_dd)
Converts answers from 5.5 trial probability discounting from Qualtrics template
Description
Converts answers from 5.5 trial probability discounting from Qualtrics template
Usage
ans_pd(df)
Arguments
df |
A dataframe containing all the columns |
Value
A dataframe with the ResponseId, index, and response (sc or lu).
Examples
ans_pd(five.fivetrial_pd)
Calculate Area-Under-the-Curve (AUC) Metrics for Delay Discounting Data
Description
This function calculates three types of Area-Under-the-Curve (AUC) metrics for delay discounting data: regular AUC (using raw delays), log10 AUC (using logarithmically scaled delays), and ordinal AUC (using ordinally scaled delays). These metrics provide different perspectives on the rate of delay discounting.
Usage
calc_aucs(dat)
Arguments
dat |
A data frame containing delay discounting data. It must include the following columns:
|
Value
A tibble with the following columns:
-
id: The participant or group identifier. -
auc_regular: The regular AUC, calculated using the raw delay values. -
auc_log10: The log10 AUC, calculated using logarithmically transformed delay values. -
auc_rank: The rank AUC, calculated using ordinally scaled delay values.
Examples
# Example data
data <- data.frame(
id = rep("P1", 6),
x = c(1, 7, 30, 90, 180, 365),
y = c(0.8, 0.5, 0.3, 0.2, 0.1, 0.05)
)
# Calculate AUC metrics for a single participant
calc_aucs(data)
Calculate Confidence Intervals for a Parameter
Description
This function computes the lower and upper bounds of the confidence interval for a parameter estimate, given its standard error, a specified significance level, and the degrees of freedom from the model.
Usage
calc_conf_int(estimate, std_error, model, alpha = 0.05)
Arguments
estimate |
A numeric value representing the parameter estimate. |
std_error |
A numeric value representing the standard error of the parameter estimate. |
model |
A fitted model object that provides the residual degrees of freedom via |
alpha |
A numeric value representing the significance level. Default is 0.05 (95% confidence interval). |
Value
A numeric vector of length two:
First element: Lower bound of the confidence interval.
Second element: Upper bound of the confidence interval.
Examples
# Example using a linear model
data <- data.frame(x = 1:10, y = c(2.3, 2.1, 3.7, 4.5, 5.1, 6.8, 7.3, 7.9, 9.2, 10.1))
lm_model <- lm(y ~ x, data = data)
calc_conf_int(estimate = 0.5, std_error = 0.1, model = lm_model, alpha = 0.05)
Calculate scores, answers, and timing for 5.5 trial delay discounting from Qualtrics template
Description
Calculate scores, answers, and timing for 5.5 trial delay discounting from Qualtrics template
Usage
calc_dd(df)
Arguments
df |
A dataframe containing all the columns from the template. |
Value
A dataframe with k/ed50 values, answers, timing
Examples
calc_dd(five.fivetrial_dd)
Calculate scores, answers, and timing for 5.5 trial probability discounting from Qualtrics template
Description
Calculate scores, answers, and timing for 5.5 trial probability discounting from Qualtrics template
Usage
calc_pd(df)
Arguments
df |
A dataframe containing all the columns from the template. |
Value
A dataframe with h/ep50 values, answers, timing
Examples
calc_pd(five.fivetrial_pd)
Calculate R-Squared for a Model
Description
This function calculates the coefficient of determination (R^2) for a given model by comparing the sum of squared errors (SSE)
to the total sum of squares (SST).
Usage
calc_r2(model)
Arguments
model |
A fitted model object. The model must have |
Value
A numeric value representing the R^2 value of the model. Returns NA if the model is NULL.
Examples
# Example using a simple linear model
data <- data.frame(x = 1:10, y = c(1, 2, 3, 4, 5, 6, 7, 9, 10, 11))
lm_model <- lm(y ~ x, data = data)
calc_r2(lm_model)
Check for Unsystematic Data Violations
Description
This function checks a dataset for violations of two criteria commonly used to identify unsystematic delay-discounting data:
Criterion 1: Any subsequent value of
yexceeds the previous value by more than a specified proportion of the larger later reward (ll).Criterion 2: The last value of
yis not at least a specified proportion less than the first value ofy.
Usage
check_unsystematic(dat, ll = 1, c1 = 0.2, c2 = 0.1)
Arguments
dat |
A data frame containing the delay-discounting data. It must have at least two columns:
|
ll |
A numeric value representing the larger later reward. Default is 1. |
c1 |
A numeric value for the threshold proportion for Criterion 1. Default is 0.2. |
c2 |
A numeric value for the threshold proportion for Criterion 2. Default is 0.1. |
Value
A tibble with the following columns:
-
id: The unique identifier for the data set. -
c1_pass: Logical value indicating whether Criterion 1 was passed. -
c2_pass: Logical value indicating whether Criterion 2 was passed.
Examples
data <- tibble::tibble(
id = c(rep("P1", 6)),
x = c(1, 7, 30, 90, 180, 365), # delays
y = c(0.9, 0.5, 0.3, 0.2, 0.1, 0.05) # indifference points
)
check_unsystematic(data, ll = 1, c1 = 0.2, c2 = 0.1)
Delay Discounting Data
Description
A dataset containing a set of fake delay discounting responses
Usage
dd_ip
Format
A data frame with delay discounting responses
Fit Delay-Discounting Model
Description
This function fits a delay-discounting model to the given dataset using the specified equation and method.
Usage
fit_dd(dat, equation, method)
Arguments
dat |
A data frame containing delay ( |
equation |
A character string specifying the delay-discounting equation to use. Options include:
|
method |
A character string specifying the method for fitting the model. Options include:
|
Value
A list object of class "fit_dd", containing:
The fitted model(s).
The original dataset (
dat).The specified method (
method).
Examples
data <- data.frame(
id = rep(1:2, each = 6),
x = rep(c(1, 7, 30, 90, 180, 365), 2),
y = c(0.9, 0.5, 0.3, 0.2, 0.1, 0.05, 0.85, 0.55, 0.35, 0.15, 0.1, 0.05)
)
fit_dd(data, equation = "mazur", method = "two stage")
Example Qualtrics output from the 5.5 trial delay discounting template.
Description
An example dataset containing four participants' data (two typical discounting patterns and two patterns suggesting potential misattention to the task).
Usage
five.fivetrial_dd
Format
Example Qualtrics output
Example Qualtrics output from the 5.5 trial probability discounting template.
Description
An example dataset containing four participants' data.
Usage
five.fivetrial_pd
Format
Example Qualtrics output
Generate fake MCQ data
Description
Generate fake MCQ data
Usage
generate_data_mcq(n_ids = 100, n_items = 27, seed = 1234, prop_na = 0)
Arguments
n_ids |
Number of subjectids |
n_items |
Number of trials |
seed |
Random seed |
prop_na |
Proportion of NAs in the entire data set |
Value
Dataframe of subjectid, questionid, and response
Examples
generate_data_mcq(n_ids = 2, n_items = 27, prop_na = .01)
Get internal lookup table for the 27-item MCQ
Description
Get internal lookup table for the 27-item MCQ
Usage
get_lookup_table()
Value
Dataframe with questionid, magnitude, and kindiff
Examples
get_lookup_table()
Calculates item nearest neighbor imputation approach discussed by Yeh et al. (2023)
Description
Calculates item nearest neighbor imputation approach discussed by Yeh et al. (2023)
Usage
inn(dat, random, verbose)
Arguments
dat |
A single subject's 27-item MCQ data in long form |
random |
Boolean whether to insert a random draw (0 or 1) for NAs |
verbose |
Boolean whether to print subject and question ids pertaining to missing data |
Value
An imputed data set to be scored
Reshape MCQ data long to wide
Description
Reshape MCQ data long to wide
Usage
long_to_wide_mcq(dat, q_col = "questionid", ans_col = "response")
Arguments
dat |
Long format MCQ |
q_col |
Name of the question column (default is "questionid") |
ans_col |
Name of the answer column (defualt is "response") |
Value
Wide format data frame
Reshape MCQ data from long to wide (as used in the 21- and 27-Item Monetary Choice Questionnaire Automated Scorer)
Description
Reshape MCQ data from long to wide (as used in the 21- and 27-Item Monetary Choice Questionnaire Automated Scorer)
Usage
long_to_wide_mcq_excel(dat, subj_col = "subjectid", ans_col = "response")
Arguments
dat |
Long format MCQ data |
subj_col |
Character column name of subject ids |
ans_col |
Character column name of responses |
Value
Wide format MCQ data that can be used in the Excel Automated Scorers
Examples
long_to_wide_mcq_excel(generate_data_mcq(2))
Example 27-item MCQ data
Description
A dataset containing two participants' data (same data as in the paper by Kaplan et al., 2016)
Usage
mcq27
Format
Long-form data.frame with columns: subjectid, questionid, response.
Plot Proportion of SIR/SS Choices by k Value
Description
This function creates a plot of the proportion of SIR/SS
choices by k value using the output of the prop_ss function.
Usage
## S3 method for class 'prop_ss_output'
plot(
x,
...,
pt_shape = 21,
pt_fill = "white",
pt_size = 3,
title = "Proportion of SIR/SS choices by k value",
xlab = "k value rank",
ylab = "Proportion of SS choices"
)
Arguments
x |
Output from the |
... |
Additional arguments passed to |
pt_shape |
Shape of the points in the plot. Default is 21. |
pt_fill |
Fill color of the points in the plot. Default is "white". |
pt_size |
Size of the points in the plot. Default is 3. |
title |
Title of the plot. Default is "Proportion of SIR/SS choices by k value". |
xlab |
Label for the x-axis. Default is "k value rank". |
ylab |
Label for the y-axis. Default is "Proportion of SS choices". |
Value
A ggplot object.
Examples
plot(prop_ss(mcq27))
Plot MCQ-27 Scores
Description
This function creates a plot of the MCQ-27 scores for different metrics (small_k, medium_k, large_k, geomean_k, overall_k). The function handles different logarithmic transformations of the k-values and adjusts the y-axis label accordingly.
Usage
## S3 method for class 'score_mcq27_output'
plot(x, ..., xlab = "Metric", alpha = 0.3)
Arguments
x |
A data frame returned by the |
... |
Additional arguments passed to methods. |
xlab |
Label for the x-axis. Default is "Metric". |
alpha |
Transparency of the points in the plot. Default is 0.3. |
Value
A ggplot object showing the boxplot of MCQ-27 scores.
Examples
plot(score_mcq27(mcq27))
Plot Delay-Discounting Model
Description
This function generates a plot of the delay-discounting data and the fitted model.
Usage
plot_dd(
fit_dd_object,
xlabel = "Delay",
ylabel = "Indifference Point",
title = "",
logx = TRUE
)
Arguments
fit_dd_object |
A fitted delay-discounting model object of class |
xlabel |
A character string specifying the label for the x-axis. Default is |
ylabel |
A character string specifying the label for the y-axis. Default is |
title |
A character string specifying the plot title. Default is |
logx |
Logical. If |
Value
A ggplot object representing the fitted model and data.
Examples
data <- data.frame(
id = rep(1:2, each = 6),
x = rep(c(1, 7, 30, 90, 180, 365), 2),
y = c(0.9, 0.5, 0.3, 0.2, 0.1, 0.05, 0.85, 0.55, 0.35, 0.15, 0.1, 0.05)
)
fit <- fit_dd(data, equation = "mazur", method = "mean")
plot_dd(fit)
Calculate proportion of SIR/SS responses at each k value
Description
Calculate proportion of SIR/SS responses at each k value
Usage
prop_ss(dat)
Arguments
dat |
Dataframe (longform) with subjectid, questionid, and response (0 for SIR/SS and 1 for LDR/LL) |
Value
Dataframe with proportion of SIR/SS responses at each k rank
Examples
prop_ss(mcq27)
Extract Results from Delay-Discounting Model
Description
This function extracts model parameter estimates, fit statistics, and confidence intervals from a fitted delay-discounting model.
Usage
results_dd(fit_dd_object)
Arguments
fit_dd_object |
A fitted delay-discounting model object of class |
Value
A tibble containing the following columns:
-
id: The participant or group ID (if applicable). -
term: The model parameter (e.g.,k). -
estimate: The estimated value of the parameter. -
std.error: The standard error of the parameter estimate. -
statistic: The t-statistic for the parameter estimate. -
p.value: The p-value for the parameter estimate. -
conf_low: The lower bound of the 95% confidence interval. -
conf_high: The upper bound of the 95% confidence interval. -
R2: The coefficient of determination (R^2).
Examples
data <- data.frame(
id = rep(1:2, each = 6),
x = rep(c(1, 7, 30, 90, 180, 365), 2),
y = c(0.9, 0.5, 0.3, 0.2, 0.1, 0.05, 0.85, 0.55, 0.35, 0.15, 0.1, 0.05)
)
fit <- fit_dd(data, equation = "mazur", method = "two stage")
results_dd(fit)
Score 5.5 trial delay discounting from Qualtrics template
Description
Score 5.5 trial delay discounting from Qualtrics template
Usage
score_dd(df)
Arguments
df |
A dataframe containing all the columns |
Details
Currently assumes the attending questions are present and labeled "Attend-LL" and "Attend-SS"
Value
A dataframe with id, indexes, response, k value, and effective delay 50.
Examples
score_dd(five.fivetrial_dd)
Score 27-item MCQ
Description
Score 27-item MCQ
Usage
score_mcq27(
dat = dat,
impute_method = "none",
round = 6,
random = FALSE,
trans = "none",
return_data = FALSE,
verbose = FALSE
)
Arguments
dat |
Dataframe (longform) with subjectid, questionid, and response (0 for SIR/SS and 1 for LDR/LL) |
impute_method |
One of: "none", "ggm", "GGM", "inn", "INN" |
round |
Numeric specifying number of decimal places
(passed to |
random |
Boolean whether to insert a random draw (0 or 1) for NAs. Default is FALSE |
trans |
Transformation to apply to k values: "none", "log", or "ln". Default is "none" |
return_data |
Boolean whether to return the original data and new imputed responses. Default is FALSE. |
verbose |
Boolean whether to print subject and question ids pertaining to missing data. Default is FALSE. |
Value
Summary dataframe
Examples
score_mcq27(mcq27)
Score one subject's 27-item MCQ
Description
Score one subject's 27-item MCQ
Usage
score_one_mcq27(dat, impute_method = "none", round = 6)
Arguments
dat |
One subject's 27 items from the MCQ |
impute_method |
One of: "none", "ggm", "GGM", "inn", "INN" |
round |
Numeric specifying number of decimal places
(passed to |
Value
Vector with scored 27-item MCQ metrics
Examples
beezdiscounting:::score_one_mcq27(mcq27[mcq27$subjectid %in% 1, ])
Score 5.5 trial probability discounting from Qualtrics template
Description
Score 5.5 trial probability discounting from Qualtrics template
Usage
score_pd(df)
Arguments
df |
A dataframe containing all the columns |
Details
Currently assumes the attending questions are present and labeled "Attend-LL" and "Attend-SS"
Value
A dataframe with id, indexes, response, h value, and effective probability 50.
Examples
score_pd(five.fivetrial_pd)
Provide a summary of the results from the MCQ ouutput table.
Description
Provide a summary of the results from the MCQ ouutput table.
Usage
summarize_mcq(res, na.rm = TRUE)
Arguments
res |
Dataframe with MCQ results (output from the |
na.rm |
Boolean whether to remove NAs from the calculation |
Value
Dataframe with summary statistics
Examples
summarize_mcq(score_mcq27(mcq27))
Extract timing metrics from 5.5 trial delay discounting from Qualtrics template
Description
Extract timing metrics from 5.5 trial delay discounting from Qualtrics template
Usage
timing_dd(df)
Arguments
df |
A dataframe containing all the columns |
Details
Currently assumes the attending questions are present and labeled "Attend-LL" and "Attend-SS"
Value
A dataframe with ResponseId, indexes, values and timing
Examples
timing_dd(five.fivetrial_dd)
Extract timing metrics from 5.5 trial probability discounting from Qualtrics template
Description
Extract timing metrics from 5.5 trial probability discounting from Qualtrics template
Usage
timing_pd(df)
Arguments
df |
A dataframe containing all the columns |
Details
Currently assumes the attending questions are present and labeled "Attend-LL" and "Attend-SS"
Value
A dataframe with ResponseId, indexes, values and timing
Examples
timing_pd(five.fivetrial_pd)
Reshape MCQ data wide to long
Description
Reshape MCQ data wide to long
Usage
wide_to_long_mcq(dat, items = 27)
Arguments
dat |
Wide format MCQ assuming subject id is in column 1 |
items |
Number of MCQ questions |
Value
Long format data frame
Reshape MCQ data from wide (as used in the 21- and 27-Item Monetary Choice Questionnaire Automated Scorer) to long
Description
Reshape MCQ data from wide (as used in the 21- and 27-Item Monetary Choice Questionnaire Automated Scorer) to long
Usage
wide_to_long_mcq_excel(dat)
Arguments
dat |
Wide format MCQ data as used in the Excel Automated Scorers |
Value
Long format data frame
Examples
wide_to_long_mcq_excel(long_to_wide_mcq_excel(generate_data_mcq(2)))