Metadata-Version: 2.4
Name: JwzTumor
Version: 1.0.4
Summary: Breast ultrasound benign-malignant diagnosis with segmentation-assisted multi-task learning.
Author: SuShuheng
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/SuShuheng/JwzTumor
Project-URL: Documentation, https://github.com/SuShuheng/JwzTumor#readme
Project-URL: Repository, https://github.com/SuShuheng/JwzTumor
Project-URL: Issues, https://github.com/SuShuheng/JwzTumor/issues
Project-URL: Changelog, https://github.com/SuShuheng/JwzTumor/releases
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm>=4.65
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.2
Requires-Dist: Pillow>=9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# JwzTumor

[![PyPI version](https://img.shields.io/pypi/v/JwzTumor.svg)](https://pypi.org/project/JwzTumor/)
[![PyPI downloads](https://img.shields.io/pypi/dm/JwzTumor.svg)](https://pypi.org/project/JwzTumor/)
[![Python](https://img.shields.io/pypi/pyversions/JwzTumor.svg)](https://pypi.org/project/JwzTumor/)
[![License](https://img.shields.io/pypi/l/JwzTumor.svg)](https://github.com/SuShuheng/JwzTumor/blob/master/LICENSE)

Breast ultrasound benign-malignant diagnosis with segmentation-assisted multi-task learning.

## Overview

JwzTumor implements **LABDG-Pre + DGBC-MTLNet + MPTC-Head**, a multi-task system for breast tumor diagnosis from ultrasound images:

- **LABDG-Pre**: Lesion-aware boundary-preserving domain-generalized preprocessing
- **DGBC-MTLNet**: Domain-generalized boundary-context collaborative multi-task network (CNN-Mamba hybrid)
- **MPTC-Head**: Morphology-prompted topology-consistent classification head (4-stream)

The system outputs: classification probability, segmentation mask, edge map, SDM, uncertainty map, and explainability visualizations.

## Project Structure

```
jwz-tumor/
  pyproject.toml
  configs/          # 8 YAML configs
  dataset/          # BUSBRA + BUSI data
  src/JwzTumor/
    data/           # Datasets, preprocessing, augmentation, cache, audit, collate
    models/         # LABDG-Pre, DGBCEncoder, MPP, decoder, MPTC-Head
    losses/         # 7 loss modules + factory
    training/       # Stage trainer, scheduler, callbacks
    inference/      # Predictor, TTA, postprocessing, visualization
    evaluation/     # Classification + segmentation metrics
    cli/            # 6 CLI commands
    utils/          # Config, seed, logging, I/O, registry
  tests/            # 12 test files
```

## Datasets

### BUSBRA (Training)
- Images: `bus_{id}-{side}.png`, Masks: `mask_{id}-{side}.png`
- Labels: `bus_data.csv` (Pathology: benign/malignant)
- CV: `5-fold-cv.csv` or `10-fold-cv.csv`
- Case-level splitting (no leak)

### BUSI (Testing)
- Directory-based: `benign/`, `malignant/`
- Skip: `normal-不使用/`
- Multi-mask: OR union in original size before resize
- RGB images converted to grayscale

## Installation

```bash
# Install from PyPI
pip install JwzTumor

# Using uv
uv pip install -e .

# Development
uv pip install -e ".[dev]"
```

## Quick Start

```bash
# Show version
jwzt version

# Export config template
jwzt get --name train_full --output configs/my_config.yaml

# Train
jwzt train --config configs/train_full.yaml --experiment-name exp001 --fold 1

# Stage-specific training
jwzt train --config configs/train_pretrain_pre.yaml --stage pretrain_pre --fold 1
jwzt train --config configs/train_pretrain_seg.yaml --stage pretrain_seg --fold 1
jwzt train --config configs/train_cls_head.yaml --stage train_cls --fold 1
jwzt train --config configs/train_finetune.yaml --stage finetune_all --fold 1

# Predict
jwzt pred --config configs/infer_busi.yaml --model checkpoints/best_auc.ckpt --data dataset/Dataset_BUSI_with_GT --output outputs/busi_predictions

# Evaluate
jwzt eval --config configs/eval_busi.yaml --pred outputs/busi_predictions --data dataset/Dataset_BUSI_with_GT

# Audit dataset
jwzt audit-data --data-root dataset --output outputs/dataset_audit_summary.json

# Debug training
jwzt train --config configs/train_debug.yaml --experiment-name debug_run
```

## Training Strategy

Four-stage training:
1. **pretrain_pre**: Train LABDG-Pre only (coarse localization, structure maps)
2. **pretrain_seg**: Train DGBC-MTLNet segmentation (encoder + decoder)
3. **train_cls**: Train MPTC-Head only (freeze encoder + preprocessing)
4. **finetune_all**: End-to-end fine-tuning with all losses

## Metrics

**Classification**: AUC, Accuracy, Sensitivity, Specificity, Precision, F1
**Segmentation**: Dice, IoU, HD95, Boundary-F1

## Stargazers over time

[![Stargazers over time](https://starchart.cc/SuShuheng/JwzTumor.svg)](https://starchart.cc/SuShuheng/JwzTumor)

## License

Apache-2.0
