microProfiler

Microscopy image preprocessing, segmentation, and profiling pipeline for multi-well plate data.

Parses filenames via user-supplied regex into unified metadata, runs a chainable preprocessing pipeline, then performs cell segmentation and feature profiling.

Filename Parsing

All metadata is extracted from filenames via regex with named capture groups. Canonical metadata columns (well, field, stack, timepoint, channel) are filled with defaults (A1, 0, 0, 0, ch0) when not captured. Additional capture groups are preserved as extra metadata. Regex presets for Operetta and MICA formats are provided in the GUI.

Installation

Requirements

• Python >= 3.10
• OS: Only Windows 11 (64-bit) was tested; CLI works cross-platform
• GPU (optional): NVIDIA GPU with CUDA 12+ for faster cellpose segmentation

Quick Install

conda create -n micro
conda activate micro

git clone https://github.com/soulong/microProfiler.git
cd microProfiler
pip install .

GPU-Accelerated Install (Recommended)

For significantly faster Cellpose segmentation, install GPU-enabled PyTorch before installing microProfiler.

Step 1 — Install PyTorch with CUDA

Go to pytorch.org/get-started and select your CUDA version. Example for CUDA 12.6:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

Step 2 — Install JAX with CUDA (used by BaSiC shading correction)

pip install jax[cuda12]

See jax.readthedocs.io for other CUDA versions.

Step 2.5 — Install DINOv3 (required for Cellpose v4 models)

pip install git+https://github.com/facebookresearch/dinov3

Step 3 — Install microProfiler

pip install .

This installs cellpose and all remaining dependencies automatically.

Windows Desktop Shortcut

After installing in the micro conda environment, create a desktop shortcut that launches microProfiler without opening a console window:

microprofiler install-shortcut

This places a shortcut on the Desktop and in the Start Menu. The shortcut uses pythonw.exe from the micro environment for a clean, console-free launch.

Pipeline Order

Input → Regex parse → Resize → BaSiC → Z-projection → Tile → Filter* → Segment → Profile

1. Regex parse — Filenames parsed into metadata via user-supplied regex. Canonical fields filled with defaults.
2. Resize (optional) — Standalone resize step
3. BaSiC correction (optional) — Flatfield/darkfield shading correction
4. Z-projection (optional) — Max/mean/min projection of Z-stacks
5. Tile splitting (optional) — Non-overlapping tiles
6. Filter* (optional) — Metadata filter (not a standalone pipeline step). Narrow the dataset before segmentation/profiling by applying regex patterns against metadata columns via ImageDataset.filter_metadata().
7. Segmentation (optional) — Cellpose-SAM object detection
8. Profiling — Image-level and object-level feature extraction. Supports multi-object profiling (profile multiple masks with different channel/feature settings in a single run via object_profilings list).

Desktop GUI

microProfiler includes a PySide6 desktop GUI that wraps the full pipeline with step-by-step image preview, parameter configuration and running.

Running the GUI

Run microprofiler install-shortcut after installation to create a Windows shortcut that opens the GUI without a console window. Otherwise, run with the following terminal command under the micro conda environment:

microprofiler

The microprofiler command launches the GUI when called with no arguments. The CLI pipeline is accessible via subcommands:

Command	Action
microprofiler	Launch desktop GUI
microprofiler run ...	Run pipeline from CLI (requires --config)
microprofiler --debug run ...	Run pipeline with verbose DEBUG logging
microprofiler --log-file pipeline.log run ...	Run pipeline and write logs to file
microprofiler install-shortcut	Create Windows desktop shortcut
microprofiler export-config <session_dir>	Export GUI session to CLI-ready YAML
microprofiler --version	Print version
microprofiler --help	Show CLI help

Cellpose Model

microProfiler uses Cellpose for segmentation. Built-in model names: cpsam_v2, cpdino, cpdino-vitb. cpdino is the default.

Cellpose v4+ models (cpdino, cpdino-vitb, cpsam_v2) require DINOv3:

pip install cellpose --upgrade
pip install git+https://github.com/facebookresearch/dinov3

microProfiler does not bundle Cellpose model weights — they are downloaded automatically by Cellpose on first use. Click Browse in the GUI to select a custom model file.

Quick Start (CLI)

All pipeline parameters are specified in a YAML config file. The CLI accepts only the input directory and config path:

