calab¶

CaLab: calcium imaging analysis tools — deconvolution and data preparation.

Attributes¶

`DriftModel`
`SpikeModel`

Classes¶

`BiexpFitResult`	Result from bi-exponential kernel fitting.
`CaDeconResult`	Full result from CaDecon (automated deconvolution via InDeCa algorithm).
`CellGroundTruth`	Ground truth for a single simulated cell.
`DeconConfig`	Configuration for automated CaDecon deconvolution via the bridge.
`DeconvolutionResult`	Full result from FISTA deconvolution.
`HeadlessBrowser`	Manages a Playwright browser for headless CaDecon / CaTune runs.
`KernelConfig`	Double-exponential kernel: h(t) = exp(-t/tau_decay) - exp(-t/tau_rise).
`MarkovConfig`	Two-state HMM spike generator (silent/active) with bursty firing.
`NoiseConfig`	Noise model: Gaussian + optional Poisson (shot) noise.
`PhotobleachingConfig`	Exponential photobleaching: `F(t) = 1 - amp (1 - exp(-t/tau))`.
`PoissonConfig`	Homogeneous Poisson spike generator.
`RandomWalkDrift`	Mean-reverting Gaussian random walk baseline drift (default).
`SaturationConfig`	Hill equation indicator saturation: F_sat = F^n / (F^n + Kd^n).
`SimulationConfig`	Complete configuration for synthetic calcium trace generation.
`SimulationResult`	Complete simulation result with observed traces and per-cell ground truth.
`SinusoidalDrift`	Deterministic sinusoidal baseline drift.
`SolveTraceResult`	Result from a single-trace InDeCa solve.
`presets`	Built-in indicator presets. Each method returns a SimulationConfig.

Functions¶

`bandpass_filter`(→ numpy.ndarray)	Apply FFT bandpass filter derived from kernel time constants. Delegates to Rust.
`build_kernel`(→ numpy.ndarray)	Build double-exponential calcium kernel. Delegates to Rust.
`compute_lipschitz`(→ float)	Compute Lipschitz constant. Delegates to Rust.
`compute_upsample_factor`(→ int)	Compute the upsample factor for a given sampling rate and target. Delegates to Rust.
`decon`(→ calab._compute.CaDeconResult \| None)	Open CaDecon in the browser for automated deconvolution.
`deconvolve_from_export`(traces, params_path[, return_full])	Run deconvolution using parameters from a CaTune export JSON.
`estimate_kernel`(→ numpy.ndarray)	Estimate a free-form kernel from traces and spike trains. Delegates to Rust.
`fit_biexponential`(→ BiexpFitResult)	Fit a bi-exponential model to a free-form kernel. Delegates to Rust.
`load_caiman`(→ tuple[numpy.ndarray, dict])	Load traces from a CaImAn HDF5 results file.
`load_export_params`(→ dict)	Load deconvolution parameters from a CaTune export JSON.
`load_minian`(→ tuple[numpy.ndarray, dict])	Load traces from a Minian Zarr output directory.
`load_tuning_data`(→ tuple[numpy.ndarray, dict])	Load calcium traces and metadata saved by `save_for_tuning()`.
`run_deconvolution`(→ numpy.ndarray)	Run FISTA deconvolution on one or more calcium traces.
`run_deconvolution_full`(→ DeconvolutionResult)	Run FISTA deconvolution returning full results.
`save_for_tuning`(→ None)	Save calcium traces in CaTune-compatible format.
`simulate`(→ SimulationResult)	Generate synthetic calcium imaging traces with full ground truth.
`solve_trace`(→ SolveTraceResult)	Run the InDeCa pipeline on a single trace. Delegates to Rust.
`tau_to_ar2`(→ tuple[float, float, float, float])	Derive AR(2) coefficients from tau parameters.
`tune`(→ dict \| None)	Open CaTune in the browser for interactive parameter tuning.

Package Contents¶

class calab.BiexpFitResult¶

Bases: NamedTuple

Result from bi-exponential kernel fitting.

tau_rise¶

Slow-component rise time constant (seconds).

Type:: float

tau_decay¶

Slow-component decay time constant (seconds).

Type:: float

beta¶

Slow-component amplitude.

Type:: float

residual¶

Fit residual (lower is better).

