lbm_suite2p_python 2.3.1

Light Beads Microscopy Pipeline using Suite2p

LBM-Suite2p-Python

Status: Late-beta stage of development

A volumetric 2-photon calcium imaging processing pipeline for Light Beads Microscopy (LBM) datasets, built on Suite2p.

A GUI is available via mbo_utilities (GUI functionality will lag behind this pipeline).

Installation

LBM-Suite2p-Python is a pure pip install. You can use venv, uv (recommended), or conda. Just remove the uv prefix.

# create a new project folder
mkdir my_project
cd my_project

# (uv only) create environment and install
uv venv --python 3.12.9
uv pip install lbm_suite2p_python

Optional Dependencies

# With rastermap for activity clustering visualization
uv pip install "lbm_suite2p_python[rastermap]"

# With cellpose for anatomical cell detection (includes PyTorch)
uv pip install "lbm_suite2p_python[cellpose]"

# All optional dependencies
uv pip install "lbm_suite2p_python[all]"

Development Installation

While this pipeline is in active development, you can keep a local copy to quickly pull changes:

git clone https://github.com/MillerBrainObservatory/LBM-Suite2p-Python.git
cd LBM-Suite2p-Python
uv pip install .

GUI Dependencies

Linux / macOS:

sudo apt install libxcursor-dev libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev

Windows: Install Microsoft Visual C++ Redistributable

Troubleshooting

When installing from github, you may get:

Git LFS Error: If you see smudge filter lfs failed:

GIT_LFS_SKIP_SMUDGE=1 uv sync --all-extras --active

Quick Start

import lbm_suite2p_python as lsp

results = lsp.pipeline(
    input_data="D:/data/raw",   # path to file, directory, or list of files
    save_path=None,             # default: save next to input
    ops=None,                   # default: use MBO-optimized parameters
    planes=None,                # default: process all planes
    roi=None,                   # default: stitch multi-ROI data
    keep_reg=True,              # default: keep data.bin (registered binary)
    keep_raw=False,             # default: delete data_raw.bin after processing
    force_reg=False,            # default: skip if already registered
    force_detect=False,         # default: skip if stat.npy exists
    dff_window_size=None,       # default: auto-calculate from tau and framerate
    dff_percentile=20,          # default: 20th percentile for baseline
    dff_smooth_window=None,     # default: auto-calculate from tau and framerate
)

Planar Results

Each z-plane produces diagnostic images automatically saved during processing.

Segmentation overlays on reference images

ROI quality metrics: size, SNR, compactness

ΔF/F traces sorted by quality

Volumetric Results

Volume-level visualizations combine data across all z-planes.

ROI masks across all z-planes

3D ROI centroids colored by SNR

Activity sorted by similarity (Rastermap)

Built With

This pipeline integrates several open-source tools:

• Suite2p - Core registration and segmentation
• Cellpose - Anatomical segmentation (optional)
• Rastermap - Activity clustering (optional)
• mbo_utilities - ScanImage I/O and metadata
• scanreader - ScanImage metadata parsing

Issues & Support

• Bug reports: GitHub Issues
• Questions: See Suite2p documentation for Suite2p-specific questions
• Known issues: Widgets may throw "Invalid Rect" errors (upstream issue)

Contributing

Contributions are welcome! This project follows Suite2p's conventions and uses:

• Ruff for linting and formatting (line length: 88, numpy docstring style)
• pytest for testing
• Sphinx for documentation