API

lbm_caiman_python.calculate_centers(A, dims)

lbm_caiman_python.calculate_num_patches(image, stride, overlap)

Calculate the total number of patches in an image given stride and rf.

Parameters:

image_sizetuple

Size of the image as (df, cols).

strideint

Half-size of the patches in pixels (patch width is rf*2 + 1).

overlapint

Amount of overlap between patches in pixels.

Returns:

int

Total number of patches.

lbm_caiman_python.clean_batch(df)

Clean a batch of DataFrame entries by removing unsuccessful df from storage.

This function iterates over the df of the given DataFrame, identifies df where the ‘outputs’ column is either None or a dictionary containing a ‘success’ key with a False value. For each such row, the corresponding item is removed using the df.caiman.remove_item() method, and the removal is saved to disk.

Parameters:

dfpandas.DataFrame

The DataFrame to be cleaned. It must have a ‘uuid’ column for identification and an ‘outputs’ column containing a dictionary with a ‘success’ key.

Returns:

pandas.DataFrame

The DataFrame reloaded from disk after unsuccessful items have been removed.

Notes

• If ‘outputs’ is None or does not contain ‘success’ as a key with a value of False, the row will be removed.

Examples

>>> import pandas as pd
>>> df = pd.DataFrame({
...     'uuid': ['123', '456', '789'],
...     'outputs': [{'success': True}, {'success': False}, None]
... })
>>> cleaned_df = clean_batch(df)
Removing unsuccessful batch row 1.
Row 1 deleted.
Removing unsuccessful batch row 2.
Row 2 deleted.

lbm_caiman_python.combine_z_planes(results: dict)

Combines all z-planes in the results dictionary into a single estimates object.

Parameters:

results (dict): Dictionary with estimates for each z-plane.

Returns:

estimates.Estimates: Combined estimates for all z-planes.

lbm_caiman_python.concat_param_diffs(input_df, param_diffs)

Add parameter differences to the input DataFrame.

Parameters:

input_dfDataFrame

The input DataFrame containing a ‘batch_index’ column.

param_diffsDataFrame

The DataFrame containing the parameter differences for each batch.

Returns:

input_dfDataFrame

The input DataFrame with the parameter differences added.

Examples

>>> import pandas as pd
>>> import lbm_caiman_python as lcp
>>> import lbm_mc as mc
>>> batch_df = mc.load_batch('path/to/batch.pickle')
>>> metrics_files = lcp.summary.compute_mcorr_metrics_batch(batch_df)
>>> metrics_df = lcp.summary._create_df_from_metric_files(metrics_files)
>>> param_diffs = batch_df.caiman.get_params_diffs("mcorr", item_name=batch_df.iloc[0]["item_name"])
>>> final_df = lcp.concat_param_diffs(metrics_df, param_diffs)
>>> print(final_df.head())

lbm_caiman_python.default_params()

Default parameters for both registration and CNMF. The exception is gSiz being set relative to gSig.

Returns:

dict

Dictionary of default parameter values for registration and segmentation.

Notes

This will likely change as CaImAn is updated.

lbm_caiman_python.delete_batch_rows(df, rows_delete, remove_data=False, safe_removal=True)

lbm_caiman_python.fix_scan_phase(data_in: ndarray, offset: int)

Corrects the scan phase of the data based on a given offset along a specified dimension.

lbm_caiman_python.generate_patch_view(image: Any, pixel_resolution: float, target_patch_size: int = 40, overlap_fraction: float = 0.5)

Generate a patch visualization for a 2D image with approximately square patches of a specified size in microns. Patches are evenly distributed across the image, using calculated strides and overlaps.

Parameters:

imagendarray

A 2D NumPy array representing the input image to be divided into patches.

pixel_resolutionfloat

The pixel resolution of the image in microns per pixel.

target_patch_sizefloat, optional

The desired size of the patches in microns. Default is 40 microns.

overlap_fractionfloat, optional

The fraction of the patch size to use as overlap between patches. Default is 0.5 (50%).

Returns:

figmatplotlib.figure.Figure

A matplotlib figure containing the patch visualization.

axmatplotlib.axes.Axes

A matplotlib axes object showing the patch layout on the image.

Examples

>>> import numpy as np
>>> from matplotlib import pyplot as plt
>>> data = np.random.random((144, 600))  # Example 2D image
>>> pixel_resolution = 0.5  # Microns per pixel
>>> fig, ax = generate_patch_view(data, pixel_resolution)
>>> plt.show()

lbm_caiman_python.get_all_batch_items(files: list, algo='all') → DataFrame