# Run full pipeline using a YAML config file
microprofiler run /path/to/Measurement\ 1 --config examples/pipeline_config.yml

# Enable debug logging and log to file
microprofiler --debug --log-file pipeline.log run /path/to/data --config config.yml

A complete YAML config with all parameters is at examples/pipeline_config.yml.

Library Usage

import re
from pathlib import Path
from microProfiler import ImageDataset
from microProfiler.preprocessing.resizer import resize_dataset
from microProfiler.preprocessing.basic_correction import apply_basic
from microProfiler.preprocessing.z_projection import z_project_dataset
from microProfiler.preprocessing.tile_splitter import tile_dataset
from microProfiler.segmentation.cellpose import segment_dataset
from microProfiler.profiling.image_profiler import profile_images
from microProfiler.profiling.object_profiler import profile_objects, measure_objects

root = Path(r"/path/to/Measurement 1")

image_pat = re.compile(
    r"(?P<well>[A-Z]\d+)_f(?P<field>\d+)_z(?P<stack>\d+)_t(?P<timepoint>\d+)_ch(?P<channel>\d+)\.tiff$"
)
mask_pat = re.compile(
    r"(?P<well>[A-Z]\d+)_f(?P<field>\d+)_z(?P<stack>\d+)_t(?P<timepoint>\d+)_ch(?P<channel>\d+)_cp_masks_(?P<mask_name>.+)\.png$"
)

# 1. Load dataset (filenames parsed via regex)
ds = ImageDataset(root, image_pattern=image_pat, mask_pattern=mask_pat)
channels = ds.intensity_colnames

# 2. Preprocess (in-place on disk)
ds = resize_dataset(ds, scale_factor=0.5)
ds = apply_basic(ds, mode="fit-transform")
if "stack" in ds.metadata.columns:
    ds = z_project_dataset(ds, method="max")
ds = tile_dataset(ds, tile_w=540, tile_h=540)

# 3. Segment
ds = segment_dataset(ds, object_name="cell", chan1=channels[:1])

# 4. Profile — image-level + object-level with extras
profile_images(ds, channels=channels, db_path=root / "results.db", table_name="image")
profile_objects(
    ds,
    mask_name="cell",
    intensity_channels=channels,
    radial_channels=channels[:1],
    radial_n_bins=5,
    granularity_channels=channels[:1],
    glcm_channels=channels[:1],
    glcm_distances=[2],
    correlation_pairs=[(channels[0], channels[1])] if len(channels) >= 2 else None,
    granularity_kwargs={"radii": [1, 3, 6, 8, 12], "subsample_size": 1.0},
    db_path=root / "results.db",
)

# Or measure a single image/mask pair directly
img, masks = ds.get_imageset(0)
df = measure_objects(
    masks["cell"], img,
    channel_names=channels,
    intensity_channels=channels,
    granularity_channels=channels,
)

Key Modules

Module	Purpose
io.dataset	Metadata management, filename parsing, file discovery (optional subdirectory glob), image loading, image iteration
io.schema	Metadata column schema, well derivation, output filename builder
io.database	Thread-safe SQLite (WAL mode, per-thread connections)
io.loaders	Unified TIFF I/O
preprocessing.resizer	Image resizing
preprocessing.basic_correction	BaSiC shading correction wrapper
preprocessing.z_projection	Z-stack projection
preprocessing.tile_splitter	Image tiling
segmentation.cellpose	Cellpose-SAM segmentation
profiling.image_profiler	Whole-image features
profiling.object_profiler	Per-object features (shape, intensity, texture)
profiling.extras	Radial distribution, granularity, GLCM, correlation
profiling.batch_writer	Batched SQLite writer

Acknowledgements

microProfiler uses the following open-source libraries:

• BaSiCPy — Flatfield and darkfield shading correction.
  https://github.com/peng-lab/BaSiCPy
• Cellpose — Generalist deep learning model for segmentation.
  https://github.com/MouseLand/cellpose

Citation

If you use microProfiler in your research, please cite the repository:

@software{microProfiler,
  author = {Hao He},
  title = {microProfiler: Microscopy Image Preprocessing, Segmentation, and Profiling Pipeline},
  year = {2026},
  url = {https://github.com/soulong/microProfiler}
}

License

MIT