mbo_utilities 3.0.0

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 the Miller Brain Suite, 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

We recommend uv for managing environments.

For help setting up, see the MBO guide on virtual environments.

uv venv --python 3.12.9
# .venv\Scripts\activate   # optional 

Base (I/O, metadata, GUI)

uv pip install mbo_utilities

With processing pipelines

# suite2p pipeline
uv pip install "mbo_utilities[suite2p]"

# everything (suite2p + rastermap + torch)
uv pip install "mbo_utilities[all]"

GPU dependencies

PyTorch and CuPy require CUDA-specific wheels that must be installed separately.

Suite2p requires pytorch. Installation depends on your cuda version. See the pytorch Get Started page for the correct install command for your OS/Cuda version.

# pytorch with CUDA 12.N (required for suite2p GPU)
# make sure you uninstall any previous versions of pytorch
uv pip uninstall torch torchvision  
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

# cupy (optional, enables GPU for axial registration)
nvidia-smi # check your cuda version first
uv pip install cupy-cuda12x  # for CUDA 12.x
uv pip install cupy-cuda11x  # for CUDA 11.x

Verify installation

mbo --check-install

This will show the status of all packages, GPU availability, and provide exact install commands for anything missing.

Installation script (recommended for new users)

The install script handles environment creation, GPU detection, and optional dependencies automatically.

# 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 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

Miller Brain Suite

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.

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\Miller Brain Suite.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