Type:: float

tau_rise_fast¶

Fast-component rise time constant (seconds), 0 if single-component.

Type:: float

tau_decay_fast¶

Fast-component decay time constant (seconds), 0 if single-component.

Type:: float

beta_fast¶

Fast-component amplitude, 0 if single-component.

Type:: float

beta: float¶

beta_fast: float¶

residual: float¶

tau_decay: float¶

tau_decay_fast: float¶

tau_rise: float¶

tau_rise_fast: float¶

class calab.CaDeconResult¶

Bases: NamedTuple

Full result from CaDecon (automated deconvolution via InDeCa algorithm).

activity¶

Deconvolved activity matrix, shape (n_cells, n_timepoints), float32.

Type:: np.ndarray

alphas¶

Per-cell scaling factors, shape (n_cells,), float64.

Type:: np.ndarray

baselines¶

Per-cell baseline estimates, shape (n_cells,), float64.

Type:: np.ndarray

pves¶

Per-cell proportion of variance explained, shape (n_cells,), float64.

Type:: np.ndarray

kernel_slow¶

Slow biexponential kernel waveform, float32.

Type:: np.ndarray

kernel_fast¶

Fast biexponential kernel waveform, float32 (empty if single-component).

Type:: np.ndarray

fs¶

Sampling rate in Hz.

Type:: float

metadata¶

Extensible dict with biexp params, convergence info, h_free, etc.

Type:: dict

activity: numpy.ndarray¶

alphas: numpy.ndarray¶

baselines: numpy.ndarray¶

fs: float¶

kernel_fast: numpy.ndarray¶

kernel_slow: numpy.ndarray¶

metadata: dict¶

pves: numpy.ndarray¶

class calab.CellGroundTruth¶

Bases: pydantic.BaseModel

Ground truth for a single simulated cell.

alpha: float¶

clean_calcium: numpy.ndarray¶

model_config¶

snr: float¶

spikes: numpy.ndarray¶

tau_decay_s: float¶

tau_rise_s: float¶

class calab.DeconConfig¶

Bases: pydantic.BaseModel

Configuration for automated CaDecon deconvolution via the bridge.

Fields map 1:1 to the BridgeConfig TypeScript interface in @calab/io. Only autorun is always serialized; all other fields use exclude_none=True so absent values fall through to browser defaults.

aspect_ratio: float | None¶

autorun: bool¶

convergence_tol: float | None¶

hp_filter_enabled: bool | None¶

lp_filter_enabled: bool | None¶

max_iterations: int | None¶

num_subsets: int | None¶

seed: int | None¶

target_coverage: float | None¶

upsample_target: int | None¶

class calab.DeconvolutionResult¶

Bases: NamedTuple

Full result from FISTA deconvolution.

activity¶

Non-negative deconvolved activity estimates, same shape as input traces.

Type:: np.ndarray

baseline¶

Estimated scalar baseline (per-trace if multi-trace input).

Type:: float | np.ndarray

reconvolution¶

K*activity + baseline, the model fit to the trace.

Type:: np.ndarray

iterations¶

Number of FISTA iterations run (per-trace if multi-trace input).

Type:: int | np.ndarray

converged¶

Whether convergence criterion was met (per-trace if multi-trace input).

Type:: bool | np.ndarray

activity: numpy.ndarray¶

baseline: float | numpy.ndarray¶

converged: bool | numpy.ndarray¶

iterations: int | numpy.ndarray¶

reconvolution: numpy.ndarray¶

class calab.HeadlessBrowser(*, visible: bool = False)¶

Manages a Playwright browser for headless CaDecon / CaTune runs.

Can be used as a context manager for single runs, or kept alive across multiple decon() / tune() calls for batch processing.

Examples

Single run:

with HeadlessBrowser() as hb:
    result = calab.decon(traces, fs, headless=hb, autorun=True)

Batch (reuses browser across datasets):

with HeadlessBrowser() as hb:
    for traces in datasets:
        result = calab.decon(traces, fs, headless=hb, autorun=True)

close() → None¶

Shut down page, context, browser, and Playwright.

Each teardown runs in its own try/except so a crashed browser (where context.close() raises) still lets browser.close() and pw.stop() run. Without this, a single teardown error would leak the remaining resources — most visibly an orphaned Chromium process that lingers until the Python process exits.

