Metadata-Version: 2.4
Name: multimodalsrm
Version: 0.1.0
Summary: Shared response models for native-time multimodal observations
Author: Luke J. Chang
License-Expression: MIT
Project-URL: Homepage, https://github.com/ljchang/multimodalsrm
Project-URL: Documentation, https://ljchang.github.io/multimodalsrm/
Project-URL: Repository, https://github.com/ljchang/multimodalsrm
Project-URL: Issues, https://github.com/ljchang/multimodalsrm/issues
Project-URL: Changelog, https://github.com/ljchang/multimodalsrm/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: scikit-learn>=1.4
Requires-Dist: joblib>=1.3
Requires-Dist: threadpoolctl>=3
Provides-Extra: bayesian
Requires-Dist: jax==0.11.2; extra == "bayesian"
Requires-Dist: jaxlib==0.11.2; extra == "bayesian"
Requires-Dist: numpyro==0.22.0; extra == "bayesian"
Requires-Dist: arviz==1.3.0; extra == "bayesian"
Requires-Dist: xarray>=2024.1; extra == "bayesian"
Provides-Extra: plots
Requires-Dist: matplotlib>=3.8; extra == "plots"
Provides-Extra: test
Requires-Dist: pytest>=9; extra == "test"
Requires-Dist: packaging>=24; extra == "test"
Requires-Dist: matplotlib>=3.8; extra == "test"
Requires-Dist: psutil>=5.9; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=9; extra == "dev"
Requires-Dist: packaging>=24; extra == "dev"
Requires-Dist: matplotlib>=3.8; extra == "dev"
Requires-Dist: psutil>=5.9; extra == "dev"
Requires-Dist: ruff>=0.11; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Requires-Dist: PyYAML>=6; extra == "dev"
Dynamic: license-file

# MultimodalSRM

[![CI](https://github.com/ljchang/multimodalsrm/actions/workflows/ci.yml/badge.svg)](https://github.com/ljchang/multimodalsrm/actions/workflows/ci.yml)
[![Documentation](https://img.shields.io/badge/docs-online-teal)](https://ljchang.github.io/multimodalsrm/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Shared response models for observations measured across people, modalities and native sampling times.

**Version `0.1.0`.** This package contains the extracted R-MSRM and GP-MSRM implementations. Software checks, fit convergence, uncertainty calibration and empirical recovery are separate claims.

## Models

- **R-MSRM (`MultimodalSRM`)** estimates one exact common latent response per run by default, with participant–modality mappings and regularized response kernels.
- **GP-MSRM (`BayesianMultimodalSRM`)** uses a continuous shared latent Gaussian process, individual observation mappings, explicit priors, MAP estimation and supported posterior workflows.

Both use named native-time observations, masks and missing streams. They preserve explicit information boundaries for held-out prediction. Learned FIR responses are deferred. Legacy neighborhood, graph, mixture and reference estimators are not exported by this package. See the [capability and backend matrix](docs/capabilities.md) before choosing a workflow.

## Install

Python 3.12 or later is required. Install the release from PyPI:

```sh
python -m pip install "multimodalsrm==0.1.0"
# Optional Bayesian runtime:
python -m pip install "multimodalsrm[bayesian]==0.1.0"
```

Enable float64 before using the Bayesian model (`JAX_ENABLE_X64=true`). See the [installation guide](https://ljchang.github.io/multimodalsrm/getting-started/) for environment setup.

### Development and runnable examples

The example scripts live in the source repository. From a clone:

```sh
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python examples/r_quickstart.py
```

For the optional Bayesian runtime:

```sh
python -m pip install -e '.[bayesian]'
JAX_ENABLE_X64=true JAX_PLATFORM_NAME=cpu python examples/gp_map_quickstart.py
```

The base install does not require JAX, NumPyro, ArviZ or plotting libraries. The Bayesian extra pins the runtime used by the source handoff; enabling float64 is required. Editable source installs follow the checkout; use the `v0.1.0` tag to match this release.

## Data and imports

```python
from multimodalsrm import MultimodalSRM, TimeSeries, Identity, Gaussian, Response
from multimodalsrm.bayesian import BayesianMultimodalSRM, BayesianPriors

# values: (observations, features); times: (observations,).
# Each modality retains its own timestamps. A mask marks observed entries.
# data = {participant: {run: {modality: TimeSeries(values, times, mask)}}}
```

Use consistent timestamp units across streams. Separate runs have separate latent responses; participants viewing the same run share one response. `features=K` chooses the latent dimensionality rather than estimating K. The [runnable tutorials](docs/tutorials.md) demonstrate fitting, explicit target exclusion, independent new runs and GP archive replay on small synthetic data.

## Documentation and development

- **[Read the documentation](https://ljchang.github.io/multimodalsrm/)** — installation, data preparation, model concepts, and tutorials.
- [Documentation overview](docs/index.md), [installation](docs/getting-started.md), and [model concepts](docs/concepts.md)
- [Tutorials](docs/tutorials.md) and [capabilities](docs/capabilities.md)
- [Preview and contribute to the Zensical site](docs/documentation.md)
- [Migration and archive compatibility](docs/migration.md)
- [Source integration and provenance](docs/model-integration.md)
- [CI and test policy](docs/testing.md)
- [Release setup](docs/releasing.md), [contributing](CONTRIBUTING.md) and [changelog](CHANGELOG.md)
- [Post-release Linux CPU/GPU evaluation plan](docs/superpowers/plans/2026-09-21-post-release-linux-performance-evaluation.md)
- [Prior Apple MPS feasibility findings](docs/performance/2026-09-19-apple-mps-feasibility.md)

Routine PR checks use documentation-only checks or Linux core regressions and Bayesian smoke tests, depending on the changed files. The full Linux/macOS suites and wheel/source-distribution checks run on request and before every release. See the [test policy](docs/testing.md) and current CI run for coverage and evidence. Passing CI does not certify scientific validity or authorize a new release.

## License and citation

MIT licensed; see [LICENSE](LICENSE). The implementation was extracted from Luke J. Chang's [shared-response-models](https://github.com/ljchang/shared-response-models) research repository with contributor provenance retained in the [integration record](docs/model-integration.md). Citation metadata is in [CITATION.cff](CITATION.cff). No package DOI or associated publication is claimed. Research observations and fitted archives are not distributed.
