Metadata-Version: 2.5
Name: mtdr
Version: 0.1.0
Summary: Model-based targeted dimensionality reduction (mTDR) for neural population data
Project-URL: Homepage, https://github.com/jyanar/mtdr
Project-URL: Documentation, https://jyanar.github.io/mtdr/
Project-URL: Source, https://github.com/jyanar/mtdr
Project-URL: Issues, https://github.com/jyanar/mtdr/issues
Project-URL: Changelog, https://github.com/jyanar/mtdr/blob/main/CHANGELOG.md
Author-email: Jorge Yanar <jorgeyanar@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: dimensionality reduction,mTDR,neural population,neuroscience,reduced-rank regression
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.13
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: matplotlib>=3.9; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs<2,>=1.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'dev'
Requires-Dist: mypy==2.3.1; extra == 'dev'
Requires-Dist: pandas>=2.2.2; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.1; extra == 'dev'
Requires-Dist: ruff==0.16.9; extra == 'dev'
Requires-Dist: scipy-stubs; extra == 'dev'
Requires-Dist: xarray>=2024.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Provides-Extra: lint
Requires-Dist: mypy==2.3.1; extra == 'lint'
Requires-Dist: pre-commit>=3.7; extra == 'lint'
Requires-Dist: ruff==0.16.9; extra == 'lint'
Requires-Dist: scipy-stubs; extra == 'lint'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.9; extra == 'plot'
Provides-Extra: test
Requires-Dist: hypothesis>=6.100; extra == 'test'
Requires-Dist: matplotlib>=3.9; extra == 'test'
Requires-Dist: pandas>=2.2.2; extra == 'test'
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest>=8.1; extra == 'test'
Requires-Dist: xarray>=2024.6; extra == 'test'
Provides-Extra: xarray
Requires-Dist: pandas>=2.2.2; extra == 'xarray'
Requires-Dist: xarray>=2024.6; extra == 'xarray'
Description-Content-Type: text/markdown

# mtdr

[![CI](https://github.com/jyanar/mtdr/actions/workflows/ci.yml/badge.svg)](https://github.com/jyanar/mtdr/actions/workflows/ci.yml)

Model-based targeted dimensionality reduction (mTDR) for neural population data,
in Python.

mTDR fits trial-by-neuron-by-time activity as a sum of low-rank, time-varying
regression coefficient matrices, one per task variable, and chooses each matrix's rank
by AIC. It handles neurons that were not recorded simultaneously through a per-trial
observation mask. The package provides the estimator `mtdr.MTDR` (fixed ranks or an AIC
rank search; predict, score, project, decode), data utilities, plots (`mtdr.plot`,
optional matplotlib) and a ground-truth simulator (`mtdr.simulate`).

Documentation: <https://jyanar.github.io/mtdr/>

## Installation

```bash
pip install mtdr                  # the core
pip install "mtdr[plot,xarray]"   # with the optional extras
```

The core needs only NumPy and SciPy (Python >= 3.11). The extras are optional:

- `plot`: matplotlib, for `mtdr.plot`;
- `xarray`: xarray and pandas, for `MTDR.to_xarray` and
  `RankSearchHistory.to_frame`.

A worked example is on the documentation's
[Getting started](https://jyanar.github.io/mtdr/getting-started/) page.

## Credit

mTDR is the method of

- M. C. Aoi, V. Mante & J. W. Pillow (2020). Prefrontal cortex exhibits
  multidimensional dynamic encoding during decision-making. *Nature
  Neuroscience* 23, 1410–1420. <https://doi.org/10.1038/s41593-020-0696-5>
- M. C. Aoi & J. W. Pillow (2018). Model-based targeted dimensionality reduction
  for neuronal population data. *Advances in Neural Information Processing
  Systems* 31.

This package is a Python port of the authors' MATLAB demo,
[`pillowlab/mTDRdemo`](https://github.com/pillowlab/mTDRdemo). It is not affiliated
with or endorsed by the authors; the method and the reference implementation are
theirs. If you use it, please cite the papers above as well as this software (see
[`CITATION.cff`](https://github.com/jyanar/mtdr/blob/main/CITATION.cff)).

## How this port was developed and checked

The port was planned, implemented, and reviewed over multiple rounds with the help
of Claude Fable 5.1, Opus 5.5, and GPT 6 Astra. The general approach I took was to
implement the algorithm from the 2018 and 2020 papers while also reproducing the
output of the published MATLAB code. The scripts in 
[`tests/fixtures/matlab/`](https://github.com/jyanar/mtdr/tree/main/tests/fixtures/matlab)
run the MATLAB reference on its two demos and on simulated datasets up to the scale
of the 2020 paper, and save what it computes. Run with MATLAB's starting points and
settings, `mtdr` reproduces the reference's quantities (rank paths, LLs, coefficient
estimates, etc) within numerical tolerance. Run with the package's own defaults, which
take a slightly different optimization path, each fit must reach a likelihood at least
as good as MATLAB's.

Where the port deliberately departs from the MATLAB code (some defaults, a few fixed
bugs, SciPy's optimizers in place of `minFunc`), each difference and, where available,
a compatibility option is listed in
[`docs/differences-from-matlab.md`](https://github.com/jyanar/mtdr/blob/main/docs/differences-from-matlab.md). The model and
its estimation are described in [`docs/model.md`](https://github.com/jyanar/mtdr/blob/main/docs/model.md),
with technical appendices for the equations cited by the code.

## Development

```bash
pip install -e ".[dev]"   # the test, lint and docs tools
pre-commit install
ruff check . && ruff format --check .
mypy
pytest --cov=mtdr
mkdocs serve
```

## License

MIT (see [`LICENSE`](https://github.com/jyanar/mtdr/blob/main/LICENSE)).