navigate(url: str) → None¶

Navigate the managed page to url.

If the page is already on a different URL, it navigates there (effectively reusing the same tab).

start() → None¶

Launch the browser. Called automatically by __enter__.

If any initialization step raises after earlier steps succeeded, close() runs before re-raising. This prevents partial-init failures (e.g. Chromium launch fails after the Playwright driver started) from leaking driver processes and Chromium instances across retries.

property is_alive: bool¶: Whether the browser is still connected.

property page: playwright.sync_api.Page¶: The managed Playwright Page (raises if not started).

class calab.KernelConfig¶

Bases: pydantic.BaseModel

Double-exponential kernel: h(t) = exp(-t/tau_decay) - exp(-t/tau_rise).

Attribution: standard calcium response model (CaImAn, Suite2p, CaLab).

tau_decay_cv: float¶

tau_decay_s: float¶

tau_rise_cv: float¶

tau_rise_s: float¶

class calab.MarkovConfig¶

Bases: pydantic.BaseModel

Two-state HMM spike generator (silent/active) with bursty firing.

Attribution: CaLab web simulator Markov spike model.

model_type: Literal['markov'] = 'markov'¶

p_active_to_silent: float¶

p_silent_to_active: float¶

p_silent_to_active_cv: float¶

p_spike_when_active: float¶

p_spike_when_silent: float¶

class calab.NoiseConfig¶

Bases: pydantic.BaseModel

Noise model: Gaussian + optional Poisson (shot) noise.

Attribution: Gaussian from CaLab web simulator. Shot noise from CASCADE (Rupprecht et al., 2021).

shot_noise_enabled: bool¶

shot_noise_fraction: float¶

snr: float¶

snr_spread: float¶

class calab.PhotobleachingConfig¶

Bases: pydantic.BaseModel

Exponential photobleaching: F(t) *= 1 - amp * (1 - exp(-t/tau)).

Attribution: NAOMi (Charles et al., 2019).

amplitude_cv: float¶

amplitude_fraction: float¶

decay_time_constant_s: float¶

enabled: bool¶

class calab.PoissonConfig¶

Bases: pydantic.BaseModel

Homogeneous Poisson spike generator.

Attribution: standard model in OASIS (Friedrich et al., 2017) and CaImAn (Giovannucci et al., 2019).

model_type: Literal['poisson'] = 'poisson'¶

rate_hz: float¶

class calab.RandomWalkDrift¶

Bases: pydantic.BaseModel

Mean-reverting Gaussian random walk baseline drift (default).

Models slow irregular baseline fluctuations from tissue movement, focus drift, and neuropil signal changes. From MLspike (Deneux et al., 2016, Nature Communications).

mean_reversion: float¶

model_type: Literal['random_walk'] = 'random_walk'¶

step_std_cv: float¶

step_std_fraction: float¶

class calab.SaturationConfig¶

Bases: pydantic.BaseModel

Hill equation indicator saturation: F_sat = F^n / (F^n + Kd^n).

Attribution: MLspike (Deneux et al., 2016).

enabled: bool¶

hill_coefficient: float¶

k_d: float¶

k_d_cv: float¶

class calab.SimulationConfig¶

Bases: pydantic.BaseModel

Complete configuration for synthetic calcium trace generation.

Per-cell variation (_cv fields) live on each config struct alongside the nominal value they modify. Alpha is here because it doesn’t belong to any pipeline step.

alpha_cv: float¶

alpha_mean: float¶

drift: DriftModel¶

fs_hz: float¶

kernel: KernelConfig¶

noise: NoiseConfig¶

num_cells: int¶

num_timepoints: int¶

photobleaching: PhotobleachingConfig¶

saturation: SaturationConfig¶

seed: int¶

spike_model: SpikeModel¶

spike_sim_hz: float¶

class calab.SimulationResult¶

Bases: pydantic.BaseModel

Complete simulation result with observed traces and per-cell ground truth.

config: SimulationConfig¶

ground_truth: list[CellGroundTruth]¶

model_config¶

traces: numpy.ndarray¶

class calab.SinusoidalDrift¶

Bases: pydantic.BaseModel

Deterministic sinusoidal baseline drift.

