minisim 0.1.0

Physically-driven synthetic 1-photon miniscope data: a forward-model generator and teaching tool, the inverse of the minian analysis pipeline.

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

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

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.