Command Line Interface

Command Line Interface#

The mbo command provides tools for viewing, converting, and analyzing imaging data.

Command

Description

mbo

Launch GUI with file dialog

mbo convert

Convert between formats

mbo info

Show array info

mbo scanphase

Analyze scan-phase offset

mbo download

Download files from GitHub

mbo formats

List supported formats

GUI Mode#

mbo                          # file dialog
mbo /path/to/data            # open specific file
mbo /path/to/data --metadata # show only metadata

File Selection Data Viewer

Convert#

Convert between formats with optional processing.

mbo convert input.tiff output/ -e .zarr           # tiff to zarr
mbo convert input.tiff output/ -e .bin            # tiff to suite2p binary
mbo convert input.zarr output/ -e .tiff           # zarr to tiff
mbo convert input.tiff output/ -e .zarr -p 1 -p 7 # specific planes
mbo convert input.tiff output/ --fix-phase        # with phase correction
mbo convert input.tiff output/ -n 1000            # first 1000 frames

Option

Description

-e, --ext

Output format: .tiff, .zarr, .bin, .h5, .npy

-p, --planes

Z-planes to export (1-based), repeatable

-n, --num-frames

Limit number of frames

--roi

ROI selection: None, 0, N, or "1,3"

--fix-phase

Bidirectional phase correction

--overwrite

Replace existing files
All Convert Options

Option

Description

--output-suffix

Custom filename suffix (default: _stitched for multi-roi)

--phasecorr-method

mean, median, or max

--register-z

Z-plane registration via suite3d

--ome/--no-ome

OME-zarr metadata (zarr only)

--chunk-mb

Streaming chunk size (default: 100)

--debug

Verbose logging

Info#

Display array shape, dtype, chunk info, and metadata without loading data.

mbo info /data/raw.tiff
mbo info /data/volume.zarr
mbo info /data/suite2p/plane0

Scan-Phase Analysis#

Bidirectional resonant scanning causes alternating rows to be shifted horizontally. This tool measures that shift to help configure correction parameters.

mbo scanphase                        # file dialog
mbo scanphase /path/to/data.tiff     # analyze file
mbo scanphase ./folder/ -n 5         # first 5 tiffs
mbo scanphase data.tiff -o ./results # custom output
mbo scanphase data.tiff --show       # show plots
mbo scanphase data.tiff --format pdf # output as pdf

Output Files:

temporal.png

Offset time series + histogram. Should be flat; large jumps indicate motion/hardware issues. Typical offset: 0.5-2.0 px.

../_images/temporal.png
windows.png

Offset vs window size. Shows how estimate stabilizes with more frames. Red line marks where std drops below 0.1 px.

../_images/windows.png
spatial.png

Spatial heatmaps (32x32 and 64x64 patches). Edges different from center is normal. Gray = low signal.

../_images/spatial.png
zplanes.png

Offset vs depth (if multi-plane). Assess if offset varies with z due to resonant scanner angle.

../_images/zplanes.png
parameters.png

Offset vs signal intensity. Red line suggests threshold below which measurements are noisy.

../_images/parameters.png

Tips: Use -n 2 or -n 3 to run quickly on a subset of frames. Multi-ROI data: offsets are averaged across ROIs.

Download#

Download files from GitHub (auto-converts blob to raw URLs).

mbo download https://github.com/user/repo/blob/main/notebook.ipynb
mbo download https://github.com/user/repo/blob/main/data.npy -o ./data/

Downloading from:
  https://raw.githubusercontent.com/.../quickstart.ipynb
Saving to:
  C:\Users\...\quickstart.ipynb

Successfully downloaded: quickstart.ipynb
../_images/jupyter_lab.png

Utilities#

mbo --check-install      # verify installation and GPU config
mbo --download-notebook  # download user guide notebook
mbo --download-file URL  # download any file

mbo_utilities v2.4.3 | Python 3.12.12
==================================================

CUDA Environment:
  Driver CUDA:         12.6

Features:
  [Γ£ô] PyTorch
  [Γ£ô] CuPy
  [ ] Suite2p (not installed)
  [ ] Suite3D (not installed)
  [ ] Rastermap (not installed)

Formats#

mbo formats

Input: .tif, .tiff, .zarr, .bin, .h5, .hdf5, .npy, .json Output: .tiff, .zarr, .bin, .h5, .npy

Upgrade#

Method

Command

Install script

Re-run install script

CLI only

uv tool upgrade mbo_utilities

Virtual env

uv pip install -U mbo_utilities
Contents