Useful as a simple test signal but not physically motivated.

amplitude_cv: float¶

amplitude_fraction: float¶

cycles_max: float¶

cycles_min: float¶

model_type: Literal['sinusoidal'] = 'sinusoidal'¶

class calab.SolveTraceResult¶

Bases: NamedTuple

Result from a single-trace InDeCa solve.

s_counts¶

Spike counts at the original sampling rate, shape (n_timepoints,), float32.

Type:: np.ndarray

alpha¶

Amplitude scaling factor.

Type:: float

baseline¶

Estimated baseline.

Type:: float

threshold¶

Spike threshold used.

Type:: float

pve¶

Proportion of variance explained (0–1).

Type:: float

iterations¶

Number of FISTA iterations run.

Type:: int

converged¶

Whether the solver converged.

Type:: bool

alpha: float¶

baseline: float¶

converged: bool¶

iterations: int¶

pve: float¶

s_counts: numpy.ndarray¶

threshold: float¶

class calab.presets¶

Built-in indicator presets. Each method returns a SimulationConfig.

static clean(**overrides: object) → SimulationConfig¶: Near-ideal traces: minimal noise, no drift. For algorithm debugging.

static gcamp6f(**overrides: object) → SimulationConfig¶: GCaMP6f. Time constants from Chen et al., 2013, Nature.

static gcamp6m(**overrides: object) → SimulationConfig¶: GCaMP6m. Moderate kinetics. Chen et al., 2013.

static gcamp6s(**overrides: object) → SimulationConfig¶: GCaMP6s. Slow kinetics, high SNR. Chen et al., 2013.

static jgcamp8f(**overrides: object) → SimulationConfig¶: jGCaMP8f. Fast indicator, noisier. Zhang et al., 2023.

static ogb1(**overrides: object) → SimulationConfig¶: OGB-1 synthetic dye. Stosiek et al., 2003.

calab.bandpass_filter(trace: numpy.ndarray, tau_rise: float, tau_decay: float, fs: float) → numpy.ndarray¶: Apply FFT bandpass filter derived from kernel time constants. Delegates to Rust.

calab.build_kernel(tau_rise: float, tau_decay: float, fs: float) → numpy.ndarray¶: Build double-exponential calcium kernel. Delegates to Rust.

calab.compute_lipschitz(kernel: numpy.ndarray) → float¶: Compute Lipschitz constant. Delegates to Rust.

calab.compute_upsample_factor(fs: float, target_fs: float) → int¶

Compute the upsample factor for a given sampling rate and target. Delegates to Rust.

Parameters:

fs (float) – Original sampling rate in Hz.
target_fs (float) – Target sampling rate in Hz.

Returns:

Upsampling multiplier (>= 1).

Return type:

int

Open CaDecon in the browser for automated deconvolution.

Starts a localhost HTTP server serving the provided traces, opens CaDecon with a ?bridge= parameter pointing to the server, and waits for the browser to export deconvolution results back.

Parameters:

traces (np.ndarray) – Calcium traces, shape (n_cells, n_timepoints) or (n_timepoints,).
fs (float) – Sampling rate in Hz. Default: 30.0.
timeout (float, optional) – Seconds to wait for results. None = wait forever (until Ctrl-C).
port (int, optional) – Port to bind to. None = auto-assign.
app_url (str, optional) – Override CaDecon URL (for local dev). Default: GitHub Pages.
open_browser (bool) – Whether to auto-open the browser. Default: True.
headless (HeadlessBrowser or bool or None) – None/False: default (use webbrowser.open). True: create a temporary headless browser for this call. HeadlessBrowser: reuse an existing browser instance (for batch).
autorun (bool) – If True, the solver starts automatically after loading. Default: False.
upsample_target (int, optional) – Target sampling rate for upsampling. Must be > 0.
hp_filter_enabled (bool, optional) – Enable high-pass filter.
lp_filter_enabled (bool, optional) – Enable low-pass filter.
max_iterations (int, optional) – Maximum solver iterations (1–200).
convergence_tol (float, optional) – Convergence tolerance (0–1 exclusive).
num_subsets (int, optional) – Number of random subsets. Must be > 0.
target_coverage (float, optional) – Target coverage fraction (0–1].
aspect_ratio (float, optional) – Subset aspect ratio. Must be > 0.
seed (int, optional) – Random seed for subset placement.

