| Title: | Fit Linearized Hyperbolic Model for Delay Discounting Curves |
| Version: | 0.0.1 |
| Description: | Functions for estimating parameters and hyperparameters of the linearized hyperbolic model, and testing equality of hyperparameters. |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.3 |
| Imports: | dplyr, magrittr, rlang |
| Depends: | R (≥ 3.5) |
| LazyData: | true |
| Suggests: | knitr, rmarkdown, testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| VignetteBuilder: | knitr |
| URL: | https://github.com/davideh-vt/delaydiscount, https://davideh-vt.github.io/delaydiscount/ |
| BugReports: | https://github.com/davideh-vt/delaydiscount/issues |
| NeedsCompilation: | no |
| Packaged: | 2026-04-30 20:40:16 UTC; deh99 |
| Author: | David Hinds [aut, cre], Marco Ferreira [aut], Allison Tegge [ctb], Jeff Stein [ctb] |
| Maintainer: | David Hinds <davideh@vt.edu> |
| Repository: | CRAN |
| Date/Publication: | 2026-05-05 15:22:35 UTC |
Check preconditions for an input data frame for the prepare_data_frame and jb_rule_check functions.
Description
This function is a helper function for the prepare_data_frame and jb_rule_check methods.
Usage
check_input_preconditions(dd_data)
Arguments
dd_data |
A data frame containing discounting data in long format. This function is designed to fail if the preconditions for the discounting data data frame are not met. |
Value
NULL if the input data frame passes the format checks. Throws an error if an input check is failed.
Examples
check_input_preconditions(remedi)
This function gets model parameter estimates for each group, including hyperparameters and estimates of the variance components (the observation error and subject random effect). It also gets F-test results for pairwise equality for the hyperparameter for each pair of groups, and overall equality of all hyperparameters.
Description
This function gets model parameter estimates for each group, including hyperparameters and estimates of the variance components (the observation error and subject random effect). It also gets F-test results for pairwise equality for the hyperparameter for each pair of groups, and overall equality of all hyperparameters.
Usage
dd_hyperbolic_model(dd_data)
Arguments
dd_data |
A specially formatted data frame as returned by the prepare_data_frame function. |
Value
A list with the objects ln_k_mean is a data frame with estimates of the hyperparameters of each group along with the standard error of the estimate. The hyperparameter for each group can be interpreted as the mean ln(k) for a subject in that group. var is a vector with entries sigma_sq and g. sigma_sq is the variance of the observed transformed indifference conditioned on the true ln(k) for the subject g is related to the variance of the subject random effect, which is equal to g*sigma_sq/T, where T is the number of time points. pairwise_f_tests is a data frame containing the results of all of the pairwise f-tests for equality of hyperparameters. The columns col1 and col2 contain the groups of the pairwise F-test. The F_stat column contains the F-statistic, the p_value column contains the p-value, and the df1 and df2 columns contain the numerator and denominator degrees of freedom, respectively. model_test is a data frame containing the result of the F-test for equality of all hyperparameters. It contains the columns F_stat, p_value, df1, and df2, which have the same meaning as in the pairwise_f_tests data frame.
Examples
prep_remedi <- prepare_data_frame(remedi)
dd_model <- dd_hyperbolic_model(prep_remedi)
Estimate the hyperparameters for each group, as well as the variance components of the model, using maximum likelihood estimation.
Description
This function is a helper function for dd_hyperbolic_model. We recommend not using this function on its own.
Usage
estimate_hyperbolic_model_params(dd_data)
Arguments
dd_data |
A specially formatted data frame as returned by the prepare_data_frame function. |
Value
A list of two objects: ln_k_mean is a data frame with estimates of the hyperparameters of each group along with the standard error of the estimate. The hyperparameter for each group can be interpreted as the mean ln(k) for a subject in that group. var is a vector with entries sigma_sq and g. sigma_sq is the variance of the observed transformed indifference conditioned on the true ln(k) for the subject. g is related to the variance of the subject random effect, which is equal to g*sigma_sq/T, where T is the number of time points.
Examples
prep_remedi <- prepare_data_frame(remedi)
param_ests <- estimate_hyperbolic_model_params(prep_remedi)
Return ln(k) estimates for each subject.
Description
Return ln(k) estimates for each subject.
Usage
get_subj_est_ln_k(dd_data)
Arguments
dd_data |
A specially formatted data frame as returned by the prepare_data_frame function. |
Value
A data frame consisting of one observation per subject within group with the variable ln_k containing that subject's estimated ln_k value.
Examples
prep_remedi <- prepare_data_frame(remedi)
subj_est_ln_k <- get_subj_est_ln_k(prep_remedi)
Perform an F-test for equality of some combination(s) of hyperparameters.
Description
This function is a helper function for dd_hyperbolic_model. We recommend not using this function on its own.
Usage
hyperbolic_model_f_test(dd_data, hypothesis)
Arguments
dd_data |
A specially formatted data frame as returned by the prepare_data_frame function. |
hypothesis |
A list of string vectors. Each string is the name of a group. No group appears in more than one vector. Each vector represents a set of hyperparameters that are assumed to be equal under the null hypothesis. |
Value
A list with the entries F_stat, the test statistic of the F-test; p_value, the p-value of the F-test; df1, the numerator degrees of freedom of the F-test (dimensionality of H0); df2, the denominator degrees of freedom of the F-test.
Examples
prep_remedi <- prepare_data_frame(remedi)
f_test_result <- hyperbolic_model_f_test(prep_remedi, list(c("EFT", "NCC")))
Apply Johnson-Bickel rule checks to each subject.
Description
The rules are:
There must be no more than one pair of consecutive time points in which the indifference point increases by more than 0.2.
The indifference point must decrease by at least 0.1 from the earliest to the latest time point.
Usage
jb_rule_check(dd_data)
Arguments
dd_data |
A data frame containing discounting data in long format. The data should be in long format, with columns identifying the subject, group and time point for each observation, and the indifference point. The variables should be named subj, group, delay, and indiff, respectively. Values for indifference points should be between 0 and 1, exclusive. All delays should be positive. All subjects should have observations for the exact same set of delays. |
Value
A data frame consisting of one observation per subject within group with the boolean variables C1 and C2 which are TRUE if the corresponding rule was passed and FALSE if it was not.
Examples
rule_check_result <- jb_rule_check(remedi)
Prepare a data frame containing discounting for use on the other functions in this package.
Description
This includes: Reducing the data frame to only contain the expected variables. Sorting the observations into an expected order. Transforming delay and indifference for the linearized model. Estimating ln(k) for each subject. Calculating residuals from observed values vs predictions by estimated ln(k).
Usage
prepare_data_frame(dd_data)
Arguments
dd_data |
A data frame containing discounting data in long format. The data should be in long format, with columns identifying the subject, group and time point for each observation, and the indifference point. The variables should be named subj, group, delay, and indiff, respectively. Values for indifference points should be between 0 and 1, exclusive. All delays should be positive. All subjects should have observations for the exact same set of delays. |
Value
A data frame compatible with the other functions in this package.
Examples
prep_remedi <- prepare_data_frame(remedi)
REMEDI data
Description
Delay discounting survey data from 434 adult subjects who reported having obesity and type 2 diabetes.
Usage
remedi
Format
remedi
A data frame with 3,038 rows and 5 columns:
- study
Study name (always REMEDI)
- subj
Subject ID Number
- group
Condition group
- delay
The wait in days to receive the reward,
- indiff
The requisite proportion of reward needed for the subject to be indifferent to waiting for the full reward or receiving a reduced reward immediately
Source
Brown, et al. (2023). "Episodic future thinking in type 2 diabetes: Further development and validation of the Health Information Thinking control for clinical trials". PLoS ONE 18(8): e0289478 https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0289478
Simulate a dataset from the hierarchical linearized hyperbolic model.
Description
Simulate a dataset from the hierarchical linearized hyperbolic model.
Usage
simulate_dataset(groups, num_subj, time_points, mean_ln_k, sigma_sq, g)
Arguments
groups |
A character vector, with each component naming a group. |
num_subj |
An integer vector the same length as the vector of groups. Each entry represents the number of subjects in the respective group. |
time_points |
A vector of positive numbers in increasing order, representing the time points at which a subject's delay discounting rate is measured. |
mean_ln_k |
A numeric vector of the same length as the vector of groups. Each value represents the population ln_k mean for that group. |
sigma_sq |
The variance of an observed indifference points's transformed value, conditional on the variance. |
g |
Parameter controlling the variance of individual subject ln k parameters. Equal to Var(ln_k)*(Number of time points)/sigma_sq, that is, the ratio of the variance of a subject ln k parameter to the variance of the estimate of a subject ln k parameter (conditional on the true ln k parameter). |
Value
A data frame of simulated delay discounting data containing one observation per delay per subject. It contains the following columns: subj: A number identifying the subject. true_ln_k: The true ln_k parameter of that subject. group: The subject's group. delay: The delay for the observation. indiff: The indifference point for the subject at the delay the observation corresponds to, between 0 and 1, representing the proportion of the reward the subject would need to receive to choose receiving the smaller reward now instead of waiting the delay for the full reward.
Examples
dd_data <- simulate_dataset(groups = c("EFT", "NCC"),
num_subj = c(75, 150),
time_points = c(30, 90, 180, 365, 1095, 1825, 3650),
mean_ln_k = c(-6.7, -6),
sigma_sq = 1.5, g = 10)