Presets and build_spec#

Named, realistic starting points for a recording, and the composer that turns them into a Spec. A scope and a region are the two orthogonal halves of a recording’s physical setup; this module names the common ones so a test or a notebook can grab a validated starting point in one line instead of hand-tuning a dozen fields.

Scope, Region, and build_spec are importable from the top level (from minisim import Scope, Region, build_spec); the named factory functions live in the minisim.presets submodule.

Scope#

A scope is the measurable hardware - objective optics plus image sensor - and the instrument-fixed effects that ride with it: the excitation illumination falloff, the collection-side vignette, the stray-light leakage glow, and the rig’s typical photons_per_unit exposure. Everything here is independent of the tissue you point it at.

pydantic model minisim.Scope[source]#

Bases: _Base

A miniscope’s measurable hardware: objective optics + image sensor.

The reusable physical front-end - everything independent of the tissue you image. Besides the objective optics and the bare image_sensor, a scope carries its own static field signature: the excitation-side illumination falloff, the collection-side vignette, and the stray-light leakage glow - all fixed to the instrument, not the tissue (None to omit any). photons_per_unit is the rig’s typical exposure/flux scale (excitation power x integration time), the brightness build_spec() gives the sensor by default. focal_depth_in_tissue_um and front_working_distance_um are the two acquisition-level fields that travel with the scope rather than the region. Compose with a Region via build_spec().

Fields:

  • focal_depth_in_tissue_um (float | Literal['auto'])

  • front_working_distance_um (float | None)

  • illumination (minisim.spec.IlluminationProfile | None)

  • image_sensor (minisim.spec.ImageSensor)

  • leakage (minisim.spec.Leakage | None)

  • optics (minisim.spec.Optics)

  • photons_per_unit (float)

  • vignette (minisim.spec.Vignette | None)

field optics: Optics [Required]#

Objective optics (NA, magnification, emission).

field image_sensor: ImageSensor [Required]#

The bare image sensor (pixel count/pitch, QE, noise, bit depth).

field illumination: IlluminationProfile | None = None#

Excitation-side illumination falloff (center-bright LED), or None.

field vignette: Vignette | None = None#

Collection-side emission vignette, or None.

field leakage: Leakage | None = None#

Additive stray-light leakage glow, or None.

field photons_per_unit: float = 100.0#

The rig’s typical exposure/flux scale; the default brightness build_spec gives the sensor.

Constraints:

  • gt = 0

field focal_depth_in_tissue_um: FocalDepth = 'auto'#

Focal-plane depth into tissue, µm, or ‘auto’ (median cell depth).

field front_working_distance_um: float | None = None#

Front working distance (lens front → focal point), µm; informational.

minisim.presets.miniscope_v4()[source]#

UCLA Miniscope V4: NA 0.3 GRIN, 608×608 px at 4.8 µm pitch, ~1.0 mm FOV.

Confirmed V4 numbers (D. Aharoni): magnification 2.9 so the sensor sees a ~1.0 mm field of view, 525 nm GCaMP emission, a ~2500 µm field-curvature radius, an 8-bit sensor ADC, and a 700 µm front working distance. The scope also carries the V4’s characteristic static field signature - a gentle center-bright excitation glow, a moderate emission vignette, and a soft stray-light leakage - plus a bright deep-tissue exposure, so a build_spec() recording reproduces the V4 look without hand-adding it. The focal plane defaults to "auto" (tracks the placed layer), as the anatomy notebook does. The remaining sensor-noise fields (QE, read noise, gain) are left at the library defaults until measured V4 values land.

Return type:

Scope

minisim.presets.generic_1p()[source]#

A neutral generic 1-photon scope - the library default optics and sensor.

NA 0.45, magnification 8×, 256×256 px at 3.0 µm pitch (a small ~96 µm FOV). A convenient, fast neutral baseline when the specific instrument does not matter; use miniscope_v4() for a realistic V4 setup.

Return type:

Scope

Region#

A region is the biology a scope is pointed at: the cell population (depth, density, morphology), the depth-dependent tissue scatter, the diffuse neuropil haze from the surrounding dendritic/axonal felt, and the region’s characteristic dark-vessel vasculature confound.

pydantic model minisim.Region[source]#

Bases: _Base

A standard imaging target: cell population + tissue scatter + vessels.

The biology half of a recording - what a Scope is pointed at. population carries the cell distribution (depth range, density, morphology); tissue the depth-dependent scatter; neuropil the diffuse background haze from the surrounding dendritic/axonal felt, or None for a clean background; vasculature the region’s characteristic dark-vessel confound, or None for no vessels. Compose with a scope via build_spec().

Fields:

  • neuropil (minisim.spec.Neuropil | None)

  • population (minisim.spec.NeuronPopulation)

  • tissue (minisim.spec.Tissue)

  • vasculature (minisim.spec.Vasculature | None)

field population: NeuronPopulation [Required]#

The cell distribution to place (depth, density, morphology).