Returns:

Deconvolution results if received, None if timeout/cancelled.

Return type:

CaDeconResult or None

calab.deconvolve_from_export(traces: numpy.ndarray, params_path: str | pathlib.Path, return_full: bool = False)¶

Run deconvolution using parameters from a CaTune export JSON.

Loads parameters via load_export_params(), optionally applies the bandpass filter, and runs FISTA deconvolution.

Parameters:

traces (np.ndarray) – Calcium traces, shape (n_timepoints,) or (n_cells, n_timepoints).
params_path (str or Path) – Path to the CaTune export JSON file.
return_full (bool, optional) – If True, return a DeconvolutionResult namedtuple. Default False returns just the activity array.

Returns:

Deconvolved activity (or full result if return_full=True).

Return type:

np.ndarray or DeconvolutionResult

calab.estimate_kernel(traces_flat: numpy.ndarray, spikes_flat: numpy.ndarray, trace_lengths: numpy.ndarray, alphas: numpy.ndarray, baselines: numpy.ndarray, kernel_length: int, *, max_iters: int = 200, tol: float = 0.0001, warm_kernel: numpy.ndarray | None = None, smooth_lambda: float = 0.0) → numpy.ndarray¶

Estimate a free-form kernel from traces and spike trains. Delegates to Rust.

Parameters:

traces_flat (np.ndarray) – Concatenated 1-D traces (all cells flattened).
spikes_flat (np.ndarray) – Concatenated 1-D spike trains (matching traces_flat).
trace_lengths (np.ndarray) – Length of each individual trace in the flat arrays.
alphas (np.ndarray) – Per-trace amplitude scaling factors.
baselines (np.ndarray) – Per-trace baseline estimates.
kernel_length (int) – Desired output kernel length in samples.
max_iters (int) – Maximum FISTA iterations for kernel estimation.
tol (float) – Convergence tolerance.
warm_kernel (np.ndarray, optional) – Kernel from a previous iteration for warm-start.
smooth_lambda (float) – Total-variation smoothness penalty weight.

Returns:

Estimated free-form kernel, shape (kernel_length,), float32.

Return type:

np.ndarray

calab.fit_biexponential(h_free: numpy.ndarray, fs: float, *, refine: bool = True, skip: int = 0, warm: BiexpFitResult | None = None) → BiexpFitResult¶

Fit a bi-exponential model to a free-form kernel. Delegates to Rust.

Parameters:

h_free (np.ndarray) – Free-form kernel (1-D).
fs (float) – Sampling rate in Hz.
refine (bool) – Whether to refine with a fast (second) component.
skip (int) – Number of leading samples to skip in the fit.
warm (BiexpFitResult, optional) – Previous fit result for warm-start.

Return type:

BiexpFitResult

calab.load_caiman(path: str, trace_key: str = 'estimates/C', fs_key: str = 'params/data/fr', fs: float | None = None) → tuple[numpy.ndarray, dict]¶

Load traces from a CaImAn HDF5 results file.

Parameters:

path (str) – Path to the CaImAn HDF5 file (e.g., caiman_results.hdf5).
trace_key (str) – HDF5 key for the traces array. Default: "estimates/C".
fs_key (str) – HDF5 key for the sampling rate. Default: "params/data/fr".
fs (float, optional) – Override sampling rate. If provided, fs_key is ignored.

Returns:

traces (np.ndarray) – Traces array, shape (n_cells, n_timepoints), dtype float64.
metadata (dict) – Metadata dict with keys: source, sampling_rate_hz, num_cells, num_timepoints.

Raises:

ImportError – If h5py is not installed.
FileNotFoundError – If the HDF5 file does not exist.
KeyError – If trace_key is not found in the file.

calab.load_export_params(path: str | pathlib.Path) → dict¶

Load deconvolution parameters from a CaTune export JSON.

Parses the JSON export schema 1.1.0 (defined in src/lib/export.ts) and returns the parameters needed for deconvolution.

Parameters:

path (str or Path) – Path to the CaTune export JSON file.

Returns:

Dictionary with keys: tau_rise, tau_decay, lambda_, fs, filter_enabled.

Return type:

dict

