Overview

PyPI PyPI - Downloads PyPI - Python Version GitHub pull requests GitHub Workflow Status (with event) GitHub Repo stars

HSSM (Hierarchical Sequential Sampling Modeling) is a modern, source-available Python toolbox for computational modeling in cognitive neuroscience. It supports a broad range of sequential sampling models used to study decision-making, learning, and other cognitive processes — from basic research to the analysis of clinical effects. HSSM provides state-of-the-art likelihood approximation methods within the Python Bayesian ecosystem and facilitates hierarchical model building and inference via fast and robust MCMC samplers. User-friendly, extensible, and flexible, it can rigorously estimate the impact of neural and other trial-by-trial covariates through parameter-wise mixed-effects models.

HSSM is a BRAINSTORM project in collaboration with the Center for Computation and Visualization (CCV) and the Center for Computational Brain Science within the Carney Institute at Brown University.

Installation¶

pip install hssm        # or: uv add hssm

HSSM installs on all platforms with Python 3.12–3.14. For GPU sampling (CUDA extras), Colab, the dev version, optional dependencies, and troubleshooting, see the Installation guide.

Example¶

Here is a simple example of how to use HSSM:

import hssm

# Load a package-supplied dataset
cav_data = hssm.load_data("cavanagh_theta")

# Define a basic hierarchical model with trial-level covariates
model = hssm.HSSM(
    model="ddm",
    data=cav_data,
    include=[
        {
            "name": "v",
            "prior": {
                "Intercept": {"name": "Normal", "mu": 0.0, "sigma": 1.0},
                "theta": {"name": "Normal", "mu": 0.0, "sigma": 1.0},
            },
            "formula": "v ~ theta + (1|participant_id)",
            "link": "identity",
        },
    ],
)

# Sample from the posterior for this model
model.sample()

Start here¶

Fit your first model

From pip install to a result you can defend. Six steps, each building on the last:
1. Installation — a working environment, GPU extras included.
2. Quickstart — simulate, fit, and check a DDM in about 15 minutes.
3. The HSSM tutorial — one guided next step: fit a drift-rate regression, diagnose it, check predictions, and interpret the condition effect.
4. Hierarchical modeling — lmer-style formulas on any model parameter.
5. Hierarchical DDM regressions — map your actual design onto a formula, and recover it.
6. Compare and interpret models — rank candidates, and recognise when the data cannot separate them.
Capstone: A complete scientific workflow — one dataset, start to finish.

Want every option? Take the optional scenic route through model families, priors, regressions, hierarchies, comparison, and low-level extensions.

Used HDDM before? Coming from HDDM maps what you know onto HSSM.
Bring your own likelihood or model

For models HSSM does not ship, or likelihoods you trained yourself:
1. Likelihood kinds in HSSM — analytical, approx_differentiable, and blackbox, and when each applies.
2. The ONNX likelihood contract — the exact rules an approximate differentiable ONNX file must satisfy.
3. Bring your own likelihood — the route table for networks trained in sbi or BayesFlow.
4. Then the walkthrough for your route — sbi NRE, BayesFlow NRE, BayesFlow LRE, or JAX callables.
5. Use the low-level API with PyMC — when the formula interface is the constraint.

Beyond the paths, the docs are organised by what you are doing: Learn for guided material, How-to guides for a specific task, Explanations for the reasoning behind a choice, and Reference for exact APIs and project metadata.

Part of a larger toolchain¶

HSSM is the inference layer of a larger ecosystem: ssm-simulators supplies the models and simulated data, LANfactory trains the likelihood networks that make otherwise-intractable models estimable, and HSSM consumes them. Most users never need the other repositories. See the canonical HSSM ecosystem map for ownership boundaries, contributor routes, and the complete site directory.

What HSSM gives you¶

Hierarchical Bayesian inference for a broad family of sequential sampling models, including those with no analytical likelihood.
Parameter-wise mixed-effects regressions in lmer-like syntax, so neural and trial-by-trial covariates can enter any model parameter.
Reinforcement learning sequential sampling models (RLSSMs), where the decision parameters are driven by a learning process.
Custom models and likelihoods: bring an ONNX network, a JAX callable, or a black-box Python function.
Built on PyMC, Bambi, and ArviZ, so the wider Python Bayesian ecosystem applies directly.

Citation¶

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.

Community¶

Questions and modeling advice — open a discussion.
Bugs and feature requests — open an issue using the corresponding template.
Contributing — see the contribution guidelines.