Metadata-Version: 2.4
Name: minisim
Version: 0.2.0
Summary: Physically-driven synthetic 1-photon miniscope data: a forward-model generator and teaching tool, the inverse of the minian analysis pipeline.
Keywords: calcium-imaging,miniscope,neuroscience,simulation,synthetic-data,benchmarking
Author-Email: Daniel Aharoni <daharoni@mednet.ucla.edu>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Project-URL: Homepage, https://github.com/miniscope/minisim
Project-URL: Documentation, https://minisim.readthedocs.io/
Project-URL: Repository, https://github.com/miniscope/minisim
Project-URL: Issues, https://github.com/miniscope/minisim/issues
Project-URL: Changelog, https://github.com/miniscope/minisim/blob/main/CHANGELOG.md
Requires-Python: >=3.10
Requires-Dist: numpy>=1.20.2
Requires-Dist: numpydantic>=1.8
Requires-Dist: opencv-python-headless>=4.6
Requires-Dist: pydantic>=2
Requires-Dist: scipy>=1.4.1
Requires-Dist: xarray>=0.17.0
Requires-Dist: zarr<3,>=2.18
Provides-Extra: notebook
Requires-Dist: ipympl>=0.10.0; extra == "notebook"
Requires-Dist: ipywidgets; extra == "notebook"
Requires-Dist: jupyter; extra == "notebook"
Requires-Dist: matplotlib; extra == "notebook"
Requires-Dist: mediapy; extra == "notebook"
Requires-Dist: tqdm; extra == "notebook"
Provides-Extra: test
Requires-Dist: minisim[notebook]; extra == "test"
Requires-Dist: pytest>=8.4.1; extra == "test"
Requires-Dist: pytest-cov>=7.1.0; extra == "test"
Requires-Dist: ruff>=0.15.14; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=8.1; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.16; extra == "docs"
Requires-Dist: myst-nb>=1.1; extra == "docs"
Requires-Dist: autodoc-pydantic>=2.2; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: sphinx-design>=0.6; extra == "docs"
Description-Content-Type: text/markdown

# minisim

[![pytest](https://github.com/miniscope/minisim/actions/workflows/testandcov.yml/badge.svg)](https://github.com/miniscope/minisim/actions/workflows/testandcov.yml)
[![codecov](https://codecov.io/gh/miniscope/minisim/branch/main/graph/badge.svg)](https://codecov.io/gh/miniscope/minisim)
[![Documentation Status](https://readthedocs.org/projects/minisim/badge/?version=latest)](https://minisim.readthedocs.io/en/latest/?badge=latest)
[![PyPI](https://img.shields.io/pypi/v/minisim.svg)](https://pypi.org/project/minisim/)
[![Python versions](https://img.shields.io/pypi/pyversions/minisim.svg)](https://pypi.org/project/minisim/)
[![License](https://img.shields.io/pypi/l/minisim.svg)](https://github.com/miniscope/minisim/blob/main/LICENSE)

**Physically-driven synthetic 1-photon miniscope data: a forward-model
generator and teaching tool.**

minisim builds a miniscope recording *forward* from its physical components, the
inverse of an analysis pipeline like [minian](https://github.com/miniscope/minian).
Instead of recovering signals from a movie, it starts from biology and optics and
produces the movie, together with the ground truth that generated it:

```
place neurons -> cell activity -> bleaching -> optics -> composite -> neuropil
             -> brain motion -> illumination profile -> vignette -> leakage -> image sensor
```

Each stage is a small, inspectable physical model. Because the recording is built
forward, every recording ships with exact ground truth (cell locations,
footprints, calcium traces, spike times, motion trajectory, per-pixel optical
fields), which makes minisim useful for:

- **Benchmarking** calcium-imaging pipelines (minian, CaImAn, suite2p, ...)
  against known ground truth.
- **Teaching** the anatomy of miniscope data: what each physical effect does to
  the image, via interactive notebooks.
- **Testing** analysis code with reproducible, parameterized fixtures.

📖 **Full documentation: [minisim.readthedocs.io](https://minisim.readthedocs.io/)** — concepts,
quickstart, how-to guides, and the API reference.

## Install

```bash
pip install minisim                # engine only
pip install "minisim[notebook]"    # + the interactive teaching notebooks
```

Requires Python >= 3.10. Core dependencies are just numpy, scipy, xarray, zarr,
pydantic, and numpydantic.

The teaching notebooks ship inside the package; list them and copy the ones you
want out to a writable directory with the bundled command:

```bash
minisim-notebooks list                  # see what's available
minisim-notebooks copy 01_anatomy       # -> ./minisim-notebooks/01_anatomy
# then: cd minisim-notebooks/01_anatomy && jupyter lab
```

## Quick start

```python
from minisim import (
    Acquisition, Optics, ImageSensor, PlaceNeurons, CellActivity,
    CellOptics, Composite, Sensor, Spec, simulate,
)

spec = Spec(
    acquisition=Acquisition(
        fps=20.0, duration_s=10.0,
        optics=Optics(magnification=8.0, na=0.45),
        image_sensor=ImageSensor(n_px_height=256, n_px_width=256, pixel_pitch_um=8.0),
    ),
    seed=0,
    steps=[
        PlaceNeurons(density_per_mm3=400000.0, soma_radius_um=4.0),
        CellActivity(),
        CellOptics(),
        Composite(),
        Sensor(),
    ],
)

rec = simulate(spec)
movie = rec.observed          # xarray DataArray (frame, height, width)
truth = rec.ground_truth      # cells, traces, spikes, optical fields
```

## Relationship to minian

minisim is the forward (generative) counterpart to minian's inverse (analysis)
pipeline. The dependency is strictly one-directional: minisim never imports
minian. minian uses minisim as a test dependency to supply ground-truth fixtures
for its recovery tests.

## License

GPL-3.0-or-later. See [LICENSE](LICENSE).
