Help for package CBSr

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:

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 to normD. 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 in Delay1 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 with Delay1 chance of winning). Choice==0 means participnat chose the certain option (i.e., $20 for sure)