Loading Data¶

If you already have calcium imaging results from CaImAn or Minian, the CaLab loaders let you import those traces directly – no manual HDF5/Zarr wrangling needed. Once loaded, you can save traces in CaTune-compatible format for interactive tuning in the browser, or pass them straight to calab.tune() or calab.run_deconvolution().

The loaders are optional. Install the required dependencies with:

pip install calab[loaders]

This pulls in h5py (for CaImAn HDF5 files) and zarr (for Minian Zarr stores). If you only need one loader, you can install the individual dependency (pip install h5py or pip install zarr).

CaImAn (HDF5)¶

import calab

traces, meta = calab.load_caiman("caiman_results.hdf5")

print(traces.shape)             # (n_cells, n_timepoints), dtype float64
print(meta["sampling_rate_hz"]) # read from the HDF5 file

Parameters:

Parameter	Default	Description
`path`	(required)	Path to the CaImAn HDF5 file.
`trace_key`	`"estimates/C"`	HDF5 dataset key for the traces array.
`fs_key`	`"params/data/fr"`	HDF5 dataset key for the sampling rate. Ignored if `fs` is provided.
`fs`	`None`	Override sampling rate (Hz). When provided, the value from `fs_key` is not read.

Override the default keys if your file uses a different layout:

traces, meta = calab.load_caiman(
    "my_file.hdf5",
    trace_key="estimates/C",
    fs_key="params/data/fr",
)

Or provide the sampling rate directly:

traces, meta = calab.load_caiman("my_file.hdf5", fs=30.0)

Minian (Zarr)¶

import calab

traces, meta = calab.load_minian("minian_output/", fs=30.0)

Minian does not store the sampling rate in its Zarr output, so you should provide fs if you know it. If omitted, meta["sampling_rate_hz"] will be None.

Parameters:

Parameter	Default	Description
`path`	(required)	Path to the Minian Zarr directory.
`trace_key`	`"C"`	Zarr key for the traces array.
`fs`	`None`	Sampling rate in Hz.

Override the trace key if needed:

traces, meta = calab.load_minian("minian_output/", trace_key="C", fs=30.0)

Metadata dict¶

Both loaders return a metadata dict with the same structure:

{
    "source": "caiman",          # or "minian"
    "sampling_rate_hz": 30.0,    # float, or None if unknown
    "num_cells": 42,             # int
    "num_timepoints": 9000,      # int
}

This dict is separate from the save_for_tuning JSON sidecar – it is a lightweight summary of what was loaded and can be passed through to save_for_tuning as custom metadata if desired.

Saving for CaTune¶

After loading, save traces in CaTune-compatible format:

calab.save_for_tuning(traces, fs=meta["sampling_rate_hz"], path="my_recording")
# Creates: my_recording.npy + my_recording_metadata.json

The .npy file contains the traces as a float64 array (dtype='<f8', C-contiguous), and the _metadata.json sidecar records the sampling rate, dimensions, schema version, and dtype. These files can be loaded directly in CaTune’s browser interface via drag-and-drop.

You can attach additional metadata to the JSON sidecar:

calab.save_for_tuning(
    traces,
    fs=meta["sampling_rate_hz"],
    path="my_recording",
    metadata={"subject": "mouse_01", "session": "day3"},
)

To reload saved files in Python:

traces, meta = calab.load_tuning_data("my_recording")
# Reads my_recording.npy + my_recording_metadata.json

Error handling¶

The loaders raise clear errors when something goes wrong:

ImportError – raised if the required dependency is not installed. The message tells you exactly what to install:
```
ImportError: h5py is required to load CaImAn files.
Install it with: pip install calab[loaders]
```
FileNotFoundError – raised if the HDF5 file or Zarr directory does not exist at the given path.
KeyError – raised if the trace key is not found in the file. The message lists available top-level keys so you can find the right one.

End-to-end example¶

A typical workflow: load CaImAn results, save for CaTune, then tune interactively:

import calab

# 1. Load from CaImAn
traces, meta = calab.load_caiman("caiman_results.hdf5")

# 2. Save in CaTune format
calab.save_for_tuning(traces, fs=meta["sampling_rate_hz"], path="my_recording")

# 3. Open in the browser for interactive tuning
params = calab.tune(traces, fs=meta["sampling_rate_hz"])

# 4. Or run batch deconvolution directly
activity = calab.run_deconvolution(
    traces, fs=meta["sampling_rate_hz"],
    tau_r=0.02, tau_d=0.4, lam=0.5,
)