API

Functions, broken down by category.

Run Suite2p

lbm_suite2p_python.run_plane(input_path: str | Path, save_path: str | Path | None = None, ops: dict | str | Path = None, keep_raw: bool = False, keep_reg: bool = True, force_reg: bool = False, force_detect: bool = False, **kwargs)

Processes a single imaging plane using suite2p, handling registration, segmentation, and plotting of results.

Parameters:

input_pathstr or Path

Full path to the file to process, with the file extension.

save_pathstr or Path, optional

Directory to save the results.

opsdict, str or Path, optional

Path to or dict of user‐supplied ops.npy. If given, it overrides any existing or generated ops.

keep_rawbool, default false

if true, do not delete the raw binary (data_raw.bin) after processing.

keep_regbool, default false

if true, do not delete the registered binary (data.bin) after processing.

force_regbool, default false

if true, force a new registration even if existing shifts are found in ops.npy.

force_detectbool, default false

if true, force roi detection even if an existing stat.npy is present.

Returns:

dict

Processed ops dictionary containing results.

Raises:

FileNotFoundError

If input_tiff does not exist.

TypeError

If save_folder is not a string.

Exception

If plotting functions fail.

Notes

• ops supplied to the function via ops_file will take precendence over previously saved ops.npy files.

lbm_suite2p_python.run_volume(input_files: list, save_path: str | Path = None, ops: dict | str | Path = None, keep_reg: bool = True, keep_raw: bool = True, force_reg: bool = False, force_detect: bool = False, replot: bool = False)

Processes a full volumetric imaging dataset using Suite2p, handling plane-wise registration, segmentation, plotting, and aggregation of volumetric statistics and visualizations.

Parameters:

input_fileslist of str or Path

List of TIFF file paths, each representing a single imaging plane.

save_pathstr or Path, optional

Base directory to save all outputs. If none, will create a “volume” directory in the parent of the first input file.

opsdict or list, optional

Dictionary of Suite2p parameters to use for each imaging plane.

save_pathstr, optional

Subdirectory name within save_path for saving results (default: None).

keep_rawbool, default false

if true, do not delete the raw binary (data_raw.bin) after processing.

keep_regbool, default false

if true, do not delete the registered binary (data.bin) after processing.

force_regbool, default false

if true, force a new registration even if existing shifts are found in ops.npy.

force_detectbool, default false

if true, force roi detection even if an existing stat.npy is present.

replotbool, optional

If True, regenerate all summary plots even if they already exist (default: False).

Returns:

list of str

List of paths to ops.npy files for each plane.

Raises:

Exception

If volumetric summary statistics or any visualization fails to generate.

Notes

At the root of save_path will be a folder for each z-plane with all suite2p results, as well as volumetric outputs at the base of this folder.

Each z-plane folder contains: - Registration, Segmentation and Extraction results (ops, spks, iscell) - Summary statistics: execution time, signal strength, acceptance rates - Optional rastermap model for visualization of activity across the volume

Each save_path root contains: - Accepted/Rejected histogram, neuron-count x z-plane (acc_rej_bar.png) - Execution time for each step in each z-plane (execution_time.png) - Mean/Max images, with and without segmentation masks, in GIF/MP4 - Traces animation over time and neurons - Optional rastermap clustering results

---

Load results

lbm_suite2p_python.load_ops(ops_input: str | Path | list[str | Path])

Simple utility load a suite2p npy file

lbm_suite2p_python.load_traces(ops: dict | str | Path)

Return (accepted-only) fluorescence traces, neuropil traces and spike traces from ops file.

Parameters:

opsstr, Path or dict

Path to the ops.npy file or a dict containing the ops data.

Returns:

tuple

A tuple containing three arrays filtered to contain only accepted neurons: - F: Fluorescence traces (2D array, shape [n_neurons, n_timepoints]) - Fneu: Neuropil fluorescence traces (2D array, shape [n_neurons, n_timepoints]) - spks: Spike traces (2D array, shape [n_neurons, n_timepoints])

See also

lbm_suite2p_python.load_ops

lbm_suite2p_python.load_planar_results

lbm_suite2p_python.load_planar_results(ops: dict | str | Path, z_plane: list | int = None) → dict

Load stat, iscell, spks files and return as a dict. Does NOT filter by valid cells, array contain both accepted and rejected neurons. Filter for accepted-only via f[iscell] or fneue[iscell] if needed.

Parameters:

opsdict, str or Path

Dict of or path to the ops.npy file.

z_planeint or None, optional

the z-plane index for this file. If provided, it is stored in the output.

Returns:

dict

dictionary with keys: - ‘F’: fluorescence traces loaded from F.npy, - ‘Fneu’: neuropil fluorescence traces loaded from Fneu.npy, - ‘spks’: spike traces loaded from spks.npy, - ‘stat’: stats loaded from stat.npy, - ‘iscell’: boolean array from iscell.npy, - ‘cellprob’: cell probability from classifier. - ‘z_plane’: an array (of shape [n_neurons,]) with the provided z_plane index.

