Create README.md

README.md

@@ -0,0 +1,98 @@
+---
+language:
+- en
+tags:
+- medical
+- histopathology
+- breast-cancer
+- vision
+- multiple-instance-learning
+- pytorch
+- pathology
+license: cc-by-nc-4.0
+datasets:
+- bracs
+- bach
+- breakhis
+metrics:
+- accuracy
+- f1
+- recall
+---
+
+# OpenPink Core (Breast Cancer Histopathology AI)
+
+OpenPink Core is a state-of-the-art Dual-Stream Multiple Instance Learning (MIL) model designed for the classification of Breast Cancer Whole Slide Images (WSIs) and Regions of Interest (ROIs). Built on top of the **Virchow2** foundation model, OpenPink classifies tissue into four clinical categories: **Atypical, Benign, Malignant, and Normal**, with a specific emphasis on identifying diagnostically challenging Atypical lesions.
+
+## Model Details
+
+- **Architecture:** Dual-Stream Gated Attention MIL (processes global macroscopic thumbnails alongside high-resolution 224x224 patches).
+- **Feature Extractor:** Virchow2 (1280-dimensional embeddings, SwiGLU MLP, SiLU).
+- **Training Strategy:** 10-Fold Stratified Group Cross-Validation.
+- **Domain Adaptation:** Multi-source training utilizing Hard Example Mining from South American (BreaKHis) and European (BRACS, BACH) datasets to decouple cellular density from malignancy.
+- **Ensemble:** The repository provides 10 pre-trained checkpoints (folds) for robust ensemble inference.
+- **License:** CC-BY-NC-4.0 (Strictly Non-Commercial & Research use only).
+
+## Intended Use & Limitations
+
+**FOR ACADEMIC AND RESEARCH PURPOSES ONLY.**
+
+- **Not for Clinical Use:** This tool has not been evaluated by the FDA, EMA, or any other regulatory body. It is not a medical device. It cannot be used for diagnostic, prognostic, or therapeutic purposes.
+- **Limitations:** The model assumes H&E (Hematoxylin and Eosin) stained slides. Variations in extreme staining protocols may degrade performance. We strongly recommend applying Macenko Stain Normalization prior to feature extraction.
+
+## Training Data
+
+The model was trained and internally validated on multi-centric European clinical cohorts:
+- **BRACS (BReAst Carcinoma Subtyping):** Hematoxylin & Eosin (H&E) stained ROIs.
+- **BACH (Breast Cancer Histology):** High-resolution microscopy images.
+
+To ensure global generalization, the model was aggressively domain-adapted using "Hard Negative" injections from the **BreaKHis** dataset (Brazil), focusing on hyper-cellular benign tumors like Fibroadenomas to prevent False Positives in dense tissue structures.
+
+## Evaluation Results
+
+### Internal Validation (European Cohorts)
+During 10-fold CV on BRACS and BACH, the model achieved:
+- **Accuracy:** 93.33%
+- **Macro F1-Score:** 90.18%
+- **Atypical Recall (Sensitivity):** 95.65%
+- **Malignant Recall:** 98.68%
+
+### Out-Of-Distribution (OOD) Domain Adaptation
+Evaluated on **1,693 unseen images** from BreaKHis using a strict Clinical Thresholding constraint (Probability > 0.30 for Malignant).
+- **Malignant Recall:** 82.46% (945 / 1146 cases)
+- **Benign Specificity:** 66.73% (365 / 547 cases) - *Massive improvement over the 16.8% baseline.*
+- **Perfect Separation:** Zero Atypical or Normal misclassifications in the entire OOD set.
+
+## How to Use
+
+The checkpoints in this repository are designed to be loaded by the `OpenPink-Core` inference scripts. 
+
+### 1. Download Checkpoints via Python
+You can automatically download all 10 folds using the `huggingface_hub` library:
+
+```python
+from huggingface_hub import snapshot_download
+
+# Download the checkpoints folder
+snapshot_download(
+    repo_id="MatthewMak/OpenPink-Core", 
+    allow_patterns="*.pt", 
+    local_dir="./checkpoints"
+)
+```
+
+### 2. Feature Extraction & Inference
+Clone the [OpenPink-Core GitHub/GitLab Repository](#) (link pending) and run the evaluation scripts using the downloaded checkpoints.
+
+```bash
+# 1. Extract Virchow2 Features (Auto-Macenko enabled)
+python extract_features.py --data_dir ./images --output_dir ./features --ref_image ref.png
+
+# 2. Run Ensemble Inference with Clinical Thresholding
+python evaluate_ood.py --features_dir ./features --checkpoints_dir ./checkpoints --malignant_threshold 0.30
+```
+
+## Citation & Credits
+- **Author/Lead Researcher:** Matthaios Makrogiannis
+- **Institution:** University of Ioannina
+- **Year:** 2026