lbm_suite2p_python 3.0.2

Calcium Imaging Pipeline built with Suite2p, Cellpose and Rastermap

Installation · Documentation · User Guide · Issues

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

• Process volumetric calcium imaging data - motion correction, cell detection, and signal extraction across z-planes
• Automated quality diagnostics - ROI quality metrics, ΔF/F traces, and correlation maps
• Scalable architecture - process single planes or entire volumes with consistent parameters

Planar Suite2p outputs combined into a 3D representation of neural activity

Note: lbm_suite2p_python is in late-beta stage of active development. File an issue for bugs or feature requests.

Installation

lbm_suite2p_python is available on PyPI:

We recommend using a virtual environment. For help setting up a virtual environment, see the MBO guide on virtual environments.

# create a new project folder
mkdir my_project && cd my_project

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

# or with pip
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

git clone https://github.com/MillerBrainObservatory/LBM-Suite2p-Python.git
cd LBM-Suite2p-Python
uv pip install -e ".[dev]"

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 (1-indexed)
    roi_mode=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
)

User Guide for full API reference and examples

Output Gallery

Planar Results

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

correlation image with ROI overlay	mean image with ROI overlay
ROI quality metrics	ΔF/F traces sorted by quality

Volumetric Results

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

XZ/YZ orthogonal projections

activity sorted by similarity (rastermap)

GUI

A graphical interface is available via mbo_utilities:

pip install mbo_utilities
mbo                    # launch GUI
mbo /path/to/data      # open file directly

Note: GUI functionality may lag behind the latest pipeline features.

Troubleshooting

Git LFS Download Errors

If you see smudge filter lfs failed when installing from GitHub:

GIT_LFS_SKIP_SMUDGE=1 uv pip install git+https://github.com/MillerBrainObservatory/LBM-Suite2p-Python.git

Or set it permanently:

# Windows
[System.Environment]::SetEnvironmentVariable('GIT_LFS_SKIP_SMUDGE', '1', 'User')

# Linux/macOS
echo 'export GIT_LFS_SKIP_SMUDGE=1' >> ~/.bashrc
source ~/.bashrc

GUI Dependencies

Linux / macOS:

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

Windows: Install Microsoft Visual C++ Redistributable

Built With

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

Issues & Support

• Bug reports: GitHub Issues
• Questions: See documentation or Suite2p docs

Contributing

Contributions are welcome! This project uses:

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