v0.5.0

HSSM v0.5.0: New conflict-task and collapsing-bound models, safer hierarchical prior defaults, and richer model visualization

We're excited to announce HSSM 0.5.0, a release that broadens HSSM's model library toward conflict tasks and collapsing decision bounds, makes hierarchical prior defaults safer and more honest about their limits, and substantially expands what the model cartoon plots can show you.

This release adds three new built-in models, each backed by a trained likelihood network published alongside its parameter-recovery evidence. It also tightens how HSSM generates priors for hierarchical models, replacing a silent fallback with an explicit modeling decision where the previous default could not be justified.

Install or upgrade directly from PyPI:

pip install -U hssm
# or
uv add hssm

HSSM 0.5.0 supports Python 3.12 through 3.14.

What's new

Conflict-task models: gamma_drift and gamma_drift_angle

HSSM 0.5.0 adds the conflict-task (DMC-style) model family. In gamma_drift, the drift is a constant v plus a gamma-shaped bump with signed peak amplitude c, its time course set by shape and scale. A negative c pulls evidence toward the wrong boundary early in the trial and then decays back to baseline, which is the standard account of interference in Simon, flanker, and Stroop-style tasks.

gamma_drift_angle combines that drift with a linearly collapsing decision bound, adding the collapse angle theta.

Both models are available by name and their likelihood networks download automatically:

model = hssm.HSSM(data=data, model="gamma_drift_angle")

An angle model with a wider drift range

angle_extended is the angle model with drift bounds widened from (-3, 3) to (-6, 6), for designs that produce strong evidence and push drift rates beyond the standard range.

Networks published with their recovery evidence

The likelihood networks for the two new collapsing-bound models ship on the Hugging Face artifact repository together with a parameter-recovery report bound to the exact network it judges, and a model card describing what the sweep found.

angle_extended passed its 240-fit recovery sweep with no coverage or bias failures. The gamma_drift_angle report is published with a failing verdict and an explanation: the gamma bump can peak after a collapsing bound has already ended the decision, leaving shape and scale weakly identified at those truths. Users fitting data with fast responses should check those two parameters against their priors before interpreting them.

Richer posterior uncertainty in model cartoon plots

plot_model_cartoon now displays posterior uncertainty as graded bands by default, adopting the same uncertainty="band" | "samples" | "both" | None vocabulary as plot_predictive: pointwise quantile bands on the RT histograms, fan-chart ribbons on the decision bounds, a graded drift-quantile fan, and a starting-point whisker.

Each posterior draw's geometry now derives from one coherent parameter vector, a new random_state makes the whole figure reproducible, and hist_height="auto" fits histograms to the available headroom so they can never overrun the axes. See the model cartoon plot gallery (https://lnccbrown.github.io/HSSM/tutorials/cartoon_gallery/).

Safer hierarchical prior defaults

HSSM's generated safe priors now handle group-specific effects more carefully. Matching common and group terms are zero-centered deviations; an unmatched group term owns the population location and keeps it, instead of having it silently discarded by the non-centered reparameterization. Explicit priors that cannot be represented faithfully now raise before sampling rather than being quietly rebuilt into something else.

Where HSSM has no qualified default to offer, it now says so instead of inventing one. See the upgrade notes below.

Documentation

New and refreshed material on parameterization and prior design, including centered versus non-centered logic, per-parameter parameterization, and link functions and safe priors (https://lnccbrown.github.io/HSSM/tutorials/link_functions/). The installation guide now documents how to build the simulator with its GSL/OpenMP backend for faster simulation-heavy workflows (https://lnccbrown.github.io/HSSM/getting_started/installation/).

Important upgrade notes

HSSM 0.5.0 includes breaking changes. Please review these before upgrading:

• Safe priors now refuse to generate a hierarchy for a bounded parameter. A group-only intercept, such as v ~ 0 + (1|subject) with no matching common intercept, on an identity-linked parameter with a finite bound now raises ValueError instead of silently generating an unbounded hierarchy. This affects every approx_differentiable (LAN) model, including ones that shipped in 0.4.0 such as angle, weibull, levy, and ornstein. Exact and blackbox ddm, ddm_sdv, and full_ddm keep the previous warning, and the ordinary form v ~ 1 + (1|subject) is unaffected. To migrate, keep a common intercept, use a support-respecting link such as link_settings="log_logit", supply an explicit group prior, or set prior_settings=None and specify the prior policy yourself.
• Explicit group-specific priors that bambi cannot represent faithfully now raise instead of warning. Under the default non-centered parameterization, a group prior supplying a mu hyperprior cannot be represented; pass noncentered=False for that parameter to keep the prior as written.
• For unmatched group terms, HSSM now centers the generated prior even when non-centering was requested, which intentionally changes the likelihood relative to 0.4.0 by reconnecting a location that bambi previously discarded.
• hssm.load_data() now requires its dataset argument and always returns a DataFrame. Use the new hssm.list_data() to list the built-in datasets.
• ddm_sdv's approx_differentiable sv bound has widened from (0.0, 1.0) to (0.0, 2.5), matching the range its network was trained on. The bound feeds default priors and initial values, so fits of existing ddm_sdv models may differ from 0.4.0.
• prior_settings and link_settings now reject unsupported values instead of silently ignoring them.
• The ssm-simulators floor has been raised to >=0.14.0.

See the full changelog (https://lnccbrown.github.io/HSSM/changelog/) for details and migration guidance.

Reliability and compatibility improvements

• hssm.Link now constructs bambi built-in and custom links correctly, and every identity-link spelling is recognized consistently
• Safe common-intercept priors retain response-scale priors under identity links, including HDDM-derived priors
• Repeated unmatched group expressions now fail with a clear message rather than producing an ambiguous prior
• Parameterization diagnostics now describe the graph bambi actually builds
• Fixes to JAX compilation and blackbox likelihood callbacks in the sampling path
• Notebook, documentation, and lint cleanups across the tutorial set

Thank you

Thank you to the contributors, reviewers, and users who helped shape this release.

We're looking forward to seeing what you build with HSSM 0.5.0.