Load all cnmf items from a list of .pickle files.

Parameters:

fileslist

List of .pickle files to load.

algostr, optional

Algorithm to filter by. Default is “all”. Options are “cnmf”, “cnmfe”, “mcorr” and “all”.

Returns:

dfDataFrame

DataFrame containing all items with the specified algorithm

lbm_caiman_python.get_batch_from_path(batch_path)

Load or create a batch at the given batch_path.

lbm_caiman_python.get_files_ext(base_dir, extension, max_depth) → list

Recursively searches for files with a specific extension up to a given depth and stores their paths in a pickle file.

Parameters:

base_dirstr or Path

The base directory to start searching.

extensionstr

The file extension to look for (e.g., ‘.txt’).

max_depthint

The maximum depth of subdirectories to search.

Returns:

list

A list of full file paths matching the given extension.

lbm_caiman_python.get_metadata(file: PathLike | str)

Extract metadata from a TIFF file. This can be a raw ScanImage TIFF or one processed via [lbm_caiman_python.save_as()](#save_as).

Parameters:

file: os.PathLike

Path to the TIFF file.

Returns:

dict

Metadata extracted from the TIFF file.

Raises:

ValueError

If no metadata is found in the TIFF file. This can occur when the file is not a ScanImage TIFF.

lbm_caiman_python.get_noise_fft(Y, noise_range=None, noise_method='logmexp', max_num_samples_fft=3072)

Compute the noise level in the Fourier domain for a given signal.

Parameters:

Yndarray

Input data array. The last dimension is treated as time.

noise_rangelist of float, optional

Frequency range to estimate noise, by default [0.25, 0.5].

noise_methodstr, optional

Method to compute the mean noise power spectral density (PSD), by default “logmexp”.

max_num_samples_fftint, optional

Maximum number of samples to use for FFT computation, by default 3072.

Returns:

tuple

• snfloat or ndarray

  Estimated noise level.

• psdxndarray

  Power spectral density of the input data.

lbm_caiman_python.get_single_patch_coords(dims, stride, overlap, patch_index)

Get coordinates of a single patch based on stride, overlap parameters of motion-correction.

Parameters:

dimstuple

Dimensions of the image as (rows, cols).

strideint

Number of pixels to include in each patch.

overlapint

Number of pixels to overlap between patches.

patch_indextuple

Index of the patch to return.

lbm_caiman_python.get_summary_batch(df) → DataFrame

Create a summary of successful and unsuccessful runs for each algorithm.

Parameters:

df

Returns:

lbm_caiman_python.get_summary_cnmf(df: DataFrame) → DataFrame

lbm_caiman_python.greedyROI(Y, nr=30, gSig=[5, 5], gSiz=[11, 11], nIter=5, kernel=None, nb=1, rolling_sum=False, rolling_length=100, seed_method='auto')

Greedy initialization of spatial and temporal components using spatial Gaussian filtering

Parameters:

• Y – np.array 3d or 4d array of fluorescence data with time appearing in the last axis.

• nr – int number of components to be found

• gSig – scalar or list of integers standard deviation of Gaussian kernel along each axis

• gSiz – scalar or list of integers size of spatial component

• nIter – int number of iterations when refining estimates

• kernel – np.ndarray User specified kernel to be used, if present, instead of Gaussian (default None)

• nb – int Number of background components

• rolling_max – boolean Detect new components based on a rolling sum of pixel activity (default: True)

• rolling_length – int Length of rolling window (default: 100)

• seed_method – str {‘auto’, ‘manual’, ‘semi’} methods for choosing seed pixels ‘semi’ detects nr components automatically and allows to add more manually if running as notebook ‘semi’ and ‘manual’ require a backend that does not inline figures, e.g. %matplotlib tk

Returns:

np.array

2d array of size (# of pixels) x nr with the spatial components. Each column is ordered columnwise (matlab format, order=’F’)

C: np.array

2d array of size nr X T with the temporal components

center: np.array

2d array of size nr x 2 [ or 3] with the components centroids

Return type:

A

Author:

Eftychios A. Pnevmatikakis and Andrea Giovannucci based on a matlab implementation by Yuanjun Gao

Simons Foundation, 2015

See also

http://www.cell.com/neuron/pdf/S0896-6273(15)01084-3.pdf

lbm_caiman_python.load_batch(batch_path: str | Path)

Load a batch after transfering it from a Windows to a POSIX system or vice versa.

Parameters:

batch_pathstr, Path

The path to the batch file.

Returns:

pandas.DataFrame

The loaded batch.

lbm_caiman_python.params_from_metadata(metadata)

Generate parameters for CNMF from metadata.

Based on the pixel resolution and frame rate, the parameters are set to reasonable values.

Parameters:

metadatadict

Metadata dictionary resulting from lcp.get_metadata().

Returns:

dict

Dictionary of parameters for lbm_mc.

lbm_caiman_python.read_scan(pathnames, dtype=<class 'numpy.int16'>, join_contiguous=False)

Reads a ScanImage scan.

Parameters:

• pathnames – String or list of strings. Pathname(s) or pathname pattern(s) to read.

• dtype – Data-type. Data type of the output array.

• join_contiguous – Boolean. For multiROI scans (2016b and beyond) it will join contiguous scanfields in the same depth. No effect in non-multiROI scans. See help of ScanMultiROI._join_contiguous_fields for details.

Returns:

A Scan object (subclass of BaseScan) with metadata and data. See Readme for details.

lbm_caiman_python.remove_batch_duplicates(df)

Remove duplicate items from a batch DataFrame.

Parameters:

dfpandas.DataFrame

The batch DataFrame to remove duplicates from.

Returns:

None

lbm_caiman_python.return_scan_offset(image_in, nvals: int = 8)

Compute the scan offset correction between interleaved lines or columns in an image.

This function calculates the scan offset correction by analyzing the cross-correlation between interleaved lines or columns of the input image. The cross-correlation peak determines the amount of offset between the lines or columns, which is then used to correct for any misalignment in the imaging process.

Parameters:

image_inndarray | ndarray-like

Input image or volume. It can be 2D, 3D, or 4D.

.. note::

Dimensions: [height, width], [time, height, width], or [time, plane, height, width]. The input array must be castable to numpy. e.g. np.shape, np.ravel.

nvalsint

Number of pixel-wise shifts to include in the search for best correlation.

Returns:

int

The computed correction value, based on the peak of the cross-correlation.

Notes

This function assumes that the input image contains interleaved lines or columns that need to be analyzed for misalignment. The cross-correlation method is sensitive to the similarity in pattern between the interleaved lines or columns. Hence, a strong and clear peak in the cross-correlation result indicates a good alignment, and the corresponding lag value indicates the amount of misalignment.

Examples

>>> img = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]])
>>> return_scan_offset(img, 1)

