Metadata-Version: 2.5
Name: segment-kidney-structures
Version: 0.1.1
Summary: Segment kidney structures (glomeruli, tubules, capillaries) from multiplexed fluorescence images of kidney biopsies using pre-trained convolution neural network (CNN) models.
Project-URL: Homepage, https://github.com/ThaoCao/kidneystructureanalysis
Author-email: Thao Cao <thaocao97@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: computer vision,glomerulus,imaging,kidney,segmentation,tubule,vessel
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: omnipose
Requires-Dist: pillow
Requires-Dist: scikit-image
Requires-Dist: tifffile
Description-Content-Type: text/markdown

# 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

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

The three segmentation models require a working [omnipose](https://pypi.org/project/omnipose/)/
[cellpose](https://pypi.org/project/cellpose/) environment with GPU support (PyTorch +
CUDA). Follow the
[omnipose installation guide](https://omnipose.readthedocs.io/installation.html) 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.

```bash
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.

```bash
# 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`
```bash
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

| Structure     | Input channels | Trained on |
|---------------|-----------------|------------|
| `glomeruli`   | 3 (RGB)         | CD10 / DAPI / Claudin1 / CD31 composite |
| `tubules`     | 1               | MUC1 / Claudin1 / CD138 / CD10 sum |
| `capillaries` | 1               | CD31 |

Additional model training data, sizes, parameters, and applications were published at [https://doi.org/10.64898/2026.01.14.699505](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](https://cellpose.readthedocs.io/en/latest/index.html) and [Omnipose](https://omnipose.readthedocs.io/index.html) 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](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](mailto:thaocao97@gmail.com)).

## License
MIT License

Copyright (c) 2026 Thao Cao
