segment-kidney-structures

Purpose: This package is built to perform instance segmentation of kidney structures — glomeruli, tubules, and capillaries. The input is multiplexed fluorescence imaging (e.g. CODEX) of kidney biopsies. The input format is greyscale 16-bit .tif. The three pre-trained omnipose models corresponding to three major kidney structures (glomeruli, tubules, blood vessels) are finetuned and ready to be deployed. The outputs are segmentation masks (.tif and .npy) saved as a subfolder in the input directory.

Installation

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

The three segmentation models require a working omnipose/ cellpose environment with GPU support (PyTorch + CUDA). Follow the omnipose installation guide to set up the omnipose venv.

Usage

1. Install segment-kidney-structures into an activated virtual environment

segment-kidney-structures must be installed into the same venv where omnipose is installed.

uv venv .venv
source .venv/bin/activate
uv pip install segment-kidney-structures

2. Generate segmentation inputs from specific marker channels

The current preprocessing script expects the following folder structure <root-dir>/<dataset>/<input-folder>/<marker>/, with one subfolder per marker containing matching-named 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 --input-folder your_folder_name

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

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

Troubleshooting tips:

• Make sure the filenames in each marker folder match.
• Set --markers based on your folder names (comma-separated).
• The output files are saved under <root-dir>/<dataset>/<output-folder>/.
• Make sure you visually check some input files before proceeding to the next step (aka segmentation). The correct inputs (16-bit gray-scale TIFF) should display the signals of the kidney structures with very clean background.

3. Run segmentation

All CLI commands are available under the segment-kidney-structures cli.py

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/

CLI arguments:

• --model-path to use your own model instead of the pretrained ones
• --mask-threshold / --diameter to change based on your data; setting these will override the tuned default parameters
• --no-gpu to run on CPU
• --dry-run to print the commands without executing them

Additional details on the models

Additional model training data, sizes, parameters, and applications were published at https://doi.org/10.64898/2026.01.14.699505.

Acknowledgement

This tool was made possible thanks to many brilliant scientists who have paved the way and provide feedback and guidance. Many thanks to the teams behind Cellpose and Omnipose who built the general image segmentation tools. They were the foundations of segment-kidney-structures.

Cite segment-kidney-structures

If segment-kidney-structures has been useful to your research, please cite our paper below:

High-dimensional spatial proteomics and novel machine learning pipeline identifies disease specific renal damage states
Thao Cao, Madeleine S. Torcasso, Junting Ai, Satoshi Hara, Michael S. Andrade, Anthony Chang, Gabriel Casella, Anita S. Chong, Maryellen L. Giger, Marcus R. Clark
bioRxiv 2026.01.14.699505; doi: https://doi.org/10.64898/2026.01.14.699505

Feedback and Questions

We acknowledge that there is no perfect model, but there are some useful ones. We hope to keep improving our tool and support other scientists in their imaging analysis. If you have any feedback, questions, and comments, please send me an email (thaocao97@gmail.com).

License

MIT License

Copyright (c) 2026 Thao Cao