glmhmmt

glmhmmt is the installable package for the Dynamax-based GLM-HMM / GLM-HMMT code.

If someone in the lab only wants to import the model class in their own code, this package is enough:

pip install "git+https://github.com/BrainCircuitsBehaviorLab/glmhmmt.git"

or with uv:

uv pip install "git+https://github.com/BrainCircuitsBehaviorLab/glmhmmt.git"

If they want to add it as a dependency in another uv project:

uv add "glmhmmt @ git+https://github.com/BrainCircuitsBehaviorLab/glmhmmt.git"

Then in Python:

from glmhmmt import SoftmaxGLMHMM

If they want the baseline GLM fit directly in their own code, including binary lapses:

from glmhmmt import fit_glm

Array-first GLM-HMM fitting

Use fit_glmhmm when choices are already encoded and the emission and transition design matrices have already been constructed by the calling analysis. The function performs no dataset loading, task resolution, feature construction, model naming, or file writing.

from glmhmmt import fit_glmhmm

fit = fit_glmhmm(
    y=choices,
    X=emission_matrix,
    U=transition_matrix,
    session_ids=session_ids,
    num_states=2,
    num_classes=2,
    emission_names=["bias", "stimulus", "choice_history"],
    transition_names=["reward_history"],
    baseline_class_idx=0,
    cv_folds=5,
    seed=0,
)

Pass U=None for a standard GLM-HMM or a (T, Q) transition matrix for a GLM-HMM-T. Cross-validation splits whole sessions and is followed by a separate fit on all trials; fold metrics are available in fit.cv_metrics. The same function is also exported as fit_hmm.

Direct Model Use

See examples/use_softmax_glmhmm.py for a minimal example that builds the model directly from arrays, without any task adapter.

For a baseline GLM example, see examples/glm_lapses/example.py.

The package root uses lazy imports, so importing SoftmaxGLMHMM does not require task adapters.

The CLI entrypoints under glmhmmt.cli.* are wrappers around task adapters, runtime paths, and result directories. They are useful for command-line workflows, but they are not the recommended import interface for another project.

Runtime Config

glmhmmt now looks for config.toml by searching upward from the current working directory. That means each analysis project can keep its own config next to its notebooks and scripts.

The clean way to initialise one is:

uv run glmhmmt-init-config

That writes config.toml in the current working directory. You can also choose the destination explicitly:

uv run glmhmmt-init-config \
  --path ./config.toml \
  --data-dir /absolute/path/to/data \
  --results-dir /absolute/path/to/results

At runtime, config precedence is:

configure_paths(...)
GLMHMMT_CONFIG_PATH
nearest config.toml found by upward search from the current working directory
repo-local config.toml for editable installs
packaged defaults in src/glmhmmt/resources/default_config.toml

Runtime Compatibility

The published package is tested against:

Python 3.11–3.13
jax==0.4.35
jaxlib==0.4.35
tensorflow-probability==0.25.0
optax==0.2.5
numpy>=2.0,<2.1

These bounds are intentionally conservative because newer JAX / TFP and NumPy combinations have broken APIs used by dynamax and glmhmmt.model.

Task Adapters Are Optional

This package does not need task adapters when someone only wants the reusable model classes and fitting utilities.

If a user wants task-aware CLIs or notebooks, they can provide adapters in either of these ways:

Put an adapters/ package in their own working directory, or configure [plugins].adapter_paths / GLMHMMT_TASK_PATHS.
Install a separate package that exposes entry points in the glmhmmt.tasks group.

Minimal entry-point example:

[project.entry-points."glmhmmt.tasks"]
my_lab_task = "my_lab_glmhmmt.task:MyLabTaskAdapter"

Recommended Sharing Workflow

For lab use, the simplest setup is:

Keep glmhmmt in its own Git repo.
Keep task adapters in a separate companion repo.
Install both from Git or from local editable paths during development.

That is usually better than publishing to PyPI immediately, because:

it avoids exposing unrelated analysis code
updates are simple
private sharing inside the lab is easy

Publish to PyPI later only if you want a public, versioned release.

Local Development

For work inside this repository:

uv sync
uv run python -c "from glmhmmt import SoftmaxGLMHMM; print(SoftmaxGLMHMM)"

If you want the notebook extras too:

uv sync --extra notebooks

The project-local runtime overrides live in config.toml. Packaged defaults live in src/glmhmmt/resources/default_config.toml.

Release files for glmhmmt 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for glmhmmt 0.4.1
File	Size	Uploaded
glmhmmt-0.4.1.tar.gz	203.7 kB	Jul 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for glmhmmt 0.4.1
File	Interpreter	ABI	Platform	Reset
glmhmmt-0.4.1-py3-none-any.whl 232.8 kB Jul 21, 2026	Python 3	none	any	Details

Total release size: 436.4 kB

Release files / glmhmmt-0.4.1.tar.gz

Download URL	glmhmmt-0.4.1.tar.gz
Size	203.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`efb2b84f46024c7e386d413b6ebc17d9b7a06428737dfc21a675dc9a97aed93f`
BLAKE2b-256 checksum How to use checksums	`bad0f55ed7b70a57b84dc2a87c16ebb4de089db5d235b5e54dc7b85d11b1d924`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/BrainCircuitsBehaviorLab/glmhmmt
Publishing commit: github.com/BrainCircuitsBehaviorLab/glmhmmt/tree/00f25bd9b745af10504fd601e28225adcc980036

Workflow

Publishing configuration: github.com/BrainCircuitsBehaviorLab/glmhmmt/blob/00f25bd9b745af10504fd601e28225adcc980036/.github/workflows/publish.yml
Publishing logs: github.com/BrainCircuitsBehaviorLab/glmhmmt/actions/runs/29824150424/attempts/1

Artifact

Subject: glmhmmt-0.4.1.tar.gz
SHA-256 checksum: efb2b84f46024c7e386d413b6ebc17d9b7a06428737dfc21a675dc9a97aed93f Verifying attestations

Release files / glmhmmt-0.4.1-py3-none-any.whl

Download URL	glmhmmt-0.4.1-py3-none-any.whl
Size	232.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e1f8877b19d068980c3448755cc97403efde2db7257dd1caa51e8e082249a521`
BLAKE2b-256 checksum How to use checksums	`3a8f6a4c4539749bffc8a2c29626a846e77b93b198548e678bb74a5d8cfc4c78`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/BrainCircuitsBehaviorLab/glmhmmt
Publishing commit: github.com/BrainCircuitsBehaviorLab/glmhmmt/tree/00f25bd9b745af10504fd601e28225adcc980036

Workflow

Publishing configuration: github.com/BrainCircuitsBehaviorLab/glmhmmt/blob/00f25bd9b745af10504fd601e28225adcc980036/.github/workflows/publish.yml
Publishing logs: github.com/BrainCircuitsBehaviorLab/glmhmmt/actions/runs/29824150424/attempts/1

Artifact

Subject: glmhmmt-0.4.1-py3-none-any.whl
SHA-256 checksum: e1f8877b19d068980c3448755cc97403efde2db7257dd1caa51e8e082249a521 Verifying attestations