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 notebook`	Generate template notebooks
`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

Example: Convert raw TIFFs to OME-Zarr

mbo convert D:/demo/raw D:/demo/volume --ome -e .zarr

Reading: D:/demo/raw
Counting frames: 100%|████████████████████████████| 1/1 [00:00<00:00, 19152.07it/s]
  Shape: (119, 14, 448, 448), dtype: int16
Writing: D:/demo/volume (format: .zarr)
Writing Zarr: 100%|███████████████████████████████| 119/119 [00:43<00:00, 2.71frames/s]

Done! Output saved to: D:/demo/volume/tp00001-00119_zplane01-14_stack.zarr

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.

windows.png

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

spatial.png

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

zplanes.png

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

parameters.png

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

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

Notebook#

Generate template notebooks for common analysis pipelines.

mbo notebook lsp                          # LBM-Suite2p-Python pipeline
mbo notebook basic                        # basic data exploration
mbo notebook dff                          # delta F/F analysis
mbo notebook lsp -d /path/to/data         # pre-fill data path
mbo notebook lsp -o ./notebooks           # custom output directory
mbo notebook lsp -n my_analysis           # custom name: yyyy-mm-dd_my_analysis.ipynb
mbo notebook -l                           # list available templates

Option	Description
`-o, --output`	Output directory (default: current directory)
`-n, --name`	Custom notebook name (date prefix auto-added)
`-d, --data`	Data path to pre-fill in the notebook
`-l, --list`	List available templates
`--templates-dir`	Show custom templates directory path

Available Templates:

Template	Description
`lsp`	LBM-Suite2p-Python full pipeline with imports, ops config, and visualization
`basic`	Basic mbo_utilities data exploration with imread/imwrite
`dff`	Delta F/F analysis with compute_dff and activity maps

Templates show full function signatures with all parameters, formatted for easy customization.

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

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`