mbo_utilities 2.6.3

Various utilities for the Miller Brain Observatory

Installation · Documentation · User Guide · Supported Formats · Issues

Image processing utilities for the Miller Brain Observatory (MBO).

• Modern Image Reader/Writer: Fast, lazy I/O for ScanImage/generic TIFFs, Suite2p .bin, Zarr, HDF5, and Numpy (in memeory or saved to .npy)
• Run processing pipelines for calcium imaging - motion correction, cell extraction, and signal analysis
• Operates on 3D timeseries natively and is extendable to ND-arrays
• Visualize data interactively with a GPU-accelerated GUI for exploring large datasets with fastplotlib

Select data, visualize, and inspect metadata

Note: mbo_utilities is in late-beta stage of active development. There will be bugs that can be addressed quickly, file an issue or reach out on slack.

Installation

mbo_utilities is available in pypi:

pip install mbo_utilities

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

# base: reader + GUI
pip install mbo_utilities

# with lbm_suite2p_python, suite2p, cellpose
pip install "mbo_utilities[suite2p]"

# all processing pipelines
pip install "mbo_utilities[all]"

Suite3D + CuPy: Suite3D requires CuPy for GPU acceleration. CuPy must be installed separately to match your CUDA toolkit version:

# check your CUDA version
nvcc --version

# CUDA 12.x
pip install cupy-cuda12x

# CUDA 11.x
pip install cupy-cuda11x

The install script below detects your systems cuda-version automatically.

Installation Script with UV (Recommended)

The install script will prompt several options:

1. Create a virtual environment with mbo_utilities,
2. Install the image reader globally, with Destkop Icon + use mbo any terminal
3. Install in both a virtual environment and globally
4. Specify optional dependencies, and environment paths

# Windows (PowerShell)
irm https://raw.githubusercontent.com/MillerBrainObservatory/mbo_utilities/master/scripts/install.ps1 | iex

# Linux/macOS
curl -sSL https://raw.githubusercontent.com/MillerBrainObservatory/mbo_utilities/master/scripts/install.sh | bash

Note: The mbo command is available globally thanks to uv tools. Update with the install script or manually with uv tool upgrade mbo_utilities.

Usage

The user-guide covers usage in a jupyter notebook. The CLI Guide provides a more in-depth overview of the CLI commands. The GUI Guide provides a more in-depth overview of the GUI. The ScanPhase Guide describes the bi-directional scan-phase analysis tool with output figures and figure descriptions.

Command	Description
mbo /path/to/data.tiff	View a supported file/folder
mbo info /path/to/data.tiff	Show file info and metadata
mbo convert input.tiff output.zarr	Convert between formats
mbo scanphase /path/to/data.tiff	Run scan-phase analysis
mbo notebook lsp	Generate template notebook
mbo formats	List supported formats
mbo download path/to/notebook.ipynb	Download a notebook to the current directory
mbo pollen	Pollen calibration tool (WIP)
mbo pollen path/to/data	Pollen calibration - Skip data collection

→ CLI Guide

GUI

Launch an interactive GPU-accelerated viewer for exploring large imaging datasets. Supports all MBO file formats with real-time visualization.

mbo                    # launch GUI
mbo /path/to/data      # open file directly
mbo --check-install    # verify GPU configuration

→ GUI Guide

Scan-Phase Analysis

Measure and correct bidirectional scan-phase offset in resonant scanning microscopy data. Generates diagnostic figures showing temporal stability, spatial variation, and recommended corrections.

mbo scanphase /path/to/data.tiff -o ./output

→ Scan-Phase Guide

Supported Formats

Format	Read	Write	Description
ScanImage TIFF	✓	✓	Native LBM acquisition format
Generic TIFF	✓	✓	Standard TIFF stacks
Zarr	✓	✓	Chunked cloud-ready arrays
HDF5	✓	✓	Hierarchical data format
Suite2p	✓	✓	Binary and ops.npy files

→ Formats Guide

Upgrade

The CLI tool can be upgraded with uv tool upgrade mbo_utilities, or the package can be upgraded with uv pip install -U mbo_utilities.

The CLI tool can be upgraded with uv tool upgrade mbo_utilities, or the package can be upgraded with uv pip install -U mbo_utilities.

Method	Command
Install script	Re-run install script
CLI tool	uv tool upgrade mbo_utilities
Virtual env	uv pip install -U mbo_utilities

ScanImage Acquisition Modes

mbo_utilities automatically detects and parses metadata from these ScanImage acquisition modes:

Configuration	Detection	Result
LBM single channel	channelSave=[1..N], AI0 only	lbm=True, colors=1
LBM dual channel	channelSave=[1..N], AI0+AI1	lbm=True, colors=2
Piezo (single frame/slice)	hStackManager.enable=False, framesPerSlice=1	piezo=True
Piezo multi-frame (with avg)	hStackManager.enable=False, logAvgFactor>1	piezo=True, averaged frames
Piezo multi-frame (no avg)	hStackManager.enable=False, framesPerSlice>1, logAvg=1	piezo=True, raw frames
Single plane	hStackManager.enable=False	zplanes=1

Note: Frame-averaging (logAverageFactor > 1) is only available for non-LBM acquisitions.

Uninstall

If installed via quick install script:

# Windows
uv tool uninstall mbo_utilities
Remove-Item -Recurse -Force "$env:USERPROFILE\.mbo"
Remove-Item "$env:USERPROFILE\Desktop\MBO Utilities.lnk" -ErrorAction SilentlyContinue

# Linux/macOS
uv tool uninstall mbo_utilities
rm -rf ~/mbo

If installed in a project venv:

uv pip uninstall mbo_utilities

Troubleshooting

GPU/CUDA Errors

Error: "Failed to auto-detect CUDA root directory"

This occurs when using GPU-accelerated features and CuPy cannot find your CUDA Toolkit.

Check if CUDA is installed:

# Windows
dir "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA" -ErrorAction SilentlyContinue
$env:CUDA_PATH

# Linux/macOS
nvcc --version
echo $CUDA_PATH

Set CUDA_PATH:

# Windows (replace v12.6 with your version)
$env:CUDA_PATH = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6"
[System.Environment]::SetEnvironmentVariable('CUDA_PATH', $env:CUDA_PATH, 'User')

# Linux/macOS (add to ~/.bashrc or ~/.zshrc)
export CUDA_PATH=/usr/local/cuda-12.6

If CUDA is not installed, download from NVIDIA CUDA Downloads.

Git LFS Download Errors

There is a bug in fastplotlib causing git lfs errors when installed from a git branch.

Set GIT_LFS_SKIP_SMUDGE=1 and restart your terminal:

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

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

Built With

• Suite2p - Integration support
• Rastermap - Visualization
• Suite3D - Volumetric processing

Issues & Support

• Bug reports: GitHub Issues
• Questions: See documentation or open a discussion