HSSM - Hierarchical Sequential Sampling Modeling

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.

At a Glance

Installation

Install HSSM in a fresh virtual environment with Python 3.12, 3.13, or 3.14.

CPU

pip install hssm

You can also add HSSM to a uv project:

uv add hssm

CUDA

For NVIDIA GPUs, install HSSM with the extra matching your CUDA version:

pip install "hssm[cuda12]"  # CUDA 12
pip install "hssm[cuda13]"  # CUDA 13

or with uv:

uv add "hssm[cuda12]"  # CUDA 12
uv add "hssm[cuda13]"  # CUDA 13

Note: JAX's CUDA wheels are Linux-only and require a compatible NVIDIA driver (>= 525 for CUDA 12, >= 580 for CUDA 13).

Apple Silicon, AMD, and Other Accelerators

JAX supports several accelerator backends. Follow the official JAX installation guide for your platform, then install HSSM in the same environment.

Development Version

Install the current development version directly from GitHub:

pip install git+https://github.com/lnccbrown/HSSM.git

With uv:

uv add git+https://github.com/lnccbrown/HSSM.git

Google Colab

Google Colab already includes PyMC and JAX, so a standard pip install is enough:

!pip install hssm

Troubleshooting

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

Quick Start

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.

Where HSSM Fits

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.

Citation

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

Next Steps

• Documentation
• Getting started
• Main tutorial
• Scientific workflow tutorial
• RLSSM basic tutorial
• RLSSM custom models
• Plotting and model checking
• GitHub Discussions
• Contribution guide

Support

For questions, please open a discussion.

For bug reports and feature requests, please open an issue using the corresponding template.

Contribution

If you want to contribute to this project, please follow our contribution guidelines.

License

HSSM is licensed under Copyright 2023, Brown University, Providence, RI.

Acknowledgements

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.