Testing helpers#

Convenience helpers for using minisim as test fixtures for an analysis pipeline. Unlike the rest of the reference, these live in the minisim.testing submodule (from minisim.testing import make_recording, score). See the how-to guide Use minisim in your test suite for the recommended pytest wiring.

make_recording#

minisim.testing.make_recording(*, n_cells=6, n_px=128, pixel_size_um=1.0, duration_s=2.0, fps=20.0, seed=0, depth_um=50.0, soma_radius_um=5.0, morphology='soma', motion=False, activity=None, sensor=None, extra_steps=(), save_intermediates=False)[source]#

A small, fast, deterministic recording with ground truth, for CI tests.

Places n_cells well-separated somata on a jittered grid at a single depth_um and runs the minimal forward chain (place_neurons → cell_activity → optics → composite → sensor) on a square n_px × n_px sensor at pixel_size_um per pixel. Cell count, positions, and every pixel are fully determined by the arguments, so the same seed (and the same arguments) always yields the same recording - the property a fixture needs.

Defaults are tuned for CI: a 128 px FOV at 1 µm/px (128 µm), six cells at 50 µm depth, two seconds at 20 fps, with a lively, brightly-exposed default activity/sensor so every placed cell reliably fires and is detectable. Shrink n_px / duration_s for an even faster fixture, or raise n_cells for a denser one.

Parameters:

  • n_cells (int) – Number of somata to place (exactly this many; grid-arranged and separated).

  • n_px (int) – Square sensor side, pixels (both height and width).

  • pixel_size_um (float) – Object-space size of one pixel, µm. Realized via a sensor pitch of 8.0 µm and a matching magnification, so the FOV is n_px · pixel_size_um.

  • duration_s (float) – Sampling and the master RNG seed.

  • fps (float) – Sampling and the master RNG seed.

  • seed (int) – Sampling and the master RNG seed.

  • depth_um (float) – Common depth of every soma below the tissue surface, µm. The focal plane is "auto", so it resolves here and the cells are in focus.

  • soma_radius_um (float) – Cell shape: "soma" (body only, fast) or "cytosolic" (soma plus proximal dendrites).

  • morphology (str) – Cell shape: "soma" (body only, fast) or "cytosolic" (soma plus proximal dendrites).

  • motion (bool) – When True, append a default BrainMotion step, so ground_truth.shifts is populated (lets you exercise motion correction).

  • activity (CellActivity | None) – Override the CellActivity model or the Sensor exposure step; None uses defaults.

  • sensor (Sensor | None) – Override the CellActivity model or the Sensor exposure step; None uses defaults.

  • extra_steps (Sequence[Annotated[PlaceNeurons | CellActivity | CellOptics | Composite | Neuropil | Vasculature | Bleaching | BrainMotion | IlluminationProfile | Vignette | Leakage | Sensor, Discriminator(discriminator=kind, custom_error_type=None, custom_error_message=None, custom_error_context=None)]]) – Additional steps to append (Neuropil, Vignette, Leakage, …); the spec re-sorts into canonical order, so order here is free.

  • save_intermediates (bool) – Persist per-stage snapshots (see Output).

Returns:

rec.observed is the movie, rec.ground_truth the exact truth.

Return type:

Recording

score#

minisim.testing.score(estimate, ground_truth, *, iou_threshold=0.5, tol_frames=2, restrict_to_detectable=True)[source]#

Score a pipeline’s Estimate against the ground truth, in one call.

Runs the standard recovery pipeline: match estimated footprints to true ones by spatial overlap (hungarian_match() against A_observed, the recoverable target), then score the temporal recovery of the matched pairs. The conventions the a-la-carte recipe asks you to remember are applied here:

  • matches against A_observed (not the optics-free A_planted);

  • scores recall over the detectable cells by default (the fair denominator; see detectable_subset());

  • reduces per-pair trace correlations with a nan-safe median;

  • treats an estimated motion trajectory as a correction (negated) when comparing to GroundTruth.shifts.

Parameters:

  • estimate (Estimate) – The pipeline output. Only Estimate.A is required.

  • ground_truth (GroundTruth) – The recording’s ground_truth.

  • iou_threshold (float) – Minimum IoU for a matched pair to count as a true positive.

  • tol_frames (int) – Spike-timing tolerance, frames (see spike_precision_recall()).

  • restrict_to_detectable (bool) – Score against detectable_subset() (default). Set False to score against every planted cell, detectable or not.

Returns:

The scorecard. Unsupplied estimate fields score nan / None.

Return type:

Report

Estimate#

class minisim.testing.Estimate(A, C=None, S=None, shifts=None)[source]#

Bases: NamedTuple

What a pipeline recovered, as the input to score().

A is the only required field. C / S / shifts are optional; when None, the matching score in the Report is nan (or None for motion). Arrays may be numpy or xarray (minian’s CNMF returns xr.DataArray); both are accepted.

  • A - spatial footprints, (n_units, height, width).

  • C - calcium traces, (n_units, frame).

  • S - deconvolved spikes, (n_units, frame).

  • shifts - estimated per-frame (dy, dx) motion, (frame, 2). A motion correction trajectory (the negation of the applied shift); score() negates it to compare against GroundTruth.shifts.

Parameters:
A: object#

Alias for field number 0

C: object | None#

Alias for field number 1

S: object | None#

Alias for field number 2

shifts: object | None#

Alias for field number 3

Report#

class minisim.testing.Report(n_true, n_est, n_matched, recall, precision, mean_iou, trace_corr, spike_precision, spike_recall, shift_rmse)[source]#

Bases: object

The recovery scorecard score() returns.

Cell counts and spatial scores are always present; temporal scores are nan when the matching estimate field was not supplied, and shift_rmse is None when motion truth or a motion estimate is absent.

Parameters:
summary()[source]#

A compact one-line-per-metric string, handy for a test failure message.

Return type:

str