Overview

HSSM (Hierarchical Sequential Sampling Modeling) is a modern open-source 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 — the guided introduction: model choice, priors, diagnostics, predictive checks, comparison.
  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.

  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. Understanding likelihoods in HSSM — analytical, approx_differentiable, and blackbox, and when each applies.
  2. The ONNX likelihood contract — the rules an ONNX file must satisfy, demonstrated live.
  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 NLE, 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 the API.

Part of a larger toolchain

HSSM is the inference layer of a four-package 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 three. See The HSSM ecosystem for the map, including which package answers which question and how versions fit together.

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., Omar, A., Frank, M.J. (in preparation). HSSM: A generalized toolbox for hierarchical bayesian estimation of computational models in cognitive neuroscience.

Community

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

License

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