Metadata-Version: 2.4
Name: glmhmmt
Version: 0.1.0
Summary: GLM-HMM and GLM-HMMT tooling for behavioural task analysis.
Author-email: Javi <jrm2003@icloud.com>
Requires-Python: >=3.11
Requires-Dist: anywidget>=0.9.21
Requires-Dist: dynamax>=1.0.1
Requires-Dist: ipython>=9.10.1
Requires-Dist: jax>=0.9.0.1
Requires-Dist: jaxtyping>=0.3.7
Requires-Dist: marimo>=0.21.1
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: nbformat>=5.10.4
Requires-Dist: numba>=0.63.0
Requires-Dist: numpy>=2.3.5
Requires-Dist: optax>=0.2.7
Requires-Dist: pandas>=3.0.0
Requires-Dist: plotly>=6.5.2
Requires-Dist: polars>=1.38.1
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: scipy>=1.17.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: tfp-nightly==0.26.0.dev20260205
Requires-Dist: wigglystuff>=0.3.1
Provides-Extra: notebooks
Requires-Dist: anywidget==0.9.21; extra == 'notebooks'
Requires-Dist: marimo>=0.21.1; extra == 'notebooks'
Requires-Dist: plotly==6.5.2; extra == 'notebooks'
Requires-Dist: sbi==0.25.0; extra == 'notebooks'
Requires-Dist: scikit-learn==1.8.0; extra == 'notebooks'
Requires-Dist: torch==2.5.1; extra == 'notebooks'
Requires-Dist: traitlets==5.14.3; extra == 'notebooks'
Requires-Dist: wigglystuff==0.3.1; extra == 'notebooks'
Description-Content-Type: text/markdown

# 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:

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

or with `uv`:

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

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

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

Then in Python:

```python
from glmhmmt import SoftmaxGLMHMM
```

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

```python
from glmhmmt import fit_glm
```

## Direct Model Use

See [`examples/use_softmax_glmhmm.py`](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`](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.

## 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:

1. Put a `tasks/` package in their own working directory and point `GLMHMMT_TASK_PATHS` at it.
2. Install a separate package that exposes entry points in the `glmhmmt.tasks` group.

Minimal entry-point example:

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

## Recommended Sharing Workflow

For lab use, the simplest setup is:

1. Keep `glmhmmt` in its own Git repo.
2. Keep task adapters in a separate companion repo.
3. 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:

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

If you want the notebook extras too:

```bash
uv sync --extra notebooks
```

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