Metadata-Version: 2.5
Name: segment-kidney-structures
Version: 0.1.0
Summary: Segment kidney structures (glomeruli, tubules, capillaries) from multiplexed imaging using pre-trained omnipose models.
Project-URL: Homepage, https://github.com/ThaoCao/kidneystructureanalysis
Author-email: Thao Cao <thaocao97@gmail.com>
License-Expression: MIT
License-File: LICENSE
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 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

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

Segmentation requires a working [omnipose](https://pypi.org/project/omnipose/)/
[cellpose](https://pypi.org/project/cellpose/) install with GPU support (PyTorch +
CUDA). Follow the
[omnipose installation guide](https://omnipose.readthedocs.io/installation.html).

## 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.

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

```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/
```

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

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

## License

MIT
