WSI-Classification

Clinical decision-support pipeline for whole-slide image (WSI) analysis of muscle biopsies, designed to help classify slides into clinically relevant categories (including Myopathic cases).

Project Summary

This repository provides an end-to-end workflow for pathology WSIs:

• tissue segmentation and cropping from raw slides
• tile-level feature extraction using a histology foundation model
• weakly supervised classification with CLAM-MB
• model evaluation and attention heatmap visualization

Target classes currently used in this project: Healthy, Myopathic, Dystrophic, Inflammatory, Neurogenic.

End-to-End Workflow

flowchart TB
    rawSlides["RawWSI(.ndpi/.tiff)"] --> segmentation["TissueSegmentationAndCrop"]
    segmentation --> croppedOme["CroppedOME-TIFFTissues"]
    croppedOme --> featureExtraction["TileSamplingAndFeatureExtraction(H-optimus)"]
    featureExtraction --> featureBags["FeatureBags(.pt)+TileCoords(.csv)"]
    featureBags --> clamTraining["CLAM-MBTraining"]
    clamTraining --> checkpoint["ModelCheckpoint(best_model.pth)"]
    checkpoint --> evaluation["Evaluation(accuracy,CM,report)"]
    checkpoint --> attention["AttentionHeatmaps"]

Key Capabilities

• WSI preprocessing: segment tissue regions and export pyramidal OME-TIFF crops.
• Feature extraction: generate per-tissue embeddings (*_features.pt) and tile coordinates (*_tiles.csv).
• MIL classification: train CLAM-MB on variable-length tissue bags with attention and clustering regularization.
• Evaluation outputs: confusion matrix, classification report, and prediction artifacts.
• Interpretability: visualize class-branch and averaged attention maps over tissue regions.
• Metadata utility: inject objective magnification (NominalMagnification) into OME-TIFF metadata.

Repository Structure

• segmentation/ - Tissue detection, crop export, and OME magnification utility.
• feature_extraction/ - Tile dataset and embedding inference pipeline.
• clam/ - Dataset, CLAM model, training, evaluation, and attention visualization.
• camil/ - CAMIL context-aware MIL with matching CLAM/LR sampling and training/evaluation diagnostics.
• notebooks/ - Model usage and exploratory notebook scripts (jupytext format).
• environment.yml - Conda environment definition.
• .devcontainer/ - Containerized development setup.

Quick Start

1) Environment Setup

From repository root:

conda env create -f environment.yml
conda activate wsi-env

If you use the devcontainer, dependencies are defined in: .devcontainer/Dockerfile and .devcontainer/requirements.txt.

2) Prepare Data

The scripts assume local data under: /workspaces/WSI-Classification/data/HE-MYO/

Expected processed structure for CLAM:

data/HE-MYO/Processed/
  Healthy/
    slide_A/
      tissue_001.ome.tiff
      tissue_001_tiles.csv
      tissue_001_features.pt
  Myopathic/
    slide_B/
      tissue_002.ome.tiff
      tissue_002_tiles.csv
      tissue_002_features.pt
  Dystrophic/
  Inflammatory/
  Neurogenic/

3) Run the Pipeline

From repository root:

# (A) Tissue preprocessing / cropping
python segmentation/crop_tissues_multislides.py

# (B) Feature extraction on processed tissues
python feature_extraction/inference.py

# (C) Train CLAM-MB classifier
python clam/train.py

# (D) Evaluate trained model
python clam/evaluate.py

# (E) Generate attention heatmaps
python clam/visualize_attention.py

CAMIL

CAMIL uses the existing feature tensors and tile coordinates with CLAM-compatible slide splits and tile sampling. Configure camil/config.yaml, then run:

python -m camil.train --config camil/config.yaml
python -m camil.evaluate --config camil/config.yaml

See camil/README.md for architecture fidelity, configuration, checkpoints, diagnostic outputs, and synthetic tests.

DG-SSM-MIL

The dg_ssm_mil/ workflow implements the dynamic graph equations and Bi-SSM-vision block from Ding et al. (2025) for the five-class tissue task. It uses the same feature tensors and coordinate CSV files as CLAM and supports H-Optimus, UNI2-H, and GenBio through dg_ssm_mil/config.yml.

# One Monte Carlo repeat (useful for development)
python -m dg_ssm_mil.train --repeat-index 0

# All configured repeats (paper protocol defaults to 10)
python -m dg_ssm_mil.train

python -m dg_ssm_mil.evaluate
python -m dg_ssm_mil.visualize_attention --split test
python -m dg_ssm_mil.test_integration

The paper-faithful defaults use an 8-neighbor spatial graph, six dynamic neighbors, raw Euclidean coordinates, Adam with learning rate 2e-4 and weight decay 1e-5, and slide-grouped 8:1:1 train/validation/test splits. Memory-saving tile caps and weighted sampling remain optional project extensions. The devcontainer supplies the required CUDA-compatible PyTorch Geometric, torch-cluster, and mamba-ssm packages.

Optional utility to add/update OME magnification metadata:

python segmentation/add_ome_magnification.py \
  --input /path/to/tissue.ome.tiff \
  --magnification 20 \
  --output /path/to/tissue.with_mag.ome.tiff

Configuration

• Main CLAM configuration: clam/config.yml
• Default model/data settings in code currently use project-local absolute paths.
• Before running on a new machine, update path values in scripts/config as needed.

Outputs

Typical generated artifacts include:

• *_features.pt - per-tile feature embeddings per tissue
• *_tiles.csv - tile center coordinates
• checkpoints/best_model.pth - best training checkpoint
• evaluation reports and confusion matrices under the configured results directory
• attention heatmaps under the configured visualization output directory

Intended Use and Disclaimer

This software is intended for research and decision-support workflows in computational pathology. It is not a certified medical device and must not be used as a standalone diagnostic system. Any clinical or translational use requires independent validation, expert pathology oversight, and compliance with applicable regulations (for example, data-protection and medical-device requirements).

Contributing

Contributions that improve reproducibility, path configurability, and clinical interpretability are welcome. Please open an issue or pull request with a clear description of the problem and proposed change.