Metadata-Version: 2.4
Name: glmhmmt
Version: 0.2.7
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.4.35
Requires-Dist: jaxlib==0.4.35
Requires-Dist: jaxtyping>=0.3.7
Requires-Dist: marimo>=0.21.1
Requires-Dist: nbformat>=5.10.4
Requires-Dist: numba>=0.63.0
Requires-Dist: numpy>=2.3.5
Requires-Dist: optax==0.2.5
Requires-Dist: pandas>=3.0.0
Requires-Dist: platformdirs>=4.5.1
Requires-Dist: plotly>=6.5.2
Requires-Dist: polars>=1.38.1
Requires-Dist: pyarrow>=20.0.0
Requires-Dist: requests>=2.32.5
Requires-Dist: scipy>=1.17.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: tensorflow-probability==0.25.0
Requires-Dist: traitlets>=5.14.3
Requires-Dist: wigglystuff>=0.3.1
Provides-Extra: notebooks
Requires-Dist: anywidget==0.10.0; 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.

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

```bash
uv run glmhmmt-init-config
```

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

```bash
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:

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

## Runtime Compatibility

The published package is tested against:

- `jax==0.4.35`
- `jaxlib==0.4.35`
- `tensorflow-probability==0.25.0`
- `optax==0.2.5`

These pins are intentionally conservative because newer JAX / TFP combinations
have broken the `tensorflow_probability.substrates.jax` import path 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:

1. Put an `adapters/` package in their own working directory, or configure `[plugins].adapter_paths` / `GLMHMMT_TASK_PATHS`.
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`.
