Hierarchical Bayesian Modeling of the 2-alternative forced choice task using Signal detection theory model.
It has the following parameters: `d`

(discriminability), `c`

(decision bias (criteria)).

**Task**: 2-alternative forced choice task**Model**: Signal detection theory model

task2AFC_sdt( 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, ... )

data | Data to be modeled. It should be given as a data.frame object,
a filepath for a tab-seperated txt file, |
---|---|

niter | Number of iterations, including warm-up. Defaults to 4000. |

nwarmup | Number of iterations used for warm-up only. Defaults to 1000. |

nchain | Number of Markov chains to run. Defaults to 4. |

ncore | Number of CPUs to be used for running. Defaults to 1. |

nthin | Every |

inits | Character value specifying how the initial values should be generated. Possible options are "vb" (default), "fixed", "random", or your own initial values. |

indPars | Character value specifying how to summarize individual parameters. Current options are: "mean", "median", or "mode". |

modelRegressor | Whether to export model-based regressors ( |

vb | Use variational inference to approximately draw from a posterior distribution. Defaults
to |

inc_postpred | Include trial-level posterior predictive simulations in model output (may greatly increase file
size). Defaults to |

adapt_delta | Floating point value representing the target acceptance probability of a new
sample in the MCMC chain. Must be between 0 and 1. See |

stepsize | Integer value specifying the size of each leapfrog step that the MCMC sampler can
take on each new iteration. See |

max_treedepth | Integer value specifying how many leapfrog steps the MCMC sampler can take
on each new iteration. See |

... | For this model, there is no model-specific argument. |

A class "hBayesDM" object `modelData`

with the following components:

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

- 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.

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-alternative forced choice task, there should be 3 columns of data with the
labels "subjID", "stimulus", "response". 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.

- stimulus
Types of Stimuli (Should be 1 or 0. 1 for Signal and 0 for Noise)

- response
Types of Responses (It should be same format as the stimulus field. Should be 1 or 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.

Heesun Park <heesunpark26@gmail.com>

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

if (FALSE) { # Run the model with a given data.frame as df output <- task2AFC_sdt( data = df, niter = 2000, nwarmup = 1000, nchain = 4, ncore = 4) # Run the model with example data output <- task2AFC_sdt( 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) }