| Title: | Monte Carlo and Bayesian Stop-Signal Reaction Time Estimation |
|---|---|
| Description: | Estimates stop-signal reaction time (SSRT) in the stop-signal task using the integration and mean methods described by Verbruggen and colleagues (2019) <doi:10.7554/eLife.46323>. In addition to point estimates, the package provides Monte Carlo tools (nonparametric bootstrap confidence intervals, parametric ex-Gaussian simulation, minimum-trial-count and power analysis, and sensitivity analysis under violations of the horse-race assumptions) and Bayesian estimation via 'Stan', including single-subject and hierarchical ex-Gaussian horse-race models with an optional trigger-failure parameter following Matzke and colleagues (2013) <doi:10.1037/a0030543>, posterior inhibition functions, and posterior predictive checks. The Bayesian layer works with either the 'cmdstanr' or 'rstan' backend. |
| Authors: | Anton Leontyev [aut, cre] (ORCID: <https://orcid.org/0000-0001-8880-6161>) |
| Maintainer: | Anton Leontyev <antonleontyev@missouristate.edu> |
| License: | GPL-3 |
| Version: | 2.1.1 |
| Built: | 2026-10-13 12:36:38 UTC |
| Source: | https://github.com/agleontyev/ssrtcalc |
A long-format dataset from a stop-signal task using an adaptive (staircase-tracking) stop-signal delay, suitable for demonstrating every function in SSRTcalc.
adaptiveadaptive
A data frame with 4000 rows (20 subjects x 200 trials) and 6 columns:
Integer subject identifier (1-20).
Integer trial number within subject (1-200).
Trial type: 0 = go trial, 1 = stop trial.
Observed reaction time in milliseconds. NA on
successfully inhibited stop trials.
Accuracy indicator (1 = correct response on go
trials, or successful inhibition on stop trials; 0 otherwise).
Stop-signal delay (SOA) in milliseconds for stop trials;
NA on go trials. Adjusted trial-by-trial by a staircase
algorithm to track ~50% inhibition.
Simulated data distributed with the SSRTcalc package, generated to resemble a typical adaptive stop-signal task following Verbruggen et al. (2019) <doi:10.7554/eLife.46323>.
data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] integration_adaptiveSSD(d)data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] integration_adaptiveSSD(d)
A long-format dataset from a stop-signal variant of a random-dot
motion-discrimination task in which the stop-signal delay (SOA) was set to
one of six fixed values rather than being tracked by a staircase.
It complements the adaptive dataset and is intended for
demonstrating the fixed-SSD estimators integration_fixedSSD
and mean_fixedSSD.
fixedfixed
A data frame with 28,799 rows (50 subjects) and 8 columns:
Integer subject identifier. Subject 2 from the original recording is excluded (see Details), so the IDs run 1 and 3-51.
Trial number within subject (1-576; a subject with one removed trial has 575).
Trial type: 0 = go trial, 1 = stop trial.
Observed reaction time in milliseconds. NA when no
response was made (successfully inhibited stop trials and go-trial
omissions).
Accuracy indicator (1 = correct go response or
successful inhibition; 0 otherwise).
Stop-signal delay (SOA) in milliseconds for stop trials, one of
six fixed values (100, 200, 300, 400, 500, 600 ms); NA on go
trials, matching the adaptive dataset.
Motion coherence for the go discrimination (0.1, 0.5, or 0.8), an experimental difficulty manipulation.
Response direction ("left", "right", or
NA when no response was made).
All timing variables are in milliseconds, matching the rest of the
package and the adaptive dataset.
During preparation, subject 2 (who had no recorded responses on any trial) and a single stop trial with a recorded reaction time of 0 ms were removed. Subject identifiers otherwise follow the original recording, so identifier 2 is absent.
Experimental data distributed with the SSRTcalc package, from a fixed-SSD motion-discrimination stop-signal task.
data(fixed) d <- fixed[fixed$SubjID == 1, ] integration_fixedSSD(d) mean_fixedSSD(d)data(fixed) d <- fixed[fixed$SubjID == 1, ] integration_fixedSSD(d) mean_fixedSSD(d)
Implements the recommended integration method from Verbruggen et al. (2019). For each dataset:
Compute p(respond|signal) from all stop trials.
Find the nth percentile of the go-RT distribution (n = p_respond).
Subtract the mean SSD: SSRT = nth_percentile_RT - mean(SSD).
integration_adaptiveSSD( data, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", min_rt = 50 )integration_adaptiveSSD( data, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", min_rt = 50 )
data |
A data.frame with one row per trial. |
stop_col |
Column name for the stop-trial indicator (1 = stop, 0 = go).
Default |
rt_col |
Column name for reaction time in ms. Default |
acc_col |
Column name for accuracy (1 = correct). Default |
ssd_col |
Column name for stop-signal delay in ms. Default |
min_rt |
Minimum valid RT in ms; shorter responses are excluded as anticipations. Default 50. |
A single numeric value: the estimated SSRT in milliseconds.
Verbruggen, F., et al. (2019). A consensus guide to capturing the ability to inhibit actions and impulses: the stop-signal task. eLife, 8, e46323. doi:10.7554/eLife.46323
data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] integration_adaptiveSSD(d)data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] integration_adaptiveSSD(d)
Identical to integration_adaptiveSSD in computation, but
intended for experiments using a fixed (constant) stop-signal delay. When
multiple fixed SSD values are used, SSRT is computed separately for each
SSD and the results are averaged (Verbruggen et al., 2019, Appendix).
integration_fixedSSD( data, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", min_rt = 50 )integration_fixedSSD( data, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", min_rt = 50 )
data |
A data.frame with one row per trial. |
stop_col |
Column name for the stop-trial indicator (1 = stop, 0 = go).
Default |
rt_col |
Column name for reaction time in ms. Default |
acc_col |
Column name for accuracy (1 = correct). Default |
ssd_col |
Column name for stop-signal delay in ms. Default |
min_rt |
Minimum valid RT in ms; shorter responses are excluded as anticipations. Default 50. |
A single numeric value: the estimated SSRT in milliseconds.
Verbruggen, F., et al. (2019). A consensus guide to capturing the ability to inhibit actions and impulses: the stop-signal task. eLife, 8, e46323. doi:10.7554/eLife.46323
data(fixed) d <- fixed[fixed$SubjID == 1, ] integration_fixedSSD(d)data(fixed) d <- fixed[fixed$SubjID == 1, ] integration_fixedSSD(d)
Computes SSRT as the difference between mean go RT and mean SSD:
This method is less accurate than the integration method but is included for comparison and historical compatibility.
mean_adaptiveSSD( data, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", min_rt = 50 )mean_adaptiveSSD( data, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", min_rt = 50 )
data |
A data.frame with one row per trial. |
stop_col |
Column name for the stop-trial indicator (1 = stop, 0 = go).
Default |
rt_col |
Column name for reaction time in ms. Default |
acc_col |
Column name for accuracy (1 = correct). Default |
ssd_col |
Column name for stop-signal delay in ms. Default |
min_rt |
Minimum valid RT in ms; shorter responses are excluded as anticipations. Default 50. |
A single numeric value: the estimated SSRT in milliseconds.
data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] mean_adaptiveSSD(d)data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] mean_adaptiveSSD(d)
Computes SSRT as . For multiple fixed SSD
values the mean is taken across all stop trials.
mean_fixedSSD( data, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", min_rt = 50 )mean_fixedSSD( data, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", min_rt = 50 )
data |
A data.frame with one row per trial. |
stop_col |
Column name for the stop-trial indicator (1 = stop, 0 = go).
Default |
rt_col |
Column name for reaction time in ms. Default |
acc_col |
Column name for accuracy (1 = correct). Default |
ssd_col |
Column name for stop-signal delay in ms. Default |
min_rt |
Minimum valid RT in ms; shorter responses are excluded as anticipations. Default 50. |
A single numeric value: the estimated SSRT in milliseconds.
data(fixed) d <- fixed[fixed$SubjID == 1, ] mean_fixedSSD(d)data(fixed) d <- fixed[fixed$SubjID == 1, ] mean_fixedSSD(d)
A generic function for extracting per-group (e.g. per-subject) parameter
summaries from a fitted model. SSRTcalc provides
ranef.ssrt_stan for hierarchical Stan fits.
ranef(object, ...)ranef(object, ...)
object |
A fitted model object. |
... |
Additional arguments passed to methods. |
A method-specific object (typically a data.frame of per-group summaries).
Extract per-subject random effects from a hierarchical fit
## S3 method for class 'ssrt_stan' ranef(object, ...)## S3 method for class 'ssrt_stan' ranef(object, ...)
object |
An |
... |
Unused. |
data.frame with per-subject posterior summaries.
Run all four Monte Carlo analyses in one call
run_all_mc( data, n_iter = 1000, seed = 42, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa" )run_all_mc( data, n_iter = 1000, seed = 42, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa" )
data |
data.frame in SSRTcalc long format. |
n_iter |
Iterations (shared). Default 1000. |
seed |
Random seed. Default 42. |
stop_col, rt_col, acc_col, ssd_col
|
Column names. |
Named list: bootstrap, simulation, power, robustness.
## Not run: data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] res <- run_all_mc(d, n_iter=500) ## End(Not run)## Not run: data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] res <- run_all_mc(d, n_iter=500) ## End(Not run)
Resamples trials with replacement n_iter times and applies the
chosen SSRT estimation function to each resample.
ssrt_boot( data, ssrt_fn = "integration_adaptiveSSD", n_iter = 2000, conf = 0.95, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", seed = 42, parallel = FALSE, n_cores = 2 )ssrt_boot( data, ssrt_fn = "integration_adaptiveSSD", n_iter = 2000, conf = 0.95, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", seed = 42, parallel = FALSE, n_cores = 2 )
data |
data.frame in SSRTcalc long format. |
ssrt_fn |
SSRT function name. Default |
n_iter |
Bootstrap resamples. Default 2000. |
conf |
Confidence level. Default 0.95. |
stop_col, rt_col, acc_col, ssd_col
|
Column names. |
seed |
Random seed. Default 42. |
parallel |
Use parallel::mclapply? (Unix/macOS only). Default FALSE. |
n_cores |
Cores when parallel=TRUE. Default 2. |
Object of class ssrt_boot.
data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] b <- ssrt_boot(d, n_iter = 500) print(b)data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] b <- ssrt_boot(d, n_iter = 500) print(b)
Simulates datasets of increasing size and computes SSRT variance as a function of trial count (power curve).
ssrt_power( data, trial_counts = c(10, 20, 30, 50, 75, 100, 150, 200), n_iter = 500, target_se = 10, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", seed = 42 )ssrt_power( data, trial_counts = c(10, 20, 30, 50, 75, 100, 150, 200), n_iter = 500, target_se = 10, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", seed = 42 )
data |
data.frame for calibration. |
trial_counts |
Stop-trial counts to evaluate. |
n_iter |
MC iterations per count. Default 500. |
target_se |
Target SE in ms. Default 10. |
stop_col, rt_col, acc_col, ssd_col
|
Column names. |
seed |
Random seed. Default 42. |
Object of class ssrt_power.
data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] p <- ssrt_power(d, trial_counts=c(10,30,50), n_iter=200) print(p)data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] p <- ssrt_power(d, trial_counts=c(10,30,50), n_iter=200) print(p)
Sweeps three violation types: go/stop process correlation, trigger failure rate, and go-RT shift on stop trials.
ssrt_robustness( data, violation = "all", n_iter = 500, corr_range = seq(0, 0.8, by = 0.1), trigger_range = seq(0, 0.4, by = 0.05), shift_range = seq(0, 100, by = 10), stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", seed = 42 )ssrt_robustness( data, violation = "all", n_iter = 500, corr_range = seq(0, 0.8, by = 0.1), trigger_range = seq(0, 0.4, by = 0.05), shift_range = seq(0, 100, by = 10), stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", seed = 42 )
data |
data.frame for calibration. |
violation |
"all", "correlation", "trigger_failure", or "go_shift". |
n_iter |
MC iterations per condition. Default 500. |
corr_range |
Correlations to test. |
trigger_range |
Trigger failure rates to test. |
shift_range |
Go-RT shifts in ms to test. |
stop_col, rt_col, acc_col, ssd_col
|
Column names. |
seed |
Random seed. Default 42. |
Object of class ssrt_robustness.
data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] r <- ssrt_robustness(d, violation="trigger_failure", n_iter=20, trigger_range=seq(0, 0.2, 0.1)) print(r)data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] r <- ssrt_robustness(d, violation="trigger_failure", n_iter=20, trigger_range=seq(0, 0.2, 0.1)) print(r)
Fits an ex-Gaussian to observed go-RT data, simulates synthetic datasets under the horse-race model, and estimates SSRT on each.
ssrt_simulate( data, n_iter = 2000, n_trials = NULL, p_stop = NULL, ssrt_true = NULL, conf = 0.95, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", seed = 42 )ssrt_simulate( data, n_iter = 2000, n_trials = NULL, p_stop = NULL, ssrt_true = NULL, conf = 0.95, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", seed = 42 )
data |
data.frame in SSRTcalc long format. |
n_iter |
MC iterations. Default 2000. |
n_trials |
Trials per simulated dataset. NULL uses nrow(data). |
p_stop |
Stop-trial proportion. NULL uses observed proportion. |
ssrt_true |
Known true SSRT for parameter recovery. Default NULL. |
conf |
Confidence level. Default 0.95. |
stop_col, rt_col, acc_col, ssd_col
|
Column names. |
seed |
Random seed. Default 42. |
Object of class ssrt_simulate.
data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] s <- ssrt_simulate(d, n_iter=500) print(s)data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] s <- ssrt_simulate(d, n_iter=500) print(s)
Fits the independent horse-race model with ex-Gaussian go- and stop-process distributions using Hamiltonian Monte Carlo via Stan. Supports single-subject and multi-subject hierarchical designs, with an optional trigger-failure parameter following Matzke et al. (2013).
ssrt_stan( data, model = c("single", "hierarchical"), subject_col = NULL, trigger_failure = FALSE, n_quad = 100, chains = 4, iter = 2000, warmup = 1000, cores = 4, backend = "auto", adapt_delta = 0.95, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", seed = 42, ... )ssrt_stan( data, model = c("single", "hierarchical"), subject_col = NULL, trigger_failure = FALSE, n_quad = 100, chains = 4, iter = 2000, warmup = 1000, cores = 4, backend = "auto", adapt_delta = 0.95, stop_col = "vol", rt_col = "RT_exp", acc_col = "correct", ssd_col = "soa", seed = 42, ... )
data |
data.frame in SSRTcalc long format. |
model |
|
subject_col |
Column with subject IDs (required for hierarchical). |
trigger_failure |
Logical: include trigger-failure parameter. Default FALSE. |
n_quad |
Quadrature resolution for P(inhibit) integral. Default 100. |
chains |
Number of MCMC chains. Default 4. |
iter |
Total iterations per chain including warmup. Default 2000. |
warmup |
Warmup iterations. Default 1000. |
cores |
Parallel cores. Default 4. |
backend |
|
adapt_delta |
HMC target acceptance rate. Increase to 0.99 if divergences appear. Default 0.95. |
stop_col, rt_col, acc_col, ssd_col
|
Column names. |
seed |
Random seed. Default 42. |
... |
Additional arguments passed to the Stan sampler. |
An object of class ssrt_stan.
Matzke, D., et al. (2013). Bayesian parametric estimation of stop-signal reaction time distributions. Journal of Experimental Psychology: General, 142(4), 1047–1073.
## Not run: data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] fit <- ssrt_stan(d, chains = 4, iter = 2000) print(fit) plot(fit) # Hierarchical fit_h <- ssrt_stan(adaptive, model = "hierarchical", subject_col = "SubjID", chains = 4) ranef(fit_h) ## End(Not run)## Not run: data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] fit <- ssrt_stan(d, chains = 4, iter = 2000) print(fit) plot(fit) # Hierarchical fit_h <- ssrt_stan(adaptive, model = "hierarchical", subject_col = "SubjID", chains = 4) ranef(fit_h) ## End(Not run)
Fits both models and returns side-by-side SSRT posterior summaries.
ssrt_stan_compare(data, ...)ssrt_stan_compare(data, ...)
data |
data.frame in SSRTcalc long format. |
... |
Arguments forwarded to |
Invisibly, a list with base, tf, and comparison.
Computes P(inhibit | SSD) across a range of SSD values using posterior parameter samples, with a 90
ssrt_stan_inhibition_fn( fit, ssd_range = seq(0, 600, by = 10), n_draws = 400, plot = TRUE )ssrt_stan_inhibition_fn( fit, ssd_range = seq(0, 600, by = 10), n_draws = 400, plot = TRUE )
fit |
An |
ssd_range |
SSD values to evaluate in ms. Default |
n_draws |
Posterior draws to use. Default 400. |
plot |
Produce the plot? Default TRUE. |
Invisibly, a data.frame with columns: ssd, mean, lo90, hi90.
Requires the Stan model to include a log_lik vector in
generated quantities. If absent, an informative error explains how to add it.
ssrt_stan_loo(fit)ssrt_stan_loo(fit)
fit |
An |
A loo object.
Overlays posterior-predictive RT distributions over observed data.
ssrt_stan_pp_check(fit, n_samples = 200)ssrt_stan_pp_check(fit, n_samples = 200)
fit |
An |
n_samples |
Posterior draws to use. Default 200. |
Invisibly, a list with pp_go_rt and pp_ssrt.
## Not run: data(adaptive) fit <- ssrt_stan(adaptive[adaptive$SubjID == 1, ]) ssrt_stan_pp_check(fit) ## End(Not run)## Not run: data(adaptive) fit <- ssrt_stan(adaptive[adaptive$SubjID == 1, ]) ssrt_stan_pp_check(fit) ## End(Not run)