Raises:

FileNotFoundError – If the JSON file does not exist.
KeyError – If required parameter fields are missing.

calab.load_minian(path: str, trace_key: str = 'C', fs: float | None = None) → tuple[numpy.ndarray, dict]¶

Load traces from a Minian Zarr output directory.

Parameters:

path (str) – Path to the Minian Zarr directory (e.g., minian_output/).
trace_key (str) – Zarr key for the traces array. Default: "C".
fs (float, optional) – Sampling rate in Hz. Minian does not store this, so it must be provided (or will default to None in metadata).

Returns:

traces (np.ndarray) – Traces array, shape (n_cells, n_timepoints), dtype float64.
metadata (dict) – Metadata dict with keys: source, sampling_rate_hz, num_cells, num_timepoints.

Raises:

ImportError – If zarr is not installed.
FileNotFoundError – If the Zarr directory does not exist.
KeyError – If trace_key is not found in the store.

calab.load_tuning_data(path: str | pathlib.Path) → tuple[numpy.ndarray, dict]¶

Load calcium traces and metadata saved by save_for_tuning().

Parameters:

path (str or Path) – Path stem (without extension), matching the path argument used in save_for_tuning().

Returns:

traces (np.ndarray) – Loaded traces array, dtype float64.
metadata (dict) – Metadata from the JSON sidecar.

Raises:

FileNotFoundError – If either {path}.npy or {path}_metadata.json is missing.

calab.run_deconvolution(traces: numpy.ndarray, fs: float, tau_r: float, tau_d: float, lam: float, max_iters: int = 2000, conv_mode: str = 'fft', constraint: str = 'nonneg') → numpy.ndarray¶

Run FISTA deconvolution on one or more calcium traces.

Delegates to the Rust solver via calab._solver.

Parameters:

traces (np.ndarray) – Input traces, shape (n_timepoints,) for a single trace or (n_cells, n_timepoints) for multiple traces.
fs (float) – Sampling rate in Hz.
tau_r (float) – Rise time constant in seconds.
tau_d (float) – Decay time constant in seconds.
lam (float) – L1 penalty (sparsity regularization strength).
max_iters (int, optional) – Maximum number of FISTA iterations, by default 2000.
conv_mode (str, optional) – Convolution mode: 'fft' (default) or 'banded' (O(T) AR2).
constraint (str, optional) – Constraint type: 'nonneg' (default, L1 + non-negative) or 'box01' (box constraint [0, 1], no L1 penalty).

Returns:

Non-negative activity estimates, same shape as input traces.

Return type:

np.ndarray

calab.run_deconvolution_full(traces: numpy.ndarray, fs: float, tau_r: float, tau_d: float, lam: float, max_iters: int = 2000, conv_mode: str = 'fft', constraint: str = 'nonneg') → DeconvolutionResult¶

Run FISTA deconvolution returning full results.

Parameters:

traces (np.ndarray) – Input traces, shape (n_timepoints,) for a single trace or (n_cells, n_timepoints) for multiple traces.
fs (float) – Sampling rate in Hz.
tau_r (float) – Rise time constant in seconds.
tau_d (float) – Decay time constant in seconds.
lam (float) – L1 penalty (sparsity regularization strength).
max_iters (int, optional) – Maximum number of FISTA iterations, by default 2000.
conv_mode (str, optional) – Convolution mode: 'fft' (default) or 'banded' (O(T) AR2).
constraint (str, optional) – Constraint type: 'nonneg' (default, L1 + non-negative) or 'box01' (box constraint [0, 1], no L1 penalty).

Returns:

Namedtuple with fields: activity, baseline, reconvolution, iterations, converged.

Return type:

DeconvolutionResult

calab.save_for_tuning(traces: numpy.ndarray, fs: float, path: str | pathlib.Path, metadata: dict | None = None) → None¶

Save calcium traces in CaTune-compatible format.

Creates two files:

{path}.npy – Float64 array, shape (n_cells, n_timepoints), C-contiguous, little-endian (<f8).
{path}_metadata.json – JSON sidecar with sampling rate, schema version, dimensions, and optional user metadata.

The .npy file is loadable by CaTune’s browser .npy parser, which expects dtype='<f8' and fortran_order=False.

Converting from CaImAn (users have h5py):

