| Title: | Stop-Signal Reaction Time Calculator with Monte Carlo and Bayesian Extensions |
|---|---|
| Description: | Estimates stop-signal reaction time (SSRT) using integration and mean methods following Verbruggen et al. (2019) <doi:10.7554/eLife.46323>. Version 2.0 adds three major extensions: (1) Monte Carlo methods -- nonparametric bootstrap confidence intervals, parametric ex-Gaussian simulation, power/minimum-trial-count analysis, and robustness testing under horse-race assumption violations; (2) Bayesian estimation via Stan -- single-subject and hierarchical ex-Gaussian horse-race models with optional trigger-failure parameter, posterior inhibition functions, and posterior predictive checks; (3) convenience wrappers for comparing models and running full pipelines. Stan integration works with either cmdstanr or rstan as backend. |
| Authors: | Anton Leontyev [aut, cre] (ORCID: <https://orcid.org/0000-0001-8880-6161>) |
| Maintainer: | Anton Leontyev <[email protected]> |
| License: | GPL-3 |
| Version: | 2.0.4 |
| Built: | 2026-07-04 23:18:28 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)
Data from a mouse movement-based stop-signal experiment, using preset stop-signal delays, with random dot kinematogram as the "go" task, collected from 51 participants
data(fixed)data(fixed)
A data frame with 29376 rows and 7 variables
Subject identifier
stop-signal delay (ignore for "go" trials)
stop (1) or go (0) trial
Percent coherent dots in the kinematogram go task
Response time in seconds, NA if no response was made
Which button did the participant click?
Did the participant respond in "go" trials/omit response in "stop" trials (1) or not(0)?
Leontyev and Yamauchi (2019) PLoS One (doi:10.1371/journal.pone.0225437)
data(fixed) head(fixed)data(fixed) head(fixed)
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(adaptive) d <- adaptive[adaptive$SubjID == 1, ] integration_fixedSSD(d)data(adaptive) d <- adaptive[adaptive$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(adaptive) d <- adaptive[adaptive$SubjID == 1, ] mean_fixedSSD(d)data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] mean_fixedSSD(d)
Plots and prints stop-signal delays and corresponding accuracies. For studies that use fixed (randomly chosen on each trial from a pre-determined set) stop-signal delays.
plotInhFunc(df, stop_col, ssd_col, acc_col)plotInhFunc(df, stop_col, ssd_col, acc_col)
df |
Dataframe with response time, accuracy, indication whether trial is stop or go, and delays for a given trial. |
stop_col |
Name of the column in the dataframe |
ssd_col |
Name of the column in the dataframe |
acc_col |
Name of the column in the dataframe |
Line plot of the inhibition function.
data(fixed) df <- subset(fixed, new_id == 3) plotInhFunc(df = df, stop_col='vol', ssd_col='soa', acc_col='acc')data(fixed) df <- subset(fixed, new_id == 3) plotInhFunc(df = df, stop_col='vol', ssd_col='soa', acc_col='acc')
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=100, trigger_range=seq(0, 0.3, 0.1)) print(r)data(adaptive) d <- adaptive[adaptive$SubjID == 1, ] r <- ssrt_robustness(d, violation="trigger_failure", n_iter=100, trigger_range=seq(0, 0.3, 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)