CaimanSegmentationExtractor

class CaimanSegmentationExtractor(file_path: str | Path)

Bases: SegmentationExtractor

A SegmentationExtractor for CaImAn.

This class inherits from the SegmentationExtractor class, having all its functionality specifically applied to the dataset output from the ‘CaImAn’ ROI segmentation method.

CaImAn (Calcium Imaging Analysis) is a computational toolbox for large scale calcium imaging data analysis and behavioral analysis. This extractor provides access to the rich output of CaImAn’s analysis pipeline stored in HDF5 format.

The CaImAn estimates object contains the following key components:

Spatial and Temporal Components:

Ascipy.sparse.csc_matrix (# pixels x # components)

Spatial footprints of identified components. Each column represents a component’s spatial footprint, flattened with order=’F’.

Cnp.ndarray (# components x # timesteps)

Temporal traces (denoised and deconvolved) for each component.

bnp.ndarray (# pixels x # background components)

Spatial background components, flattened with order=’F’.

fnp.ndarray (# background components x # timesteps)

Temporal background components.

Neural Activity:

Snp.ndarray (# components x # timesteps)

Deconvolved neural activity (spikes) for each component.

F_dffnp.ndarray (# components x # timesteps)

DF/F normalized temporal components (2p data only).

YrAnp.ndarray (# components x # timesteps)

Residual traces after denoising.

Quality Assessment:

SNR_compnp.ndarray (# components,)

Signal-to-noise ratio for each component.

r_valuesnp.ndarray (# components,)

Spatial correlation values for each component.

cnn_predsnp.ndarray (# components,)

CNN-based classifier predictions (0-1, neuron-like probability).

idx_componentslist

Indices of accepted components.

idx_components_badlist

Indices of rejected components.

Component Properties:

centerlist (# components,)

Centroid coordinates for each spatial footprint.

coordinateslist (# components,)

Contour coordinates for each spatial footprint.

gnp.ndarray (# components, p)

Autoregressive time constants for each trace.

blnp.ndarray (# components,)

Baseline values for each trace.

c1np.ndarray (# components,)

Initial calcium concentration for each trace.

neurons_snnp.ndarray (# components,)

Noise standard deviation for each trace.

Background and Noise:

b0np.ndarray (# pixels,)

Constant baseline for each pixel (1p data).

snnp.ndarray (# pixels,)

Noise standard deviation for each pixel.

Wscipy.sparse matrix (# pixels x # pixels)

Ring model matrix for background computation (1p data).

Summary Images:

Cnnp.ndarray (height, width)

Local correlation image.

Caiman parameters:

The params group contains all analysis parameters organized by category: - data: Dataset properties (dimensions, frame rate, decay time) - init: Component initialization parameters - motion: Motion correction parameters - quality: Component evaluation thresholds - spatial/temporal: Processing parameters - online: OnACID algorithm parameters

Notes

Some fields may be stored as scalar values in the HDF5 file when they are not available or not computed. This extractor will detect such cases and return None for those fields.

At the moment (June, 2025), Caimn does not keep documentation of their output format. Looking at the source what they do is to transform the cnmfe class to a dict with the dunder method (__dict__) and save this as an HDF5 file:

flatironinstitute/CaImAn

This might change in the future, so please check the CaImAn documentation.

Initialize a CaimanSegmentationExtractor instance.

Parameters:

file_path (str) – The location of the HDF5 file containing CaImAn analysis output.

Notes

The extractor will automatically detect which data types are available in the HDF5 file. This allows for compatibility with different CaImAn versions and analysis configurations.

Quality metrics (SNR, spatial correlation values, CNN predictions) are automatically stored as properties during initialization if available.

__del__()

Close the h5py file when the object is deleted.

get_accepted_list() → list

Get a list of accepted ROI ids.

Returns:

accepted_list – List of accepted ROI ids.

Return type:

list

get_rejected_list() → list

Get a list of rejected ROI ids.

Returns:

rejected_list – List of rejected ROI ids.

Return type:

list

get_frame_shape() → tuple

Get frame size of movie (height, width).

Returns:

frame_shape – 2-D array: image height x image width

Return type:

array_like

get_native_timestamps(start_sample: int | None = None, end_sample: int | None = None) → ndarray | None

Retrieve the original unaltered timestamps for the data in this interface.

Returns:

timestamps – The timestamps for the data stream, or None if native timestamps are not available.

Return type:

numpy.ndarray or None