import h5py
import calab

with h5py.File("caiman_results.hdf5", "r") as f:
    traces = f["estimates/C"][:]       # shape: (n_cells, n_timepoints)
    fs = float(f["params/data/fr"][()])

calab.save_for_tuning(traces, fs, "my_recording")
# -> my_recording.npy + my_recording_metadata.json

Converting from Minian (users have zarr/xarray):

import zarr
import calab

store = zarr.open("minian_output", mode="r")
traces = store["C"][:]  # shape: (n_cells, n_frames)
fs = 30.0  # user must know their frame rate

calab.save_for_tuning(traces, fs, "my_recording")

Parameters:

traces (np.ndarray) – Calcium traces, shape (n_timepoints,) for a single trace or (n_cells, n_timepoints) for multiple traces.
fs (float) – Sampling rate in Hz.
path (str or Path) – Output path stem (without extension). Will create {path}.npy and {path}_metadata.json.
metadata (dict, optional) – Additional metadata to include in the JSON sidecar. Keys are merged into the output; built-in keys take precedence.

Raises:

ValueError – If traces has more than 2 dimensions.

calab.simulate(config: SimulationConfig | None = None, **kwargs: object) → SimulationResult¶

Generate synthetic calcium imaging traces with full ground truth.

Parameters:

config (SimulationConfig, optional) – Full configuration. If None, a default config is created.
**kwargs – Override fields on the default/provided config (e.g., num_cells=50, seed=123).

Returns:

Contains traces array and per-cell ground truth.

Return type:

SimulationResult

calab.solve_trace(trace: numpy.ndarray, tau_rise: float, tau_decay: float, fs: float, *, upsample_factor: int = 1, max_iters: int = 500, tol: float = 0.0001, hp_enabled: bool = False, lp_enabled: bool = False, warm_counts: numpy.ndarray | None = None, lambda_: float = 0.0) → SolveTraceResult¶

Run the InDeCa pipeline on a single trace. Delegates to Rust.

Parameters:

trace (np.ndarray) – 1-D calcium trace.
tau_rise (float) – Time constants in seconds.
tau_decay (float) – Time constants in seconds.
fs (float) – Sampling rate in Hz.
upsample_factor (int) – Upsampling multiplier (1 = no upsampling).
max_iters (int) – Maximum FISTA iterations.
tol (float) – Convergence tolerance.
hp_enabled (bool) – Enable high-pass / low-pass filtering.
lp_enabled (bool) – Enable high-pass / low-pass filtering.
warm_counts (np.ndarray, optional) – Spike counts from a previous iteration (at original rate) for warm-start.
lambda (float) – L1 sparsity penalty.

Return type:

SolveTraceResult

calab.tau_to_ar2(tau_rise: float, tau_decay: float, fs: float) → tuple[float, float, float, float]¶

Derive AR(2) coefficients from tau parameters.

Pure Python (trivial math, no solver needed).

Returns:: (g1, g2, d, r) where g1 = d + r, g2 = -(d * r), d = exp(-dt/tau_decay), r = exp(-dt/tau_rise).
Return type:: tuple[float, float, float, float]

calab.tune(traces: numpy.ndarray, fs: float = 30.0, timeout: float | None = None, port: int | None = None, app_url: str | None = None, open_browser: bool = True) → dict | None¶

Open CaTune in the browser for interactive parameter tuning.

Starts a localhost HTTP server serving the provided traces, opens CaTune with a ?bridge= parameter pointing to the server, and waits for the user to export parameters from the web app.

Parameters:

traces (np.ndarray) – Calcium traces, shape (n_cells, n_timepoints) or (n_timepoints,).
fs (float) – Sampling rate in Hz. Default: 30.0.
timeout (float, optional) – Seconds to wait for params. None = wait forever (until Ctrl-C).
port (int, optional) – Port to bind to. None = auto-assign.
app_url (str, optional) – Override CaTune URL (for local dev). Default: GitHub Pages.
open_browser (bool) – Whether to auto-open the browser. Default: True.

Returns:

Exported parameters dict if received, None if timeout/cancelled. Keys: tau_rise, tau_decay, lambda_, fs, filter_enabled.

Return type:

dict or None

calab.DriftModel¶

calab.SpikeModel¶