segment-kidney-structures

Purpose: This package is built to perform instance segmentation of kidney structures — glomeruli, tubules, and capillaries. The input is from multiplexed imaging (e.g. CODEX). The three pre-trained models are ready to be deployed. The outputs are segmentation masks (.tif and .npy)

Installation

pip install segment-kidney-structures
# or
uv pip install segment-kidney-structures

Segmentation requires a working omnipose/ cellpose install with GPU support (PyTorch + CUDA). Follow the omnipose installation guide.

Usage

All commands are available under the segment-kidney-structures CLI (or python -m segment_kidney_structures.cli).

1. Build segmentation inputs from marker images

Each dataset is expected to live at <root-dir>/<dataset>/<input-folder>/<marker>/, with one subdirectory per marker containing matching per-sample TIFF images.

# Glomeruli: RGB composite from CD10, Claudin1, CD31 (+ DAPI for QC)
segment-kidney-structures preprocess-glomeruli \
    --root-dir /path/to/data --dataset your_dataset

# Tubules: normalized sum of MUC1, Claudin1, CD138, CD10 channels
segment-kidney-structures preprocess-tubules \
    --root-dir /path/to/data --dataset your_dataset

# Capillaries/vessels: CD31 
segment-kidney-structures preprocess-vessels \
    --root-dir /path/to/data --dataset your_dataset

Each subcommand accepts --input-folder (default ds10), --markers (comma-separated, order matters), --output-name, and --dataset.

2. Run segmentation

segment-kidney-structures segment --structure glomeruli --input-dir /path/to/data/
segment-kidney-structures segment --structure tubules   --input-dir /path/to/data/
segment-kidney-structures segment --structure capillaries --input-dir /path/to/data/

--model-path to use your own model instead of the pretrained ones --mask-threshold / --diameter to override the tuned default parameters --no-gpu to run on CPU --dry-run to print the commands without executing them

Bundled models

License

MIT