JwzTumor 1.0.2

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

JwzTumor

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

# Install from PyPI
pip install JwzTumor

# Using uv
uv pip install -e .

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

Quick Start

# 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

License

Apache-2.0