field tissue: Tissue [Required]#

Depth-dependent light scatter of the imaged tissue.

field neuropil: Neuropil | None = None#

Diffuse background haze from the surrounding felt, or None.

field vasculature: Vasculature | None = None#

The region’s dark-vessel confound, or None.

minisim.presets.ca1()[source]#

Hippocampal CA1 imaged through an implanted GRIN lens.

CA1 reads as a thin pyramidal band: cytosolic GCaMP somata (radius ~5 µm) at ~45000 cells/mm³ over a ~140-160 µm slab (the anatomy notebook’s CA1 preset). Neuropil haze is moderate: the imaged band is the densely-packed pyramidal soma layer, with most of the dendritic/axonal felt in the adjacent strata (radiatum/oriens) outside the thin imaged slab. Vasculature is on but less pronounced than cortex - thinner, lower-contrast vessels just above the pyramidal band (D. Aharoni).

Return type:

Region

minisim.presets.cortex_l23()[source]#

Neocortex layer 2/3 (standard cytosolic GCaMP).

L2/3 excitatory cells: cytosolic GCaMP somata (radius ~6 µm), sparsely labeled (~8000 cells/mm³) and spread through a deeper, thicker 100-200 µm band than CA1, so depth-dependent scatter and defocus matter more. Neuropil haze is prominent: the imaged band is dense with dendrites and axons woven among the sparse somata, so the diffuse background reads strongly relative to the cells. Vasculature is thick and on top of the cells (D. Aharoni): a shallow layer of large-caliber, high-contrast vessels above the imaged band.

Return type:

Region

Compose with build_spec#

build_spec assembles any scope × any region into a validated Spec. It builds the Acquisition from the scope’s optics/sensor and the region’s tissue, then the forward chain place_neurons → cell_activity → optics → composite, and appends the region’s neuropil and vasculature, the scope’s static fields (illumination, vignette, leakage), and a sensor exposed at the scope’s photons_per_unit - each gated by an include_* toggle so you can drop any of them for a clean baseline. Swap the scope or region independently, override the rest with sweep(), or hand-place cells via the populations argument.

minisim.build_spec(scope, region, *, duration_s=150.0, fps=20.0, seed=0, populations=None, activity=None, sensor=None, extra_steps=(), include_neuropil=True, include_vasculature=True, include_scope_fields=True, save_intermediates=False)[source]#

Assemble a validated Spec from a scope × a region.

Builds the Acquisition from the scope’s optics/sensor and the region’s tissue, then the minimal forward chain (place_neurons → cell_activity → optics → composite → sensor) plus the region’s neuropil and vasculature and the scope’s static fields (illumination, vignette, leakage) when present. The result is a real frozen Spec: drop it into simulate(), or pass it to sweep() as the base for a parameter grid.

Parameters:

  • scope (Scope) – The two halves to compose; see miniscope_v4() / ca1() etc.

  • region (Region) – The two halves to compose; see miniscope_v4() / ca1() etc.

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

  • populations (Sequence[NeuronPopulation] | None) – Override the region’s cell distribution - e.g. a hand-placed pair of overlapping cells (a list of NeuronPopulation with explicit positions_um). None uses the region’s own population.

  • activity (CellActivity | None) – The CellActivity model; None uses its defaults.

  • sensor (Sensor | None) – The Sensor exposure step; None uses the scope’s own photons_per_unit exposure (V4 ≈ 600 for a bright deep-tissue field, the generic scope 100). Pass an explicit Sensor(...) to override.

  • 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)]]) – Steps the scope/region do not already supply - typically BrainMotion or Bleaching (the region’s neuropil/vasculature and the scope’s illumination/vignette/leakage come in automatically; see the include_* toggles). The Spec re-sorts into canonical pipeline order, so order here is free, and a duplicate kind raises.

  • include_neuropil (bool) – When False, drop the region’s neuropil haze (a clean, background-free movie). Ignored when the region has no neuropil.

  • include_vasculature (bool) – When False, drop the region’s vessel layer (a clean, vessel-free movie). Ignored when the region has no vasculature.

  • include_scope_fields (bool) – When False, drop the scope’s static fields (illumination, vignette, leakage) for a flat-field, glow-free movie. Ignored for a scope that sets none of them.

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

Returns:

Validated end to end - an impossible combination (a soma larger than the FOV, say) raises here, at build time.

Return type:

Spec

Example#

from minisim import build_spec, simulate
from minisim.presets import miniscope_v4, ca1

# a Miniscope V4 imaging hippocampal CA1, full V4 look (illumination, vignette,
# leakage, neuropil, vasculature) included by default
spec = build_spec(miniscope_v4(), ca1(), duration_s=30.0, seed=0)
rec = simulate(spec)

# a clean, confound-free baseline of the same anatomy
clean = build_spec(
    miniscope_v4(), ca1(),
    include_neuropil=False, include_vasculature=False, include_scope_fields=False,
)