Type: | Package |
Title: | Fits Cubic Bezier Spline Functions to Intertemporal and Risky Choice Data |
Version: | 1.0.5 |
Description: | Uses monotonically constrained Cubic Bezier Splines (CBS) to approximate latent utility functions in intertemporal choice and risky choice data. For more information, see Lee, Glaze, Bradlow, and Kable <doi:10.1007/s11336-020-09723-4>. |
License: | GPL-3 |
Depends: | R (≥ 3.5) |
Encoding: | UTF-8 |
LazyData: | true |
Imports: | rJava (≥ 0.9-11), NlcOptim (≥ 0.6) |
SystemRequirements: | Java (>= 7.0) |
NeedsCompilation: | no |
RoxygenNote: | 7.1.1 |
Packaged: | 2021-02-20 16:12:08 UTC; sangi |
Author: | Sangil Lee [aut, cre] |
Maintainer: | Sangil Lee <sangillee3rd@gmail.com> |
Repository: | CRAN |
Date/Publication: | 2021-02-20 16:30:03 UTC |
CBS_ITC
Description
Fit either a 1-piece or 2-piece CBS latent utility function to binary intertemporal choice data.
Usage
CBS_ITC(choice, Amt1, Delay1, Amt2, Delay2, numpiece, numfit = NULL)
Arguments
choice |
Vector of 0s and 1s. 1 if the choice was option 1, 0 if the choice was option 2. |
Amt1 |
Vector of positive real numbers. Reward amount of choice 1. |
Delay1 |
Vector of positive real numbers. Delay until the reward of choice 1. |
Amt2 |
Vector of positive real numbers. Reward amount of choice 2. |
Delay2 |
Vector of positive real numbers. Delay until the reward of choice 2. |
numpiece |
Either 1 or 2. Number of CBS pieces to use. |
numfit |
Number of model fits to perform from different starting points. If not provided, numfit = 10*numpiece |
Details
The input data has n choices (ideally n > 100) between two reward options.
Option 1 is receiving Amt1
in Delay1
and Option 2 is receiving Amt2
in Delay2
(e.g., $40 in 20 days vs. $20 in 3 days).
One of the two options may be immediate (i.e., delay = 0; e.g., $40 in 20 days vs. $20 today).
choice
should be 1 if option 1 is chosen, 0 if option 2 is chosen.
Value
A list containing the following:
-
type
: either 'CBS1' or 'CBS2' depending on the number of pieces -
LL
: log likelihood of the model -
numparam
: number of total parameters in the model -
scale
: scaling factor of the logit model -
xpos
: x coordinates of the fitted CBS function -
ypos
: y coordinates of the fitted CBS function -
AUC
: area under the curve of the fitted CBS function. Normalized to be between 0 and 1. -
normD
: The domain of CBS function runs from 0 tonormD
. Specifically, this is the constant used to normalize all delays between 0 and 1, since CBS is fitted in a unit square first and then scaled up.
Examples
# Fit example ITC data with 2-piece CBS function.
# Load example data (included with package).
# Each row is a choice between option 1 (Amt at Delay) vs option 2 (20 now).
Amount1 = ITCdat$Amt1
Delay1 = ITCdat$Delay1
Amount2 = 20
Delay2 = 0
Choice = ITCdat$Choice
# Fit the model
out = CBS_ITC(Choice,Amount1,Delay1,Amount2,Delay2,2)
# Plot the choices (x = Delay, y = relative amount : 20 / delayed amount)
plot(Delay1[Choice==1],20/Amount1[Choice==1],type = 'p',col="blue",xlim=c(0, 180), ylim=c(0, 1))
points(Delay1[Choice==0],20/Amount1[Choice==0],type = 'p',col="red")
# Plot the fitted CBS
x = 0:out$normD
lines(x,CBSfunc(out$xpos,out$ypos,x),col="black")
CBS_RC
Description
Fit either a 1-piece or 2-piece CBS latent utility function to binary risky choice data.
Usage
CBS_RC(choice, Amt1, Prob1, Amt2, Prob2, numpiece, numfit = NULL)
Arguments
choice |
Vector of 0s and 1s. 1 if the choice was option 1, 0 if the choice was option 2. |
Amt1 |
Vector of positive real numbers. Reward amount of choice 1. |
Prob1 |
Vector of positive real numbers between 0 and 1. Probability of winning the reward of choice 1. |
Amt2 |
Vector of positive real numbers. Reward amount of choice 2. |
Prob2 |
Vector of positive real numbers between 0 and 1. Probability of winning the reward of choice 2. |
numpiece |
Either 1 or 2. Number of CBS pieces to use. |
numfit |
Number of model fits to perform from different starting points. If not provided, numfit = 10*numpiece |
Details
The input data has n choices (ideally n > 100) between two reward options.
Option 1 is receiving Amt1
with probability Prob1
and Option 2 is receiving Amt2
with probability Prob2
(e.g., $40 with 53% chance vs. $20 with 90% chance).
One of the two options may be certain (i.e., prob = 1; e.g., $40 with 53% chance vs. $20 for sure).
choice
should be 1 if option 1 is chosen, 0 if option 2 is chosen.
Value
A list containing the following:
-
type
: either 'CBS1' or 'CBS2' depending on the number of pieces -
LL
: log likelihood of the model -
numparam
: number of total parameters in the model -
scale
: scaling factor of the logit model -
xpos
: x coordinates of the fitted CBS function -
ypos
: y coordinates of the fitted CBS function -
AUC
: area under the curve of the fitted CBS function. Normalized to be between 0 and 1.
Examples
# Fit example Risky choice data with 2-piece CBS function.
# Load example data (included with package).
# Each row is a choice between option 1 (Amt with prob) vs option 2 (20 for 100%).
Amount1 = RCdat$Amt1
Prob1 = RCdat$Prob1
Amount2 = 20
Prob2 = 1
Choice = RCdat$Choice
# Fit the model
out = CBS_RC(Choice,Amount1,Prob1,Amount2,Prob2,2)
# Plot the choices (x = Delay, y = relative amount : 20 / risky amount)
plot(Prob1[Choice==1],20/Amount1[Choice==1],type = 'p',col="blue",xlim=c(0, 1), ylim=c(0, 1))
points(Prob1[Choice==0],20/Amount1[Choice==0],type = 'p',col="red")
# Plot the fitted CBS
x = seq(0,1,.01)
lines(x,CBSfunc(out$xpos,out$ypos,x))
CBSfunc
Description
Calculate either the Area Under the Curve (AUC) of a CBS function, or calculate the y coordinates of CBS function given x.
Usage
CBSfunc(xpos, ypos, x = NULL)
Arguments
xpos |
Vector of real numbers of length 1+3n (n = 1, 2, 3, ...), corresponding to Bezier points' x-coordinates of a CBS function |
ypos |
Vector of real numbers of length 1+3n (n = 1, 2, 3, ...), corresponding to Bezier points' y-coordinates of a CBS function |
x |
Vector of real numbers, corresponding to x-coordinates of a CBS function. Default value is Null. |
Value
If x is provided, return y coordinates corresponding to x. If x is not provided, return AUC.
Examples
CBSfunc(c(0,0.3,0.6,1),c(0.5, 0.2, 0.7, 0.9))
CBSfunc(c(0,0.3,0.6,1),c(0.5, 0.2, 0.7, 0.9),seq(0,1,0.1))
Sample participant data from a binary intertemporal choice task (aka delay discounting task)
Description
A dataset containing one sample participant's 120 binary choices between a delayed monetary option (Amt1
in Delay1
) and a immediate monetary option ($20 now).
The immediate monetary option was always '$20 now' across all trials
Usage
ITCdat
Format
A data frame with 120 rows and 3 variables:
- Amt1
Delayed reward amount, in dollars
- Delay1
Delay until the receipt of
Amt1
, in days- Choice
Choice between binary options.
Choice==1
means participnat chose the delayed option (i.e.,Amt1
inDelay1
days).Choice==0
means participnat chose the immediate option (i.e., $20 now)
Source
Kable, J. W., Caulfield, M. K., Falcone, M., McConnell, M., Bernardo, L., Parthasarathi, T., ... & Diefenbach, P. (2017). No effect of commercial cognitive training on brain activity, choice behavior, or cognitive performance. Journal of Neuroscience, 37(31), 7390-7402.
Sample participant data from a binary risky choice task (aka risk aversion task)
Description
A dataset containing one sample participant's 120 binary choices between a probabilistic monetary option (Amt1
with Prob1
chance of winning) and a certain monetary option ($20 for sure).
The certain monetary option was always '$20 for sure' across all trials
Usage
RCdat
Format
A data frame with 120 rows and 3 variables:
- Amt1
Probabilistic reward amount, in dollars
- Prob1
Probability of winning
Amt1
, if it were to be chosen- Choice
Choice between binary options.
Choice==1
means participnat chose the probabilistic option (i.e.,Amt1
withDelay1
chance of winning).Choice==0
means participnat chose the certain option (i.e., $20 for sure)
Source
Kable, J. W., Caulfield, M. K., Falcone, M., McConnell, M., Bernardo, L., Parthasarathi, T., ... & Diefenbach, P. (2017). No effect of commercial cognitive training on brain activity, choice behavior, or cognitive performance. Journal of Neuroscience, 37(31), 7390-7402.