See also

lbm_suite2p_python.load_ops

lbm_suite2p_python.load_traces

lbm_suite2p_python.update_ops_paths(ops_files: str | list)

Update save_path, save_path0, and save_folder in an ops dictionary based on its current location. Use after moving an ops_file or batch of ops_files.

---

Plot results

lbm_suite2p_python.plot_projection(ops, savepath=None, fig_label=None, vmin=None, vmax=None, add_scalebar=False, proj='meanImg', display_masks=False, accepted_only=False)

lbm_suite2p_python.plot_rastermap(spks, model, neuron_bin_size=None, fps=17, vmin=0, vmax=0.8, xmin=0, xmax=None, save_path=None, title=None, title_kwargs={}, fig_text=None)

lbm_suite2p_python.plot_volume_signal(zstats, savepath)

Plots the mean fluorescence signal per z-plane with standard deviation error bars.

This function loads signal statistics from a .npy file and visualizes the mean fluorescence signal per z-plane, with error bars representing the standard deviation.

Parameters:

zstatsstr or Path

Path to the .npy file containing the volume stats. The output of get_zstats().

savepathstr or Path

Path to save the generated figure.

Notes

• The .npy file should contain structured data with plane, mean_trace, and std_trace fields.

• Error bars represent the standard deviation of the fluorescence signal.

lbm_suite2p_python.plot_traces(f, save_path='', fps=17.0, num_neurons=20, window=220, title='', offset=None, lw=0.5, cmap='tab10', signal_units=None)

Plot stacked fluorescence traces with automatic offset and scale bars.

Parameters:

fndarray

2d array of fluorescence traces (n_neurons x n_timepoints).

save_pathstr, optional

Path to save the output plot (default is “./stacked_traces.png”).

fpsfloat, optional

Sampling rate in frames per second (default is 17.0).

num_neuronsint, optional

Number of neurons to display (default is 20).

windowfloat, optional

Time window (in seconds) to display (default is 120).

titlestr, optional

Title of the figure (default is “”).

offsetfloat or None, optional

Vertical offset between traces; if None, computed automatically.

lwfloat, optional

Line width for data points.

cmapstr, optional

Matplotlib colormap string (default is ‘tab10’).

signal_unitsstr, optional

Units of fluorescence signal. Options: “raw”, “dff”, “dffp”, if None will infer from percentile, recommended to keep None unless units are misinterpreted.

lbm_suite2p_python.plot_execution_time(filepath, savepath)

Plots the execution time for each processing step per z-plane.

This function loads execution timing data from a .npy file and visualizes the runtime of different processing steps as a stacked bar plot with a black background.

Parameters:

filepathstr or Path

Path to the .npy file containing the volume timing stats.

savepathstr or Path

Path to save the generated figure.

Notes

• The .npy file should contain structured data with plane, registration, detection, extraction, classification, deconvolution, and total_plane_runtime fields.

lbm_suite2p_python.save_images_to_movie(image_input, savepath, duration=None, format='.mp4')

Convert a sequence of saved images into a movie.

TODO: move to mbo_utilities.

Parameters:

image_inputstr, Path, or list

Directory containing saved segmentation images or a list of image file paths.

savepathstr or Path

Path to save the video file.

durationint, optional

Desired total video duration in seconds. If None, defaults to 1 FPS (1 image per second).

formatstr, optional

Video format: “.mp4” (PowerPoint-compatible), “.avi” (lossless), “.mov” (ProRes). Default is “.mp4”.

Examples

>>> import mbo_utilities as mbo
>>> import lbm_suite2p_python as lsp

Get all png files autosaved during LBM-Suite2p-Python run_volume() >>> segmentation_pngs = mbo.get_files(“path/suite3d/results/”, “segmentation.png”, max_depth=3) >>> lsp.save_images_to_movie(segmentation_pngs, “path/to/save/segmentation.png”, format=”.mp4”)

---

Utilities

lbm_suite2p_python.dff_percentile(f_trace, window_size=300, percentile=8)

Compute ΔF/F₀ using a rolling percentile baseline.

lbm_suite2p_python.dff_maxmin(f_trace, fps, smooth_window=5)

Compute DF/F₀ using a 5s Gaussian filter followed by rolling max-min (‘maxmin’).

lbm_suite2p_python.combine_tiffs(files)

Combines multiple TIFF files into a single stacked TIFF.

Parameters:

fileslist of str or Path

List of file paths to the TIFF files to be combined.

Returns:

np.ndarray

A 3D NumPy array representing the concatenated TIFF stack.

Notes

• Input TIFFs should have identical spatial dimensions (Y x X).

• The output shape will be (T_total, Y, X), where T_total is the sum of all input time points.

lbm_suite2p_python.get_common_path(ops_files: list | tuple)

Find the common path of all files in ops_files. If there is a single file or no common path, return the first non-empty path.