lbm_caiman_python.save_as(scan, savedir: PathLike, planes=None, frames=None, metadata=None, overwrite=True, ext='.tiff')

Save scan data to the specified directory in the desired format.

Parameters:

scanscanreader.ScanMultiROI

An object representing scan data. Must have attributes such as num_channels, num_frames, fields, and rois, and support indexing for retrieving frame data.

savediros.PathLike

Path to the directory where the data will be saved.

planesint, list, or tuple, optional

Plane indices to save. If None, all planes are saved. Default is None.

frameslist or tuple, optional

Frame indices to save. If None, all frames are saved. Default is None.

metadatadict, optional

Additional metadata to update the scan object’s metadata. Default is None.

overwritebool, optional

Whether to overwrite existing files. Default is True.

extstr, optional

File extension for the saved data. Supported options are ‘.tiff’ and ‘.zarr’. Default is ‘.tiff’.

Raises:

ValueError

If an unsupported file extension is provided.

Notes

This function creates the specified directory if it does not already exist. Data is saved per channel, organized by planes.

lbm_caiman_python.unvectorize(Y, shape: tuple[int, int], pixel_indices: ndarray = None, order='C')

Reshape an array: [n_pixels, time] -> [time, df, cols] or [n_pixels,] -> [df, cols]

Parameters:

Y: np.ndarray

vectorized movie, shape [n_pixels, time]

shape: tuple[int, int]

shape of one frame, [n_rows, n_cols]

pixel_indices: np.ndarray, default None

1D array of indices that map pixel indices in Y to real pixel indices in a “full Y” with all pixels

order: str, default “C”

“C” or “F” order

Returns:

np.ndarray

movie of shape [time, df, cols] or a 2D image of shape [df, cols]

lbm_caiman_python.vectorize(movie, pixel_indices: ndarray = None, order='C')

Reshape an array: [time, df, cols] -> [n_pixels, time]

Parameters:

movie: np.ndarray

movie of shape [time, df, cols]

pixel_indices: np.ndarray, default None

pixel indices to include in the vectorized output. 1D array of int that represents indices of a fully vectorized movie

order: str, default “C”

“C” or “F” order

Returns:

np.ndarray

vectorized movie, shape [n_pixels, time]