Metadata-Version: 2.4
Name: minisim
Version: 0.1.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: 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: 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: ipywidgets; extra == "notebook"
Requires-Dist: jupyter; extra == "notebook"
Requires-Dist: matplotlib; extra == "notebook"
Requires-Dist: mediapy; 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"
Description-Content-Type: text/markdown

# minisim

**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 -> optics -> render -> neuropil -> bleaching
             -> brain motion -> 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.

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

## Quick start

```python
from minisim import (
    Acquisition, Optics, ImageSensor, PlaceNeurons, CellActivity,
    CellOptics, Render, 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(),
        Render(),
        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).
