HSSM is a Python toolbox for hierarchical Bayesian neurocognitive modeling of choice, response time, and covariate-rich trial data.
It supports a broad family of sequential-sampling models, reinforcement learning sequential-sampling models (RLSSMs), behavioral, neural, eye-tracking, and SCR covariates, hierarchical regression, posterior diagnostics, posterior predictive checks, and Bayesian model comparison.
HSSM is a BRAINSTORM project in collaboration with the Center for Computation and Visualization and the Center for Computational Brain Science within the Carney Institute at Brown University.
| Use HSSM to... | What this means in practice |
|---|---|
| Fit sequential-sampling models | Build DDM, LBA, race, angle, and related choice/RT models from a high-level Python API. |
| Model behavioral, neural, and other trial-wise covariates | Regress model parameters on trial-level predictors such as EEG, eye-tracking, SCR, task condition, or stimulus features. |
| Use hierarchical and mixed-effects parameter models | Estimate participant-level variation and within- or between-subject effects with Bambi-style formulas. |
| Work with RLSSMs | Combine reinforcement-learning dynamics with sequential-sampling decision models. |
| Diagnose and compare Bayesian models | Use ArviZ summaries, trace diagnostics, posterior predictive checks, and model-comparison workflows. |
| Extend models with custom likelihoods | Register new models and likelihoods when built-in model definitions are not enough. |
Install HSSM in a fresh virtual environment with Python 3.12, 3.13, or 3.14.
pip install hssmYou can also add HSSM to a uv project:
uv add hssmFor NVIDIA GPUs, install HSSM with the extra matching your CUDA version:
pip install "hssm[cuda12]" # CUDA 12
pip install "hssm[cuda13]" # CUDA 13or with uv:
uv add "hssm[cuda12]" # CUDA 12
uv add "hssm[cuda13]" # CUDA 13Note: JAX's CUDA wheels are Linux-only and require a compatible NVIDIA driver (>= 525 for CUDA 12, >= 580 for CUDA 13).
JAX supports several accelerator backends. Follow the official JAX installation guide for your platform, then install HSSM in the same environment.
Install the current development version directly from GitHub:
pip install git+https://github.com/lnccbrown/HSSM.gitWith uv:
uv add git+https://github.com/lnccbrown/HSSM.gitGoogle Colab already includes PyMC and JAX, so a standard pip install is enough:
!pip install hssmHSSM is tested on Python 3.12, 3.13, and 3.14. If installation fails, start from a fresh virtual environment using one of those Python versions and check GitHub Discussions for known platform-specific fixes.
import arviz as az
import hssm
# Load a package-supplied choice/response-time dataset.
data = hssm.load_data("cavanagh_theta")
# Build a basic drift-diffusion model.
model = hssm.HSSM(data=data, model="ddm")
# Draw posterior samples. Increase draws/tune/chains for publication analyses.
idata = model.sample(draws=1000, tune=1000, chains=4)
# Inspect convergence and posterior summaries with ArviZ.
az.summary(idata)
az.plot_trace_dist(idata)For diagnostics, interpretation, regression formulas, and model comparison, see the getting started guide and the main tutorial.
HSSM is the user-facing modeling layer in the HSSM ecosystem. It builds on PyMC for Bayesian inference, Bambi for formula-based and hierarchical regression, ArviZ for diagnostics and model comparison, and JAX/PyTensor for computation.
Within the broader ecosystem, ssm-simulators supplies simulator and model definitions, while LANfactory supports likelihood approximation workflows used to develop new likelihoods.
Please cite the current HSSM paper:
Fengler, A., Xu, Y., Bera, K., Paniagua, C., Omar, A., and Frank, M. J. HSSM: A Widely Applicable Toolbox for Hierarchical Bayesian Neurocognitive Modeling. bioRxiv 2026.06.05.730398.
- DOI: https://doi.org/10.64898/2026.06.05.730398
- bioRxiv: https://www.biorxiv.org/content/10.1101/2026.06.05.730398v1
- Software archive DOI, when needed for reproducibility: https://doi.org/10.5281/zenodo.17247695
- Documentation
- Getting started
- Main tutorial
- Scientific workflow tutorial
- RLSSM basic tutorial
- RLSSM custom models
- Plotting and model checking
- GitHub Discussions
- Contribution guide
For questions, please open a discussion.
For bug reports and feature requests, please open an issue using the corresponding template.
If you want to contribute to this project, please follow our contribution guidelines.
HSSM is licensed under Copyright 2023, Brown University, Providence, RI.
We are grateful to the Bambi project for inspiration, guidance, and support. Tomas Capretto, a key contributor to Bambi, provided invaluable assistance during HSSM development.