Hierarchical Bayesian Modeling of Decision-Making Tasks

Description

Fit an array of decision-making tasks with computational models in a hierarchical Bayesian framework. Can perform hierarchical Bayesian analysis of various computational models with a single line of coding. Bolded tasks, followed by their respective models, are itemized below.

Bandit

2-Armed Bandit (Rescorla-Wagner (delta)) — bandit2arm_delta
4-Armed Bandit with fictive updating + reward/punishment sensitvity (Rescorla-Wagner (delta)) — bandit4arm_4par
4-Armed Bandit with fictive updating + reward/punishment sensitvity + lapse (Rescorla-Wagner (delta)) — bandit4arm_lapse

Bandit2

Kalman filter — bandit4arm2_kalman_filter

Cambridge Gambling Task

Cumulative Model — cgt_cm

Choice RT

Drift Diffusion Model — choiceRT_ddm
Drift Diffusion Model for a single subject — choiceRT_ddm_single
Linear Ballistic Accumulator (LBA) model — choiceRT_lba
Linear Ballistic Accumulator (LBA) model for a single subject — choiceRT_lba_single

Choice under Risk and Ambiguity

Exponential model — cra_exp
Linear model — cra_linear

Description-Based Decision Making

probability weight function — dbdm_prob_weight

Delay Discounting

Constant Sensitivity — dd_cs
Constant Sensitivity for a single subject — dd_cs_single
Exponential — dd_exp
Hyperbolic — dd_hyperbolic
Hyperbolic for a single subject — dd_hyperbolic_single

Orthogonalized Go/Nogo

RW + Noise — gng_m1
RW + Noise + Bias — gng_m2
RW + Noise + Bias + Pavlovian Bias — gng_m3
RW(modified) + Noise + Bias + Pavlovian Bias — gng_m4

Iowa Gambling

Outcome-Representation Learning — igt_orl
Prospect Valence Learning-DecayRI — igt_pvl_decay
Prospect Valence Learning-Delta — igt_pvl_delta
Value-Plus_Perseverance — igt_vpp

Peer influence task

OCU model — peer_ocu

Probabilistic Reversal Learning

Experience-Weighted Attraction — prl_ewa
Fictitious Update — prl_fictitious
Fictitious Update w/o alpha (indecision point) — prl_fictitious_woa
Fictitious Update and multiple blocks per subject — prl_fictitious_multipleB
Reward-Punishment — prl_rp
Reward-Punishment and multiple blocks per subject — prl_rp_multipleB
Fictitious Update with separate learning for Reward-Punishment — prl_fictitious_rp
Fictitious Update with separate learning for Reward-Punishment w/o alpha (indecision point) — prl_fictitious_rp_woa

Probabilistic Selection Task

Q-learning with two learning rates — pst_gainloss_Q

Risk Aversion

Prospect Theory (PT) — ra_prospect
PT without a loss aversion parameter — ra_noLA
PT without a risk aversion parameter — ra_noRA

Risky Decision Task

Happiness model — rdt_happiness

Two-Step task

Full model (7 parameters) — ts_par7
6 parameter model (without eligibility trace, lambda) — ts_par6
4 parameter model — ts_par4

Ultimatum Game

Ideal Bayesian Observer — ug_bayes
Rescorla-Wagner (delta) — ug_delta

Author(s)

Woo-Young Ahn wahn55@snu.ac.kr

Nathaniel Haines haines.175@osu.edu

Lei Zhang bnuzhanglei2008@gmail.com

References

Please cite as: Ahn, W.-Y., Haines, N., & Zhang, L. (2017). Revealing neuro-computational mechanisms of reinforcement learning and decision-making with the hBayesDM package. Computational Psychiatry. 1, 24-57. https://doi.org/10.1162/CPSY_a_00002

See Also

For tutorials and further readings, visit : http://rpubs.com/CCSL/hBayesDM.

Compute Highest-Density Interval

Description

Computes the highest density interval from a sample of representative values, estimated as shortest credible interval. Based on John Kruschke's codes.

Usage

HDIofMCMC(sampleVec, credMass = 0.95)

Arguments

Value

A vector containing the limits of the HDI

Rescorla-Wagner (Delta) Model

Description

Hierarchical Bayesian Modeling of the Aversive Learning Task using Rescorla-Wagner (Delta) Model. It has the following parameters: A (learning rate), beta (inverse temperature), gamma (risk preference).

• Task: Aversive Learning Task (Browning et al., 2015)

• Model: Rescorla-Wagner (Delta) Model

Usage

alt_delta(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Aversive Learning Task, there should be 5 columns of data with the labels "subjID", "choice", "outcome", "bluePunish", "orangePunish". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial (blue == 1, orange == 2).

outcome

Integer value representing the outcome of the given trial (punishment == 1, and non-punishment == 0).

bluePunish

Floating point value representing the magnitude of punishment for blue on that trial (e.g., 10, 97)

orangePunish

Floating point value representing the magnitude of punishment for orange on that trial (e.g., 23, 45)

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Lili Zhang <lili.zhang27@mail.dcu.ie>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"alt_delta").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Browning, M., Behrens, T. E., Jocham, G., O'reilly, J. X., & Bishop, S. J. (2015). Anxious individuals have difficulty learning the causal statistics of aversive environments. Nature neuroscience, 18(4), 590.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- alt_delta(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- alt_delta(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Rescorla-Wagner (Gamma) Model

Description

Hierarchical Bayesian Modeling of the Aversive Learning Task using Rescorla-Wagner (Gamma) Model. It has the following parameters: A (learning rate), beta (inverse temperature), gamma (risk preference).

• Task: Aversive Learning Task (Browning et al., 2015)

• Model: Rescorla-Wagner (Gamma) Model

Usage

alt_gamma(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Aversive Learning Task, there should be 5 columns of data with the labels "subjID", "choice", "outcome", "bluePunish", "orangePunish". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial (blue == 1, orange == 2).

outcome

Integer value representing the outcome of the given trial (punishment == 1, and non-punishment == 0).

bluePunish

Floating point value representing the magnitude of punishment for blue on that trial (e.g., 10, 97)

orangePunish

Floating point value representing the magnitude of punishment for orange on that trial (e.g., 23, 45)

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Lili Zhang <lili.zhang27@mail.dcu.ie>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"alt_gamma").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Browning, M., Behrens, T. E., Jocham, G., O'reilly, J. X., & Bishop, S. J. (2015). Anxious individuals have difficulty learning the causal statistics of aversive environments. Nature neuroscience, 18(4), 590.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- alt_gamma(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- alt_gamma(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Rescorla-Wagner (Delta) Model

Description

Hierarchical Bayesian Modeling of the 2-Armed Bandit Task using Rescorla-Wagner (Delta) Model. It has the following parameters: A (learning rate), tau (inverse temperature).

• Task: 2-Armed Bandit Task (Erev et al., 2010; Hertwig et al., 2004)

• Model: Rescorla-Wagner (Delta) Model

Usage

bandit2arm_delta(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the 2-Armed Bandit Task, there should be 3 columns of data with the labels "subjID", "choice", "outcome". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1 or 2.

outcome

Integer value representing the outcome of the given trial (where reward == 1, and loss == -1).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"bandit2arm_delta").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Erev, I., Ert, E., Roth, A. E., Haruvy, E., Herzog, S. M., Hau, R., et al. (2010). A choice prediction competition: Choices from experience and from description. Journal of Behavioral Decision Making, 23(1), 15-47. https://doi.org/10.1002/bdm.683

