You need to agree to share your Hugging Face information to access this model
This repository is publicly accessible, but you have to accept the conditions to access its files and content.
Access is approved automatically. By requesting access, you share your Hugging Face username and email with HistoForge. We may get in touch to ask for your feedback.
Log in or Sign Up to review the conditions and access this model content.
NuCLS Breast Nuclei (H&E)
Segments individual nuclei and assigns seven cell classes in H&E-stained human breast-carcinoma images. It returns nucleus outlines, not whole-cell boundaries. For research use, not clinical diagnosis.
Using the module
Run the module on calibrated H&E breast-carcinoma images in QuPath. Select the regions to analyse, then inspect the nucleus outlines and classes before exporting the measurements. Use non-overlapping regions when combining counts.
| Output class | What it marks |
|---|---|
| Tumor Nucleus (Non-Mitotic) | Tumour nuclei without an annotated mitotic figure. |
| Tumor Nucleus (Mitotic) | Mitotic tumour nuclei. |
| Stromal Nucleus | Fibroblasts and vascular endothelium. |
| Macrophage | Macrophage nuclei. |
| Lymphocyte | Lymphocyte nuclei. |
| Plasma Cell | Plasma-cell nuclei. |
| Other Nucleus | Ductal/myoepithelial, neutrophil and eosinophil categories grouped by the release. |
Background is discarded.
Measurements
| Measurement | Meaning | Unit |
|---|---|---|
| Analysed ROI Area | Calibrated area of the selected region. | mm² |
| Nuclei Count | Number of emitted nucleus objects assigned to that region. | nuclei |
| Non-Mitotic Tumor Nuclei | Objects labelled Tumor Nucleus (Non-Mitotic). | nuclei |
| Mitotic Tumor Nuclei | Objects labelled Tumor Nucleus (Mitotic). | nuclei |
| Stromal Nuclei | Objects labelled Stromal Nucleus. | nuclei |
| Macrophages | Objects labelled Macrophage. | nuclei |
| Lymphocytes | Objects labelled Lymphocyte. | nuclei |
| Plasma Cells | Objects labelled Plasma Cell. | nuclei |
| Other Nuclei | Objects labelled Other Nucleus. | nuclei |
| Nuclear Area | Distribution of complete predicted nucleus polygon areas. | µm² |
Areas use complete predicted nucleus polygons, not bounding boxes or shapes clipped to the ROI boundary. Across non-overlapping regions, counts and ROI areas are summed and nuclear areas are pooled. Empty classes have zero count; empty regions have no nuclear-area values. Overlapping ROIs can double-count objects.
Performance
Evaluated on 1,481 fields from 102 slides and 14 hospitals in four hospital-held-out folds (2–5). Fold 1 selected the recipe and stopping step. Scores are mean ± population SD across the four folds, in percent. They describe the cross-validation models; the packaged model was subsequently trained on all 1,744 fields and has no independent NuCLS holdout.
Paper comparison
Detection and matched-contour segmentation:
| Model | AP@0.5 |
mAP@0.5:0.95 |
Median IoU | Median Dice |
|---|---|---|---|---|
| HistoForge cross-validation models | 64.04 ± 2.58 | 25.39 ± 1.37 | 75.15 ± 1.84 | 85.80 ± 1.21 |
| NuCLS paper reported | 74.8 ± 0.5 | 33.0 ± 0.9 | 79.3 ± 1.3 | 88.5 ± 0.8 |
Seven-class classification, on matched nuclei only:
| Model | Accuracy | MCC | Micro AUROC | Macro AUROC |
|---|---|---|---|---|
| HistoForge cross-validation models | 71.74 ± 2.17 | 61.43 ± 3.53 | 94.34 ± 0.80 | 89.93 ± 1.04 |
| NuCLS paper reported | 68.4 ± 4.2 | 55.7 ± 5.4 | 92.8 ± 2.0 | 83.7 ± 2.9 |
Superclass classification, using the paper's broader category grouping:
| Model | Accuracy | MCC | Micro AUROC | Macro AUROC |
|---|---|---|---|---|
| HistoForge cross-validation models | 85.14 ± 3.24 | 77.01 ± 3.68 | 96.33 ± 1.59 | 92.77 ± 1.67 |
| NuCLS paper reported | 77.7 ± 5.7 | 65.6 ± 7.9 | 93.5 ± 2.7 | 86.0 ± 3.2 |
Paper values are quoted from Amgad et al., Bioinformatics (2022), Table 1. Classification includes nonambiguous nuclei matched by bounding-box IoU ≥0.5, regardless of class; it excludes misses and extra detections. Release contents and matched populations differ, so this is a reference comparison, not a controlled ranking.
Additional metrics
| Metric and population | Result |
|---|---|
| Matched-only seven-class macro-F1 | 51.48 ± 5.63% |
Native-contour mSA@0.50:0.95, mean per FOV |
30.45 ± 1.23% |
| Native-contour PQ, pooled per fold | 60.23 ± 1.23% |
| Native-contour AJI, mean per FOV | 53.44 ± 3.31% |
These metrics supplement the paper comparison. Contour metrics exclude predictions supported only by boxes/points or unannotated margins. Matched-only F1 excludes misses and extra detections; end-to-end F1 has not been calculated.
Per-class F1
Matched nuclei only. Counts are pooled across folds; F1 is mean ± population SD.
| Output class | Matched annotated nuclei | Classification F1 |
|---|---|---|
| Tumor Nucleus (Non-Mitotic) | 13,689 | 88.88 ± 5.07% |
| Tumor Nucleus (Mitotic) | 142 | 38.39 ± 9.72% |
| Stromal Nucleus | 4,879 | 67.02 ± 2.80% |
| Macrophage | 739 | 20.60 ± 2.64% |
| Lymphocyte | 9,992 | 73.34 ± 2.42% |
| Plasma Cell | 4,258 | 39.77 ± 20.84% |
| Other Nucleus | 428 | 32.36 ± 19.38% |
Limitations
- Macrophage, mitotic tumour, plasma-cell and Other Nucleus classification is weak or variable. Review these predictions before interpreting rare-cell counts.
- Missed, merged and split nuclei affect results. Sparse annotations and teacher-generated masks limit the training supervision.
- Results may not generalize to other tissues, stains, centres or scanners.
- Evaluation used mean foreground class probabilities; HistoForge uses pixel-majority voting, background removal and different mask cleanup. The reported scores do not establish accuracy under HistoForge's inference rules.
Models and training
The model uses DINOv3 ViT-L/16 with a spatial adapter, Cellpose-flow segmentation and an eight-channel classification head including background. The backbone starts from official DINOv3 weights; the adapter and heads start fresh. An H&E-12 model supplies training masks for box- and point-labelled nuclei, not initialization weights.
| Stage / component | Method and initialization | Input -> output | Module artifact |
|---|---|---|---|
| Nucleus segmentation and classification | DINOv3 with spatial adapter, Cellpose-flow and classification heads | RGB H&E -> seven classes of nucleus instances | Model weights |
| Measurements | Geometric counts and area calculation | Classified nuclei -> counts and nuclear-area distribution | Measurement script |
The working scale is 0.2 µm/px, inferred from the NuCLS publication because the released PNGs lack calibration. Inference uses 512-pixel tiles with 10% overlap.
Training used 19,680 native contours and 31,403 derived instances, with 5,686 excluded from classification loss. Fold 1 selected step 900; the packaged model was trained for those 900 steps on all 1,744 fields.
See the reproduction guide for the full training recipe and source. Exact reconstruction also requires the frozen teacher proposals and review records, which are not included in the module.
Licences and citations
- Weights include DINOv3 derivatives: DINOv3 License.
- Configuration and measurement script: Apache-2.0.
- NuCLS training data: corrected single-rater release, CC0.
- Training sources.
Amgad et al. (2022). NuCLS: A scalable crowdsourcing approach and dataset for nucleus classification and segmentation in breast cancer. GigaScience.
Amgad et al. (2022). Explainable nucleus classification using Decision Tree Approximation of Learned Embeddings. Bioinformatics.
Foundation model: DINOv3 (2025).
Model tree for histoforge/nucls-breast-nuclei
Base model
timm/vit_large_patch16_dinov3.lvd1689m