Hertwig, R., Barron, G., Weber, E. U., & Erev, I. (2004). Decisions From Experience and the Effect of Rare Events in Risky Choice. Psychological Science, 15(8), 534-539. https://doi.org/10.1111/j.0956-7976.2004.00715.x

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- bandit2arm_delta(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- bandit2arm_delta(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Kalman Filter

Description

Hierarchical Bayesian Modeling of the 4-Armed Bandit Task (modified) using Kalman Filter. It has the following parameters: lambda (decay factor), theta (decay center), beta (inverse softmax temperature), mu0 (anticipated initial mean of all 4 options), s0 (anticipated initial sd (uncertainty factor) of all 4 options), sD (sd of diffusion noise).

• Task: 4-Armed Bandit Task (modified)

• Model: Kalman Filter (Daw et al., 2006)

Usage

bandit4arm2_kalman_filter(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the 4-Armed Bandit Task (modified), there should be 3 columns of data with the labels "subjID", "choice", "outcome". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, or 4.

outcome

Integer value representing the outcome of the given trial (where reward == 1, and loss == -1).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Yoonseo Zoh <zohyos7@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"bandit4arm2_kalman_filter").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Daw, N. D., O'Doherty, J. P., Dayan, P., Seymour, B., & Dolan, R. J. (2006). Cortical substrates for exploratory decisions in humans. Nature, 441(7095), 876-879.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- bandit4arm2_kalman_filter(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- bandit4arm2_kalman_filter(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

3 Parameter Model, without C (choice perseveration), R (reward sensitivity), and P (punishment sensitivity). But with xi (noise)

Description

Hierarchical Bayesian Modeling of the 4-Armed Bandit Task using 3 Parameter Model, without C (choice perseveration), R (reward sensitivity), and P (punishment sensitivity). But with xi (noise). It has the following parameters: Arew (reward learning rate), Apun (punishment learning rate), xi (noise).

• Task: 4-Armed Bandit Task

• Model: 3 Parameter Model, without C (choice perseveration), R (reward sensitivity), and P (punishment sensitivity). But with xi (noise) (Aylward et al., 2018)

Usage

bandit4arm_2par_lapse(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the 4-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, or 4.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"bandit4arm_2par_lapse").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Aylward, Valton, Ahn, Bond, Dayan, Roiser, & Robinson (2018) Altered decision-making under uncertainty in unmedicated mood and anxiety disorders. PsyArxiv. 10.31234/osf.io/k5b8m

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- bandit4arm_2par_lapse(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- bandit4arm_2par_lapse(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

4 Parameter Model, without C (choice perseveration)

Description

Hierarchical Bayesian Modeling of the 4-Armed Bandit Task using 4 Parameter Model, without C (choice perseveration). It has the following parameters: Arew (reward learning rate), Apun (punishment learning rate), R (reward sensitivity), P (punishment sensitivity).

• Task: 4-Armed Bandit Task

• Model: 4 Parameter Model, without C (choice perseveration) (Seymour et al., 2012)

Usage

bandit4arm_4par(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the 4-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, or 4.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"bandit4arm_4par").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Seymour, Daw, Roiser, Dayan, & Dolan (2012). Serotonin Selectively Modulates Reward Value in Human Decision-Making. J Neuro, 32(17), 5833-5842.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- bandit4arm_4par(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- bandit4arm_4par(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

5 Parameter Model, without C (choice perseveration) but with xi (noise)

Description

Hierarchical Bayesian Modeling of the 4-Armed Bandit Task using 5 Parameter Model, without C (choice perseveration) but with xi (noise). It has the following parameters: Arew (reward learning rate), Apun (punishment learning rate), R (reward sensitivity), P (punishment sensitivity), xi (noise).

• Task: 4-Armed Bandit Task

• Model: 5 Parameter Model, without C (choice perseveration) but with xi (noise) (Seymour et al., 2012)

Usage

bandit4arm_lapse(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the 4-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, or 4.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"bandit4arm_lapse").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Seymour, Daw, Roiser, Dayan, & Dolan (2012). Serotonin Selectively Modulates Reward Value in Human Decision-Making. J Neuro, 32(17), 5833-5842.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- bandit4arm_lapse(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- bandit4arm_lapse(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

5 Parameter Model, without C (choice perseveration) but with xi (noise). Added decay rate (Niv et al., 2015, J. Neuro).

Description

Hierarchical Bayesian Modeling of the 4-Armed Bandit Task using 5 Parameter Model, without C (choice perseveration) but with xi (noise). Added decay rate (Niv et al., 2015, J. Neuro).. It has the following parameters: Arew (reward learning rate), Apun (punishment learning rate), R (reward sensitivity), P (punishment sensitivity), xi (noise), d (decay rate).

• Task: 4-Armed Bandit Task

• Model: 5 Parameter Model, without C (choice perseveration) but with xi (noise). Added decay rate (Niv et al., 2015, J. Neuro). (Aylward et al., 2018)

Usage

bandit4arm_lapse_decay(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the 4-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, or 4.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"bandit4arm_lapse_decay").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Aylward, Valton, Ahn, Bond, Dayan, Roiser, & Robinson (2018) Altered decision-making under uncertainty in unmedicated mood and anxiety disorders. PsyArxiv. 10.31234/osf.io/k5b8m

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- bandit4arm_lapse_decay(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- bandit4arm_lapse_decay(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

4 Parameter Model, without C (choice perseveration) but with xi (noise). Single learning rate both for R and P.

Description

Hierarchical Bayesian Modeling of the 4-Armed Bandit Task using 4 Parameter Model, without C (choice perseveration) but with xi (noise). Single learning rate both for R and P.. It has the following parameters: A (learning rate), R (reward sensitivity), P (punishment sensitivity), xi (noise).

• Task: 4-Armed Bandit Task

• Model: 4 Parameter Model, without C (choice perseveration) but with xi (noise). Single learning rate both for R and P. (Aylward et al., 2018)

Usage

bandit4arm_singleA_lapse(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the 4-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, or 4.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"bandit4arm_singleA_lapse").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Aylward, Valton, Ahn, Bond, Dayan, Roiser, & Robinson (2018) Altered decision-making under uncertainty in unmedicated mood and anxiety disorders. PsyArxiv. 10.31234/osf.io/k5b8m

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- bandit4arm_singleA_lapse(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- bandit4arm_singleA_lapse(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

3 Parameter Model, without C (choice perseveration), R (reward sensitivity), and P (punishment sensitivity). But with xi (noise)

Description

Hierarchical Bayesian Modeling of the N-Armed Bandit Task using 3 Parameter Model, without C (choice perseveration), R (reward sensitivity), and P (punishment sensitivity). But with xi (noise). It has the following parameters: Arew (reward learning rate), Apun (punishment learning rate), xi (noise).

• Task: N-Armed Bandit Task

• Model: 3 Parameter Model, without C (choice perseveration), R (reward sensitivity), and P (punishment sensitivity). But with xi (noise) (Aylward et al., 2018)

Usage

banditNarm_2par_lapse(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the N-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, ... N.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Cheol Jun Cho <cjfwndnsl@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"banditNarm_2par_lapse").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Aylward, Valton, Ahn, Bond, Dayan, Roiser, & Robinson (2018) Altered decision-making under uncertainty in unmedicated mood and anxiety disorders. PsyArxiv. 10.31234/osf.io/k5b8m

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- banditNarm_2par_lapse(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- banditNarm_2par_lapse(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

4 Parameter Model, without C (choice perseveration)

Description

Hierarchical Bayesian Modeling of the N-Armed Bandit Task using 4 Parameter Model, without C (choice perseveration). It has the following parameters: Arew (reward learning rate), Apun (punishment learning rate), R (reward sensitivity), P (punishment sensitivity).

• Task: N-Armed Bandit Task

• Model: 4 Parameter Model, without C (choice perseveration) (Seymour et al., 2012)

Usage

banditNarm_4par(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the N-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, ... N.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Cheol Jun Cho <cjfwndnsl@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"banditNarm_4par").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Seymour, Daw, Roiser, Dayan, & Dolan (2012). Serotonin Selectively Modulates Reward Value in Human Decision-Making. J Neuro, 32(17), 5833-5842.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- banditNarm_4par(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- banditNarm_4par(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Rescorla-Wagner (Delta) Model

Description

Hierarchical Bayesian Modeling of the N-Armed Bandit Task using Rescorla-Wagner (Delta) Model. It has the following parameters: A (learning rate), tau (inverse temperature).

• Task: N-Armed Bandit Task (Erev et al., 2010; Hertwig et al., 2004)

• Model: Rescorla-Wagner (Delta) Model

Usage

banditNarm_delta(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the N-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, ... N.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Cheol Jun Cho <cjfwndnsl@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"banditNarm_delta").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Erev, I., Ert, E., Roth, A. E., Haruvy, E., Herzog, S. M., Hau, R., et al. (2010). A choice prediction competition: Choices from experience and from description. Journal of Behavioral Decision Making, 23(1), 15-47. https://doi.org/10.1002/bdm.683

Hertwig, R., Barron, G., Weber, E. U., & Erev, I. (2004). Decisions From Experience and the Effect of Rare Events in Risky Choice. Psychological Science, 15(8), 534-539. https://doi.org/10.1111/j.0956-7976.2004.00715.x

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- banditNarm_delta(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- banditNarm_delta(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Kalman Filter

Description

Hierarchical Bayesian Modeling of the N-Armed Bandit Task (modified) using Kalman Filter. It has the following parameters: lambda (decay factor), theta (decay center), beta (inverse softmax temperature), mu0 (anticipated initial mean of all 4 options), s0 (anticipated initial sd (uncertainty factor) of all 4 options), sD (sd of diffusion noise).

• Task: N-Armed Bandit Task (modified)

• Model: Kalman Filter (Daw et al., 2006)

Usage

banditNarm_kalman_filter(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the N-Armed Bandit Task (modified), there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, ... N.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Yoonseo Zoh <zohyos7@gmail.com>, Cheol Jun Cho <cjfwndnsl@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"banditNarm_kalman_filter").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Daw, N. D., O'Doherty, J. P., Dayan, P., Seymour, B., & Dolan, R. J. (2006). Cortical substrates for exploratory decisions in humans. Nature, 441(7095), 876-879.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- banditNarm_kalman_filter(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- banditNarm_kalman_filter(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

5 Parameter Model, without C (choice perseveration) but with xi (noise)

Description

Hierarchical Bayesian Modeling of the N-Armed Bandit Task using 5 Parameter Model, without C (choice perseveration) but with xi (noise). It has the following parameters: Arew (reward learning rate), Apun (punishment learning rate), R (reward sensitivity), P (punishment sensitivity), xi (noise).

• Task: N-Armed Bandit Task

• Model: 5 Parameter Model, without C (choice perseveration) but with xi (noise) (Seymour et al., 2012)

Usage

banditNarm_lapse(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the N-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, ... N.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Cheol Jun Cho <cjfwndnsl@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"banditNarm_lapse").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Seymour, Daw, Roiser, Dayan, & Dolan (2012). Serotonin Selectively Modulates Reward Value in Human Decision-Making. J Neuro, 32(17), 5833-5842.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- banditNarm_lapse(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- banditNarm_lapse(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

5 Parameter Model, without C (choice perseveration) but with xi (noise). Added decay rate (Niv et al., 2015, J. Neuro).

Description

Hierarchical Bayesian Modeling of the N-Armed Bandit Task using 5 Parameter Model, without C (choice perseveration) but with xi (noise). Added decay rate (Niv et al., 2015, J. Neuro).. It has the following parameters: Arew (reward learning rate), Apun (punishment learning rate), R (reward sensitivity), P (punishment sensitivity), xi (noise), d (decay rate).

• Task: N-Armed Bandit Task

• Model: 5 Parameter Model, without C (choice perseveration) but with xi (noise). Added decay rate (Niv et al., 2015, J. Neuro). (Aylward et al., 2018)

Usage

banditNarm_lapse_decay(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the N-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, ... N.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Cheol Jun Cho <cjfwndnsl@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"banditNarm_lapse_decay").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Aylward, Valton, Ahn, Bond, Dayan, Roiser, & Robinson (2018) Altered decision-making under uncertainty in unmedicated mood and anxiety disorders. PsyArxiv. 10.31234/osf.io/k5b8m

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- banditNarm_lapse_decay(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- banditNarm_lapse_decay(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

4 Parameter Model, without C (choice perseveration) but with xi (noise). Single learning rate both for R and P.

Description

Hierarchical Bayesian Modeling of the N-Armed Bandit Task using 4 Parameter Model, without C (choice perseveration) but with xi (noise). Single learning rate both for R and P.. It has the following parameters: A (learning rate), R (reward sensitivity), P (punishment sensitivity), xi (noise).

• Task: N-Armed Bandit Task

• Model: 4 Parameter Model, without C (choice perseveration) but with xi (noise). Single learning rate both for R and P. (Aylward et al., 2018)

Usage

banditNarm_singleA_lapse(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the N-Armed Bandit Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer value representing the option chosen on the given trial: 1, 2, 3, ... N.

gain

Floating point value representing the amount of currency won on the given trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on the given trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Cheol Jun Cho <cjfwndnsl@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"banditNarm_singleA_lapse").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Aylward, Valton, Ahn, Bond, Dayan, Roiser, & Robinson (2018) Altered decision-making under uncertainty in unmedicated mood and anxiety disorders. PsyArxiv. 10.31234/osf.io/k5b8m

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- banditNarm_singleA_lapse(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- banditNarm_singleA_lapse(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Exponential-Weight Mean-Variance Model

Description

Hierarchical Bayesian Modeling of the Balloon Analogue Risk Task using Exponential-Weight Mean-Variance Model. It has the following parameters: phi (prior belief of burst), eta (updating exponent), rho (risk preference), tau (inverse temperature), lambda (loss aversion).

• Task: Balloon Analogue Risk Task

• Model: Exponential-Weight Mean-Variance Model (Park et al., 2020)

Usage

bart_ewmv(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Balloon Analogue Risk Task, there should be 3 columns of data with the labels "subjID", "pumps", "explosion". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

pumps

The number of pumps.

explosion

0: intact, 1: burst

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Harhim Park <hrpark12@gmail.com>, Jaeyeong Yang <jaeyeong.yang1125@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"bart_ewmv").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Park, H., Yang, J., Vassileva, J., & Ahn, W. (2020). The Exponential-Weight Mean-Variance Model: A novel computational model for the Balloon Analogue Risk Task. https://doi.org/10.31234/osf.io/sdzj4

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- bart_ewmv(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- bart_ewmv(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Re-parameterized version of BART model with 4 parameters

Description

Hierarchical Bayesian Modeling of the Balloon Analogue Risk Task using Re-parameterized version of BART model with 4 parameters. It has the following parameters: phi (prior belief of balloon not bursting), eta (updating rate), gam (risk-taking parameter), tau (inverse temperature).

• Task: Balloon Analogue Risk Task

• Model: Re-parameterized version of BART model with 4 parameters (van Ravenzwaaij et al., 2011)

Usage

bart_par4(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Balloon Analogue Risk Task, there should be 3 columns of data with the labels "subjID", "pumps", "explosion". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

pumps

The number of pumps.

explosion

0: intact, 1: burst

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Harhim Park <hrpark12@gmail.com>, Jaeyeong Yang <jaeyeong.yang1125@gmail.com>, Ayoung Lee <aylee2008@naver.com>, Jeongbin Oh <ows0104@gmail.com>, Jiyoon Lee <nicole.lee2001@gmail.com>, Junha Jang <andy627robo@naver.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"bart_par4").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

van Ravenzwaaij, D., Dutilh, G., & Wagenmakers, E. J. (2011). Cognitive model decomposition of the BART: Assessment and application. Journal of Mathematical Psychology, 55(1), 94-105.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- bart_par4(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- bart_par4(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Cumulative Model

Description

Hierarchical Bayesian Modeling of the Cambridge Gambling Task using Cumulative Model. It has the following parameters: alpha (probability distortion), c (color bias), rho (relative loss sensitivity), beta (discounting rate), gamma (choice sensitivity).

• Task: Cambridge Gambling Task (Rogers et al., 1999)

• Model: Cumulative Model

Usage

cgt_cm(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Cambridge Gambling Task, there should be 7 columns of data with the labels "subjID", "gamble_type", "percentage_staked", "trial_initial_points", "assessment_stage", "red_chosen", "n_red_boxes". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

gamble_type

Integer value representng whether the bets on the current trial were presented in descending (0) or ascending (1) order.

percentage_staked

Integer value representing the bet percentage (not proportion) selected on the current trial: 5, 25, 50, 75, or 95.

trial_initial_points

Floating point value representing the number of points that the subject has at the start of the current trial (e.g., 100, 150, etc.).

assessment_stage

Integer value representing whether the current trial is a practice trial (0) or a test trial (1). Only test trials are used for model fitting.

red_chosen

Integer value representing whether the red color was chosen (1) versus the blue color (0).

n_red_boxes

Integer value representing the number of red boxes shown on the current trial: 1, 2, 3,..., or 9.

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Nathaniel Haines <haines.175@osu.edu>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"cgt_cm").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Rogers, R. D., Everitt, B. J., Baldacchino, A., Blackshaw, A. J., Swainson, R., Wynne, K., Baker, N. B., Hunter, J., Carthy, T., London, M., Deakin, J. F. W., Sahakian, B. J., Robbins, T. W. (1999). Dissociable deficits in the decision-making cognition of chronic amphetamine abusers, opiate abusers, patients with focal damage to prefrontal cortex, and tryptophan-depleted normal volunteers: evidence for monoaminergic mechanisms. Neuropsychopharmacology, 20, 322–339.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- cgt_cm(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- cgt_cm(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Drift Diffusion Model

Description

Hierarchical Bayesian Modeling of the Choice Reaction Time Task using Drift Diffusion Model. It has the following parameters: alpha (boundary separation), beta (bias), delta (drift rate), tau (non-decision time).

• Task: Choice Reaction Time Task

• Model: Drift Diffusion Model (Ratcliff, 1978)

Usage

choiceRT_ddm(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Choice Reaction Time Task, there should be 3 columns of data with the labels "subjID", "choice", "RT". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Choice made for the current trial, coded as 1/2 to indicate lower/upper boundary or left/right choices (e.g., 1 1 1 2 1 2).

RT

Choice reaction time for the current trial, in **seconds** (e.g., 0.435 0.383 0.314 0.309, etc.).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"choiceRT_ddm").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Ratcliff, R. (1978). A theory of memory retrieval. Psychological Review, 85(2), 59-108. https://doi.org/10.1037/0033-295X.85.2.59

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- choiceRT_ddm(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- choiceRT_ddm(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Drift Diffusion Model

Description

Individual Bayesian Modeling of the Choice Reaction Time Task using Drift Diffusion Model. It has the following parameters: alpha (boundary separation), beta (bias), delta (drift rate), tau (non-decision time).

• Task: Choice Reaction Time Task

• Model: Drift Diffusion Model (Ratcliff, 1978)

Usage

choiceRT_ddm_single(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Choice Reaction Time Task, there should be 3 columns of data with the labels "subjID", "choice", "RT". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Choice made for the current trial, coded as 1/2 to indicate lower/upper boundary or left/right choices (e.g., 1 1 1 2 1 2).

RT

Choice reaction time for the current trial, in **seconds** (e.g., 0.435 0.383 0.314 0.309, etc.).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"choiceRT_ddm_single").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Ratcliff, R. (1978). A theory of memory retrieval. Psychological Review, 85(2), 59-108. https://doi.org/10.1037/0033-295X.85.2.59

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- choiceRT_ddm_single(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- choiceRT_ddm_single(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Choice Reaction Time task, linear ballistic accumulator modeling

Description

Hierarchical Bayesian Modeling of choice/reaction time data with the following parameters: "d" (boundary), "A" (upper boundary of starting point), "v" (drift rate), "tau" (non-decision time). The model published in Annis, J., Miller, B. J., & Palmeri, T. J. (2016). Bayesian inference with Stan: A tutorial on adding custom distributions. Behavior research methods, 1-24.

MODEL: Brown and Heathcote LBA model - multiple subjects. Note that this implementation estimates a different drift rate for each condition-choice pair. For example, if the task involves deciding between two stimuli on each trial, and there are two different conditions throughout the task (e.g. speed versus accuracy), a total of 4 (2 stimuli by 2 conditions) drift rates will be estimated. For details on implementation, see Annis et al. (2016).

Usage

choiceRT_lba(
  data = "choose",
  niter = 3000,
  nwarmup = 1000,
  nchain = 2,
  ncore = 2,
  nthin = 1,
  inits = "random",
  indPars = "mean",
  saveDir = NULL,
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name of the file, including the file extension (e.g. ".txt"), that contains the behavioral data for the subject of interest for the current analysis. The file should be a tab-delimited text (.txt) file whose rows represent trial-by-trial observations and columns represent variables. For choice/reaction time tasks, there should be four columns of data with the labels "subjID", "choice", "RT", and "condition". It is not necessary for the columns to be in this particular order, however it is necessary that they be labelled correctly and contain the information below:

"subjID"

A unique identifier for each subject within data-set to be analyzed.

"choice"

An integer representing the choice made on the current trial. (e.g., 1 1 3 2 1 2).

"RT"

A floating number the choice reaction time in seconds. (e.g., 0.435 0.383 0.314 0.309, etc.).

"condition"

An integer representing the condition of the current trail (e.g., 1 2 3 4).

*Note: The data.txt file may contain other columns of data (e.g. "Reaction_Time", "trial_number", etc.), but only the data with the column names listed above will be used for analysis/modeling. As long as the columns above are present and labelled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this value is equivalent to a burn-in sample. Due to the nature of MCMC sampling, initial values (where the sampling chain begins) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a representative posterior is attained. When sampling is completed, the multiple chains may be checked for convergence with the plot(myModel, type = "trace") command. The chains should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC samples being chosen to generate the posterior distributions. By default, nthin is equal to 1, hence every sample is used to generate the posterior.

Contol Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. The Stan creators recommend that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to Hoffman & Gelman (2014, Journal of Machine Learning Research) for more information on the functioning of the sampler control parameters. One can also refer to section 58.2 of the Stan User's Manual for a less technical description of these arguments.

Value

modelData A class 'hBayesDM' object with the following components:

model

Character string with the name of the model ("choiceRT_lba").

allIndPars

'data.frame' containing the summarized parameter values (as specified by 'indPars') for each subject.

parVals

A 'list' where each element contains posterior samples over different model parameters.

fit

A class 'stanfit' object containing the fitted model.

rawdata

"data.frame" containing the raw data used to fit the model, as specified by the user.

References

Brown, S. D., & Heathcote, A. (2008). The simplest complete model of choice response time: Linear ballistic accumulation. Cognitive Psychology, 57(3), 153-178. http://doi.org/10.1016/j.cogpsych.2007.12.002

Annis, J., Miller, B. J., & Palmeri, T. J. (2016). Bayesian inference with Stan: A tutorial on adding custom distributions. Behavior research methods, 1-24.

Hoffman, M. D., & Gelman, A. (2014). The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. The Journal of Machine Learning Research, 15(1), 1593-1623.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model and store results in "output"
output <- choiceRT_lba(data = "example", niter = 2000, nwarmup = 1000, nchain = 3, ncore = 3)

# Visually check convergence of the sampling chains (should like like 'hairy caterpillars')
plot(output, type = 'trace')

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Choice Reaction Time task, linear ballistic accumulator modeling

Description

Individual Bayesian Modeling of choice/reaction time data with the following parameters: "d" (boundary), "A" (upper boundary of starting point), "v" (drift rate), "tau" (non-decision time). The model published in Annis, J., Miller, B. J., & Palmeri, T. J. (2016). Bayesian inference with Stan: A tutorial on adding custom distributions. Behavior research methods, 1-24.

MODEL: Brown and Heathcote LBA model - single subject. Note that this implementation estimates a different drift rate for each condition-choice pair. For example, if the task involves deciding between two stimuli on each trial, and there are two different conditions throughout the task (e.g. speed versus accuracy), a total of 4 (2 stimuli by 2 conditions) drift rates will be estimated. For details on implementation, see Annis et al. (2016).

Usage

choiceRT_lba_single(
  data = "choose",
  niter = 3000,
  nwarmup = 1000,
  nchain = 2,
  ncore = 2,
  nthin = 1,
  inits = "random",
  indPars = "mean",
  saveDir = NULL,
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name of the file, including the file extension (e.g. ".txt"), that contains the behavioral data of all subjects of interest for the current analysis. The file should be a tab-delimited text (.txt) file whose rows represent trial-by-trial observations and columns represent variables. For choice/reaction time tasks, there should be four columns of data with the labels "choice", "RT", and "condition". It is not necessary for the columns to be in this particular order, however it is necessary that they be labelled correctly and contain the information below:

"subjID"

A unique identifier for each subject within data-set to be analyzed.

"choice"

An integer representing the choice made on the current trial. (e.g., 1 1 3 2 1 2).

"RT"

A floating number the choice reaction time in seconds. (e.g., 0.435 0.383 0.314 0.309, etc.).

"condition"

An integer representing the condition of the current trail (e.g., 1 2 3 4).

*Note: The data.txt file may contain other columns of data (e.g. "Reaction_Time", "trial_number", etc.), but only the data with the column names listed above will be used for analysis/modeling. As long as the columns above are present and labelled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this value is equivalent to a burn-in sample. Due to the nature of MCMC sampling, initial values (where the sampling chain begins) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a representative posterior is attained. When sampling is completed, the multiple chains may be checked for convergence with the plot(myModel, type = "trace") command. The chains should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC samples being chosen to generate the posterior distributions. By default, nthin is equal to 1, hence every sample is used to generate the posterior.

Contol Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. The Stan creators recommend that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to Hoffman & Gelman (2014, Journal of Machine Learning Research) for more information on the functioning of the sampler control parameters. One can also refer to section 58.2 of the Stan User's Manual for a less technical description of these arguments.

Value

modelData A class 'hBayesDM' object with the following components:

model

Character string with the name of the model ("choiceRT_lba_single").

allIndPars

'data.frame' containing the summarized parameter values (as specified by 'indPars') for each subject.

parVals

A 'list' where each element contains posterior samples over different model parameters.

fit

A class 'stanfit' object containing the fitted model.

rawdata

"data.frame" containing the raw data used to fit the model, as specified by the user.

References

Brown, S. D., & Heathcote, A. (2008). The simplest complete model of choice response time: Linear ballistic accumulation. Cognitive Psychology, 57(3), 153-178. http://doi.org/10.1016/j.cogpsych.2007.12.002

Annis, J., Miller, B. J., & Palmeri, T. J. (2016). Bayesian inference with Stan: A tutorial on adding custom distributions. Behavior research methods, 1-24.

Hoffman, M. D., & Gelman, A. (2014). The No-U-turn sampler: adaptively setting path lengths in Hamiltonian Monte Carlo. The Journal of Machine Learning Research, 15(1), 1593-1623.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model and store results in "output"
output <- choiceRT_lba_single(data = "example", niter = 2000, nwarmup = 1000, nchain = 3, ncore = 3)

# Visually check convergence of the sampling chains (should like like 'hairy caterpillars')
plot(output, type = 'trace')

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Exponential Subjective Value Model

Description

Hierarchical Bayesian Modeling of the Choice Under Risk and Ambiguity Task using Exponential Subjective Value Model. It has the following parameters: alpha (risk attitude), beta (ambiguity attitude), gamma (inverse temperature).

• Task: Choice Under Risk and Ambiguity Task

• Model: Exponential Subjective Value Model (Hsu et al., 2005)

Usage

cra_exp(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Choice Under Risk and Ambiguity Task, there should be 6 columns of data with the labels "subjID", "prob", "ambig", "reward_var", "reward_fix", "choice". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

prob

Objective probability of the variable lottery.

ambig

Ambiguity level of the variable lottery (0 for risky lottery; greater than 0 for ambiguous lottery).

reward_var

Amount of reward in variable lottery. Assumed to be greater than zero.

reward_fix

Amount of reward in fixed lottery. Assumed to be greater than zero.

choice

If the variable lottery was selected, choice == 1; otherwise choice == 0.

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Jaeyeong Yang <jaeyeong.yang1125@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"cra_exp").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Hsu, M., Bhatt, M., Adolphs, R., Tranel, D., & Camerer, C. F. (2005). Neural systems responding to degrees of uncertainty in human decision-making. Science, 310(5754), 1680-1683. https://doi.org/10.1126/science.1115327

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- cra_exp(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- cra_exp(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Linear Subjective Value Model

Description

Hierarchical Bayesian Modeling of the Choice Under Risk and Ambiguity Task using Linear Subjective Value Model. It has the following parameters: alpha (risk attitude), beta (ambiguity attitude), gamma (inverse temperature).

• Task: Choice Under Risk and Ambiguity Task

• Model: Linear Subjective Value Model (Levy et al., 2010)

Usage

cra_linear(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Choice Under Risk and Ambiguity Task, there should be 6 columns of data with the labels "subjID", "prob", "ambig", "reward_var", "reward_fix", "choice". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

prob

Objective probability of the variable lottery.

ambig

Ambiguity level of the variable lottery (0 for risky lottery; greater than 0 for ambiguous lottery).

reward_var

Amount of reward in variable lottery. Assumed to be greater than zero.

reward_fix

Amount of reward in fixed lottery. Assumed to be greater than zero.

choice

If the variable lottery was selected, choice == 1; otherwise choice == 0.

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Jaeyeong Yang <jaeyeong.yang1125@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"cra_linear").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Levy, I., Snell, J., Nelson, A. J., Rustichini, A., & Glimcher, P. W. (2010). Neural representation of subjective value under risk and ambiguity. Journal of Neurophysiology, 103(2), 1036-1047.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- cra_linear(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- cra_linear(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Probability Weight Function

Description

Hierarchical Bayesian Modeling of the Description Based Decison Making Task using Probability Weight Function. It has the following parameters: tau (probability weight function), rho (subject utility function), lambda (loss aversion parameter), beta (inverse softmax temperature).

• Task: Description Based Decison Making Task

• Model: Probability Weight Function (Erev et al., 2010; Hertwig et al., 2004; Jessup et al., 2008)

Usage

dbdm_prob_weight(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Description Based Decison Making Task, there should be 8 columns of data with the labels "subjID", "opt1hprob", "opt2hprob", "opt1hval", "opt1lval", "opt2hval", "opt2lval", "choice". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

opt1hprob

Possiblity of getting higher value of outcome(opt1hval) when choosing option 1.

opt2hprob

Possiblity of getting higher value of outcome(opt2hval) when choosing option 2.

opt1hval

Possible (with opt1hprob probability) outcome of option 1.

opt1lval

Possible (with (1 - opt1hprob) probability) outcome of option 1.

opt2hval

Possible (with opt2hprob probability) outcome of option 2.

opt2lval

Possible (with (1 - opt2hprob) probability) outcome of option 2.

choice

If option 1 was selected, choice == 1; else if option 2 was selected, choice == 2.

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Yoonseo Zoh <zohyos7@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"dbdm_prob_weight").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Erev, I., Ert, E., Roth, A. E., Haruvy, E., Herzog, S. M., Hau, R., ... & Lebiere, C. (2010). A choice prediction competition: Choices from experience and from description. Journal of Behavioral Decision Making, 23(1), 15-47.

Hertwig, R., Barron, G., Weber, E. U., & Erev, I. (2004). Decisions from experience and the effect of rare events in risky choice. Psychological science, 15(8), 534-539.

Jessup, R. K., Bishara, A. J., & Busemeyer, J. R. (2008). Feedback produces divergence from prospect theory in descriptive choice. Psychological Science, 19(10), 1015-1022.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- dbdm_prob_weight(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- dbdm_prob_weight(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Constant-Sensitivity (CS) Model

Description

Hierarchical Bayesian Modeling of the Delay Discounting Task using Constant-Sensitivity (CS) Model. It has the following parameters: r (exponential discounting rate), s (impatience), beta (inverse temperature).

• Task: Delay Discounting Task

• Model: Constant-Sensitivity (CS) Model (Ebert et al., 2007)

Usage

dd_cs(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Delay Discounting Task, there should be 6 columns of data with the labels "subjID", "delay_later", "amount_later", "delay_sooner", "amount_sooner", "choice". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

delay_later

An integer representing the delayed days for the later option (e.g. 1, 6, 28).

amount_later

A floating point number representing the amount for the later option (e.g. 10.5, 13.4, 30.9).

delay_sooner

An integer representing the delayed days for the sooner option (e.g. 0).

amount_sooner

A floating point number representing the amount for the sooner option (e.g. 10).

choice

If amount_later was selected, choice == 1; else if amount_sooner was selected, choice == 0.

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"dd_cs").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Ebert, J. E. J., & Prelec, D. (2007). The Fragility of Time: Time-Insensitivity and Valuation of the Near and Far Future. Management Science. https://doi.org/10.1287/mnsc.1060.0671

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- dd_cs(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- dd_cs(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Constant-Sensitivity (CS) Model

Description

Individual Bayesian Modeling of the Delay Discounting Task using Constant-Sensitivity (CS) Model. It has the following parameters: r (exponential discounting rate), s (impatience), beta (inverse temperature).

• Task: Delay Discounting Task

• Model: Constant-Sensitivity (CS) Model (Ebert et al., 2007)

Usage

dd_cs_single(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Delay Discounting Task, there should be 6 columns of data with the labels "subjID", "delay_later", "amount_later", "delay_sooner", "amount_sooner", "choice". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

delay_later

An integer representing the delayed days for the later option (e.g. 1, 6, 28).

amount_later

A floating point number representing the amount for the later option (e.g. 10.5, 13.4, 30.9).

delay_sooner

An integer representing the delayed days for the sooner option (e.g. 0).

amount_sooner

A floating point number representing the amount for the sooner option (e.g. 10).

choice

If amount_later was selected, choice == 1; else if amount_sooner was selected, choice == 0.

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"dd_cs_single").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Ebert, J. E. J., & Prelec, D. (2007). The Fragility of Time: Time-Insensitivity and Valuation of the Near and Far Future. Management Science. https://doi.org/10.1287/mnsc.1060.0671

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- dd_cs_single(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- dd_cs_single(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Exponential Model

Description

Hierarchical Bayesian Modeling of the Delay Discounting Task using Exponential Model. It has the following parameters: r (exponential discounting rate), beta (inverse temperature).

• Task: Delay Discounting Task

• Model: Exponential Model (Samuelson, 1937)

Usage

dd_exp(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Delay Discounting Task, there should be 6 columns of data with the labels "subjID", "delay_later", "amount_later", "delay_sooner", "amount_sooner", "choice". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

delay_later

An integer representing the delayed days for the later option (e.g. 1, 6, 28).

amount_later

A floating point number representing the amount for the later option (e.g. 10.5, 13.4, 30.9).

delay_sooner

An integer representing the delayed days for the sooner option (e.g. 0).

amount_sooner

A floating point number representing the amount for the sooner option (e.g. 10).

choice

If amount_later was selected, choice == 1; else if amount_sooner was selected, choice == 0.

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"dd_exp").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Samuelson, P. A. (1937). A Note on Measurement of Utility. The Review of Economic Studies, 4(2), 155. https://doi.org/10.2307/2967612

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- dd_exp(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- dd_exp(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Hyperbolic Model

Description

Hierarchical Bayesian Modeling of the Delay Discounting Task using Hyperbolic Model. It has the following parameters: k (discounting rate), beta (inverse temperature).

• Task: Delay Discounting Task

• Model: Hyperbolic Model (Mazur, 1987)

Usage

dd_hyperbolic(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Delay Discounting Task, there should be 6 columns of data with the labels "subjID", "delay_later", "amount_later", "delay_sooner", "amount_sooner", "choice". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

delay_later

An integer representing the delayed days for the later option (e.g. 1, 6, 28).

amount_later

A floating point number representing the amount for the later option (e.g. 10.5, 13.4, 30.9).

delay_sooner

An integer representing the delayed days for the sooner option (e.g. 0).

amount_sooner

A floating point number representing the amount for the sooner option (e.g. 10).

choice

If amount_later was selected, choice == 1; else if amount_sooner was selected, choice == 0.

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"dd_hyperbolic").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Mazur, J. E. (1987). An adjustment procedure for studying delayed reinforcement.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- dd_hyperbolic(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- dd_hyperbolic(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Hyperbolic Model

Description

Individual Bayesian Modeling of the Delay Discounting Task using Hyperbolic Model. It has the following parameters: k (discounting rate), beta (inverse temperature).

• Task: Delay Discounting Task

• Model: Hyperbolic Model (Mazur, 1987)

Usage

dd_hyperbolic_single(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Delay Discounting Task, there should be 6 columns of data with the labels "subjID", "delay_later", "amount_later", "delay_sooner", "amount_sooner", "choice". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

delay_later

An integer representing the delayed days for the later option (e.g. 1, 6, 28).

amount_later

A floating point number representing the amount for the later option (e.g. 10.5, 13.4, 30.9).

delay_sooner

An integer representing the delayed days for the sooner option (e.g. 0).

amount_sooner

A floating point number representing the amount for the sooner option (e.g. 10).

choice

If amount_later was selected, choice == 1; else if amount_sooner was selected, choice == 0.

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"dd_hyperbolic_single").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Mazur, J. E. (1987). An adjustment procedure for studying delayed reinforcement.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- dd_hyperbolic_single(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- dd_hyperbolic_single(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Function to estimate mode of MCMC samples

Description

Based on codes from 'http://stackoverflow.com/questions/2547402/is-there-a-built-in-function-for-finding-the-mode' see the comment by Rasmus Baath

Usage

estimate_mode(x)

Arguments

Extract Model Comparison Estimates

Description

Extract Model Comparison Estimates

Usage

extract_ic(model_data = NULL, ic = "looic", ncore = 2)

Arguments

Value

IC Leave-One-Out and/or Watanabe-Akaike information criterion estimates.

Examples

## Not run: 
library(hBayesDM)
output = bandit2arm_delta("example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 1)
# To show the LOOIC model fit estimates (a detailed report; c)
extract_ic(output)
# To show the WAIC model fit estimates
extract_ic(output, ic = "waic")

## End(Not run)

RW + noise

Description

Hierarchical Bayesian Modeling of the Orthogonalized Go/Nogo Task using RW + noise. It has the following parameters: xi (noise), ep (learning rate), rho (effective size).

• Task: Orthogonalized Go/Nogo Task

• Model: RW + noise (Guitart-Masip et al., 2012)

Usage

gng_m1(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Orthogonalized Go/Nogo Task, there should be 4 columns of data with the labels "subjID", "cue", "keyPressed", "outcome". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

cue

Nominal integer representing the cue shown for that trial: 1, 2, 3, or 4.

keyPressed

Binary value representing the subject's response for that trial (where Press == 1; No press == 0).

outcome

Ternary value representing the outcome of that trial (where Positive feedback == 1; Neutral feedback == 0; Negative feedback == -1).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"gng_m1").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Guitart-Masip, M., Huys, Q. J. M., Fuentemilla, L., Dayan, P., Duzel, E., & Dolan, R. J. (2012). Go and no-go learning in reward and punishment: Interactions between affect and effect. Neuroimage, 62(1), 154-166. https://doi.org/10.1016/j.neuroimage.2012.04.024

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- gng_m1(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- gng_m1(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

RW + noise + bias

Description

Hierarchical Bayesian Modeling of the Orthogonalized Go/Nogo Task using RW + noise + bias. It has the following parameters: xi (noise), ep (learning rate), b (action bias), rho (effective size).

• Task: Orthogonalized Go/Nogo Task

• Model: RW + noise + bias (Guitart-Masip et al., 2012)

Usage

gng_m2(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Orthogonalized Go/Nogo Task, there should be 4 columns of data with the labels "subjID", "cue", "keyPressed", "outcome". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

cue

Nominal integer representing the cue shown for that trial: 1, 2, 3, or 4.

keyPressed

Binary value representing the subject's response for that trial (where Press == 1; No press == 0).

outcome

Ternary value representing the outcome of that trial (where Positive feedback == 1; Neutral feedback == 0; Negative feedback == -1).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"gng_m2").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Guitart-Masip, M., Huys, Q. J. M., Fuentemilla, L., Dayan, P., Duzel, E., & Dolan, R. J. (2012). Go and no-go learning in reward and punishment: Interactions between affect and effect. Neuroimage, 62(1), 154-166. https://doi.org/10.1016/j.neuroimage.2012.04.024

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- gng_m2(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- gng_m2(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

RW + noise + bias + pi

Description

Hierarchical Bayesian Modeling of the Orthogonalized Go/Nogo Task using RW + noise + bias + pi. It has the following parameters: xi (noise), ep (learning rate), b (action bias), pi (Pavlovian bias), rho (effective size).

• Task: Orthogonalized Go/Nogo Task

• Model: RW + noise + bias + pi (Guitart-Masip et al., 2012)

Usage

gng_m3(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Orthogonalized Go/Nogo Task, there should be 4 columns of data with the labels "subjID", "cue", "keyPressed", "outcome". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

cue

Nominal integer representing the cue shown for that trial: 1, 2, 3, or 4.

keyPressed

Binary value representing the subject's response for that trial (where Press == 1; No press == 0).

outcome

Ternary value representing the outcome of that trial (where Positive feedback == 1; Neutral feedback == 0; Negative feedback == -1).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"gng_m3").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Guitart-Masip, M., Huys, Q. J. M., Fuentemilla, L., Dayan, P., Duzel, E., & Dolan, R. J. (2012). Go and no-go learning in reward and punishment: Interactions between affect and effect. Neuroimage, 62(1), 154-166. https://doi.org/10.1016/j.neuroimage.2012.04.024

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- gng_m3(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- gng_m3(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

RW (rew/pun) + noise + bias + pi

Description

Hierarchical Bayesian Modeling of the Orthogonalized Go/Nogo Task using RW (rew/pun) + noise + bias + pi. It has the following parameters: xi (noise), ep (learning rate), b (action bias), pi (Pavlovian bias), rhoRew (reward sensitivity), rhoPun (punishment sensitivity).

• Task: Orthogonalized Go/Nogo Task

• Model: RW (rew/pun) + noise + bias + pi (Cavanagh et al., 2013)

Usage

gng_m4(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Orthogonalized Go/Nogo Task, there should be 4 columns of data with the labels "subjID", "cue", "keyPressed", "outcome". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

cue

Nominal integer representing the cue shown for that trial: 1, 2, 3, or 4.

keyPressed

Binary value representing the subject's response for that trial (where Press == 1; No press == 0).

outcome

Ternary value representing the outcome of that trial (where Positive feedback == 1; Neutral feedback == 0; Negative feedback == -1).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"gng_m4").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Cavanagh, J. F., Eisenberg, I., Guitart-Masip, M., Huys, Q., & Frank, M. J. (2013). Frontal Theta Overrides Pavlovian Learning Biases. Journal of Neuroscience, 33(19), 8541-8548. https://doi.org/10.1523/JNEUROSCI.5754-12.2013

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- gng_m4(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- gng_m4(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

hBayesDM Model Base Function

Description

The base function from which all hBayesDM model functions are created.

Contributor: Jethro Lee

Usage

hBayesDM_model(
  task_name,
  model_name,
  model_type = "",
  data_columns,
  parameters,
  regressors = NULL,
  postpreds = "y_pred",
  stanmodel_arg = NULL,
  preprocess_func
)

Arguments

Details

task_name: Typically same task models share the same data column requirements.

model_name: Typically different models are distinguished by their different list of parameters.

model_type is one of the following three:

""

Modeling of multiple subjects. (Default hierarchical Bayesian analysis.)

"single"

Modeling of a single subject.

"multipleB"

Modeling of multiple subjects, where multiple blocks exist within each subject.

data_columns must be the entirety of necessary data columns used at some point in the R or Stan code. I.e. "subjID" must always be included. In the case of 'multipleB' type models, "block" should also be included as well.

parameters is a list object, whose keys are the parameters of this model. Each parameter key must be assigned a numeric vector holding 3 elements: the parameter's lower bound, plausible value, and upper bound.

regressors is a list object, whose keys are the model-based regressors of this model. Each regressor key must be assigned a numeric value indicating the number of dimensions its data will be extracted as. If model-based regressors are not available for this model, this argument should just be NULL.

postpreds defaults to "y_pred", but any other character vector holding appropriate names is possible (c.f. Two-Step Task models). If posterior predictions are not yet available for this model, this argument should just be NULL.

stanmodel_arg can be used by developers, during the developmental stage of creating a new model function. If this argument is passed a character value, the Stan file with the corresponding name will be used for model fitting. If this argument is passed a stanmodel object, that stanmodel object will be used for model fitting. When creation of the model function is complete, this argument should just be left as NULL.

preprocess_func is the part of the code that is specific to the model, and is thus written in the specific model R file.
Arguments for this function are:

raw_data

A data.table that holds the raw user data, which was read by using fread.

general_info

A list that holds the general informations about the raw data, i.e. subjs, n_subj, t_subjs, t_max, b_subjs, b_max.

...

Optional additional argument(s) that specific model functions may want to include. Examples of such additional arguments currently being used in hBayesDM models are: RTbound (choiceRT_ddm models), payscale (igt models), and trans_prob (ts models).

Return value for this function should be:

data_list

A list with appropriately named keys (as required by the model Stan file), holding the fully preprocessed user data.

NOTE: Syntax for data.table slightly differs from that of data.frame. If you want to use raw_data as a data.frame when writing the preprocess_func, simply begin with the line: raw_data <- as.data.frame(raw_data).
NOTE: Because of allowing case & underscore insensitive column names in user data, raw_data columns must now be referenced by their lowercase non-underscored versions, e.g. "subjid", within the code of the preprocess function.

Value

A specific hBayesDM model function.

Outcome-Representation Learning Model

Description

Hierarchical Bayesian Modeling of the Iowa Gambling Task using Outcome-Representation Learning Model. It has the following parameters: Arew (reward learning rate), Apun (punishment learning rate), K (perseverance decay), betaF (outcome frequency weight), betaP (perseverance weight).

• Task: Iowa Gambling Task (Ahn et al., 2008)

• Model: Outcome-Representation Learning Model (Haines et al., 2018)

Usage

igt_orl(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Iowa Gambling Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer indicating which deck was chosen on that trial (where A==1, B==2, C==3, and D==4).

gain

Floating point value representing the amount of currency won on that trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on that trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Nate Haines <haines.175@osu.edu>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"igt_orl").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Ahn, W. Y., Busemeyer, J. R., & Wagenmakers, E. J. (2008). Comparison of decision learning models using the generalization criterion method. Cognitive Science, 32(8), 1376-1402. https://doi.org/10.1080/03640210802352992

Haines, N., Vassileva, J., & Ahn, W.-Y. (2018). The Outcome-Representation Learning Model: A Novel Reinforcement Learning Model of the Iowa Gambling Task. Cognitive Science. https://doi.org/10.1111/cogs.12688

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- igt_orl(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- igt_orl(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Prospect Valence Learning (PVL) Decay-RI

Description

Hierarchical Bayesian Modeling of the Iowa Gambling Task using Prospect Valence Learning (PVL) Decay-RI. It has the following parameters: A (decay rate), alpha (outcome sensitivity), cons (response consistency), lambda (loss aversion).

• Task: Iowa Gambling Task (Ahn et al., 2008)

• Model: Prospect Valence Learning (PVL) Decay-RI (Ahn et al., 2014)

Usage

igt_pvl_decay(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Iowa Gambling Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer indicating which deck was chosen on that trial (where A==1, B==2, C==3, and D==4).

gain

Floating point value representing the amount of currency won on that trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on that trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"igt_pvl_decay").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Ahn, W. Y., Busemeyer, J. R., & Wagenmakers, E. J. (2008). Comparison of decision learning models using the generalization criterion method. Cognitive Science, 32(8), 1376-1402. https://doi.org/10.1080/03640210802352992

Ahn, W.-Y., Vasilev, G., Lee, S.-H., Busemeyer, J. R., Kruschke, J. K., Bechara, A., & Vassileva, J. (2014). Decision-making in stimulant and opiate addicts in protracted abstinence: evidence from computational modeling with pure users. Frontiers in Psychology, 5, 1376. https://doi.org/10.3389/fpsyg.2014.00849

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- igt_pvl_decay(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- igt_pvl_decay(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Prospect Valence Learning (PVL) Delta

Description

Hierarchical Bayesian Modeling of the Iowa Gambling Task using Prospect Valence Learning (PVL) Delta. It has the following parameters: A (learning rate), alpha (outcome sensitivity), cons (response consistency), lambda (loss aversion).

• Task: Iowa Gambling Task (Ahn et al., 2008)

• Model: Prospect Valence Learning (PVL) Delta (Ahn et al., 2008)

Usage

igt_pvl_delta(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Iowa Gambling Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer indicating which deck was chosen on that trial (where A==1, B==2, C==3, and D==4).

gain

Floating point value representing the amount of currency won on that trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on that trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"igt_pvl_delta").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Ahn, W. Y., Busemeyer, J. R., & Wagenmakers, E. J. (2008). Comparison of decision learning models using the generalization criterion method. Cognitive Science, 32(8), 1376-1402. https://doi.org/10.1080/03640210802352992

Ahn, W. Y., Busemeyer, J. R., & Wagenmakers, E. J. (2008). Comparison of decision learning models using the generalization criterion method. Cognitive Science, 32(8), 1376-1402. https://doi.org/10.1080/03640210802352992

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- igt_pvl_delta(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- igt_pvl_delta(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Value-Plus-Perseverance

Description

Hierarchical Bayesian Modeling of the Iowa Gambling Task using Value-Plus-Perseverance. It has the following parameters: A (learning rate), alpha (outcome sensitivity), cons (response consistency), lambda (loss aversion), epP (gain impact), epN (loss impact), K (decay rate), w (RL weight).

• Task: Iowa Gambling Task (Ahn et al., 2008)

• Model: Value-Plus-Perseverance (Worthy et al., 2013)

Usage

igt_vpp(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Iowa Gambling Task, there should be 4 columns of data with the labels "subjID", "choice", "gain", "loss". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

choice

Integer indicating which deck was chosen on that trial (where A==1, B==2, C==3, and D==4).

gain

Floating point value representing the amount of currency won on that trial (e.g. 50, 100).

loss

Floating point value representing the amount of currency lost on that trial (e.g. 0, -50).

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"igt_vpp").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Ahn, W. Y., Busemeyer, J. R., & Wagenmakers, E. J. (2008). Comparison of decision learning models using the generalization criterion method. Cognitive Science, 32(8), 1376-1402. https://doi.org/10.1080/03640210802352992

Worthy, D. A., & Todd Maddox, W. (2013). A comparison model of reinforcement-learning and win-stay-lose-shift decision-making processes: A tribute to W.K. Estes. Journal of Mathematical Psychology, 59, 41-49. https://doi.org/10.1016/j.jmp.2013.10.001

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- igt_vpp(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- igt_vpp(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

Function to plot multiple figures

Description

Plots multiple figures Based on codes from 'http://www.cookbook-r.com/Graphs/Multiple_graphs_on_one_page_(ggplot2)/'

Usage

multiplot(..., plots = NULL, cols = NULL)

Arguments

Other-Conferred Utility (OCU) Model

Description

Hierarchical Bayesian Modeling of the Peer Influence Task using Other-Conferred Utility (OCU) Model. It has the following parameters: rho (risk preference), tau (inverse temperature), ocu (other-conferred utility).

• Task: Peer Influence Task (Chung et al., 2015)

• Model: Other-Conferred Utility (OCU) Model

Usage

peer_ocu(
  data = NULL,
  niter = 4000,
  nwarmup = 1000,
  nchain = 4,
  ncore = 1,
  nthin = 1,
  inits = "vb",
  indPars = "mean",
  modelRegressor = FALSE,
  vb = FALSE,
  inc_postpred = FALSE,
  adapt_delta = 0.95,
  stepsize = 1,
  max_treedepth = 10,
  ...
)

Arguments

Details

This section describes some of the function arguments in greater detail.

data should be assigned a character value specifying the full path and name (including extension information, e.g. ".txt") of the file that contains the behavioral data-set of all subjects of interest for the current analysis. The file should be a tab-delimited text file, whose rows represent trial-by-trial observations and columns represent variables.
For the Peer Influence Task, there should be 8 columns of data with the labels "subjID", "condition", "p_gamble", "safe_Hpayoff", "safe_Lpayoff", "risky_Hpayoff", "risky_Lpayoff", "choice". It is not necessary for the columns to be in this particular order, however it is necessary that they be labeled correctly and contain the information below:

subjID

A unique identifier for each subject in the data-set.

condition

0: solo, 1: info (safe/safe), 2: info (mix), 3: info (risky/risky).

p_gamble

Probability of receiving a high payoff (same for both options).

safe_Hpayoff

High payoff of the safe option.

safe_Lpayoff

Low payoff of the safe option.

risky_Hpayoff

High payoff of the risky option.

risky_Lpayoff

Low payoff of the risky option.

choice

Which option was chosen? 0: safe, 1: risky.

*Note: The file may contain other columns of data (e.g. "ReactionTime", "trial_number", etc.), but only the data within the column names listed above will be used during the modeling. As long as the necessary columns mentioned above are present and labeled correctly, there is no need to remove other miscellaneous data columns.

nwarmup is a numerical value that specifies how many MCMC samples should not be stored upon the beginning of each chain. For those familiar with Bayesian methods, this is equivalent to burn-in samples. Due to the nature of the MCMC algorithm, initial values (i.e. where the sampling chains begin) can have a heavy influence on the generated posterior distributions. The nwarmup argument can be set to a high number in order to curb the effects that initial values have on the resulting posteriors.

nchain is a numerical value that specifies how many chains (i.e. independent sampling sequences) should be used to draw samples from the posterior distribution. Since the posteriors are generated from a sampling process, it is good practice to run multiple chains to ensure that a reasonably representative posterior is attained. When the sampling is complete, it is possible to check the multiple chains for convergence by running the following line of code: plot(output, type = "trace"). The trace-plot should resemble a "furry caterpillar".

nthin is a numerical value that specifies the "skipping" behavior of the MCMC sampler, using only every i == nthin samples to generate posterior distributions. By default, nthin is equal to 1, meaning that every sample is used to generate the posterior.

Control Parameters: adapt_delta, stepsize, and max_treedepth are advanced options that give the user more control over Stan's MCMC sampler. It is recommended that only advanced users change the default values, as alterations can profoundly change the sampler's behavior. Refer to 'The No-U-Turn Sampler: Adaptively Setting Path Lengths in Hamiltonian Monte Carlo (Hoffman & Gelman, 2014, Journal of Machine Learning Research)' for more information on the sampler control parameters. One can also refer to 'Section 34.2. HMC Algorithm Parameters' of the Stan User's Guide and Reference Manual, or to the help page for stan for a less technical description of these arguments.

Contributors

Harhim Park <hrpark12@gmail.com>

Value

A class "hBayesDM" object modelData with the following components:

model

Character value that is the name of the model (\code"peer_ocu").

allIndPars

Data.frame containing the summarized parameter values (as specified by indPars) for each subject.

parVals

List object containing the posterior samples over different parameters.

fit

A class stanfit object that contains the fitted Stan model.

rawdata

Data.frame containing the raw data used to fit the model, as specified by the user.

modelRegressor

List object containing the extracted model-based regressors.

References

Chung, D., Christopoulos, G. I., King-Casas, B., Ball, S. B., & Chiu, P. H. (2015). Social signals of safety and risk confer utility and have asymmetric effects on observers' choices. Nature Neuroscience, 18(6), 912-916.

See Also

We refer users to our in-depth tutorial for an example of using hBayesDM: https://rpubs.com/CCSL/hBayesDM

Examples

## Not run: 
# Run the model with a given data.frame as df
output <- peer_ocu(
  data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Run the model with example data
output <- peer_ocu(
  data = "example", niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4)

# Visually check convergence of the sampling chains (should look like 'hairy caterpillars')
plot(output, type = "trace")

# Check Rhat values (all Rhat values should be less than or equal to 1.1)
rhat(output)

# Plot the posterior distributions of the hyper-parameters (distributions should be unimodal)
plot(output)

# Show the WAIC and LOOIC model fit estimates
printFit(output)

## End(Not run)

General Purpose Plotting for hBayesDM. This function plots hyper parameters.

Description

General Purpose Plotting for hBayesDM. This function plots hyper parameters.

Usage

## S3 method for class 'hBayesDM'
plot(
  x = NULL,
  type = "dist",
  ncols = NULL,
  fontSize = NULL,
  binSize = NULL,
  ...
)

Arguments

Plots the histogram of MCMC samples.

Description

Plots the histogram of MCMC samples.

Usage

plotDist(
  sample = NULL,
  Title = NULL,
  xLab = "Value",
  yLab = "Density",
  xLim = NULL,
  fontSize = NULL,
  binSize = NULL,
  ...
)

Arguments