README.md

---
license: mit
tags:
  - histopathology
  - digital-pathology
  - cell-detection
  - cell-classification
  - tissue-classification
  - placenta
  - yolo
  - graph-neural-network
metrics:
  - f1
  - accuracy
pipeline_tag: object-detection
---

# HAPPY — trained model weights

Trained weights for the **HAPPY** placenta histology pipeline (Histology Analysis Pipeline.PY):
a three-stage workflow of **nuclei detection → cell classification → tissue classification**
over whole slide images.

- **Code:** https://github.com/Nellaker-group/happy
- **Original methods paper:** Vanea et al., *Mapping cell-to-tissue graphs across human placenta
  histology whole slide images using deep learning with HAPPY*, Nature Communications (2024).
- **HAPPY v2/v3:** Walker et al., *Biologically inspired digital histology
  for deep phenotyping of placental composition changes across major lesion types*, Placenta (2026).

These weights are used by the HAPPY code.

## Files

| File | Stage | Architecture | Coverage | Metric |
|---|---|---|---|---|
| `nuclei/retinanet_placenta_nuclei_detector.pt` | Nuclei detection | RetinaNet | Placenta | F1 0.856 |
| `nuclei/yolo_multiorgan_nuclei_detector.pt` | Nuclei detection | YOLO (`yolo26`) | Multi-organ | F1 0.90 |
| `cell/resnet50_placenta_cell_classifier.pt` | Cell classification | ResNet-50 | Placenta (11 cell types) | Acc 84.29% |
| `tissue/clustergcn_placenta_tissue_classifier.pt` | Tissue classification | ClusterGCN (GNN) | Placenta (9 tissue types) | Acc 68.34% |

### Nuclei detector — per-organ benchmarks (YOLO, multi-organ)

| Organ | F1 | Precision | Recall |
|---|---|---|---|
| Aorta | 0.923 | 0.870 | 0.983 |
| Brain cortex | 0.955 | 0.913 | 1.000 |
| Cervix ectocervix | 0.815 | 0.692 | 0.991 |
| Liver | 0.908 | 0.885 | 0.932 |
| Muscle skeletal | 0.931 | 0.871 | 1.000 |
| Ovary | 0.852 | 0.755 | 0.978 |
| Placenta | 0.899 | 0.857 | 0.946 |

The RetinaNet detector is placenta-only (F1 0.856) and kept as an alternative to the
multi-organ YOLO detector.

### Cell classification (placenta, 11 cell types)

Evaluated on a held-out test set of 2,743 cells:

| Metric | Value |
|---|---|
| Overall accuracy | 84.29% |
| Top-2 accuracy | 94.90% |
| Macro-averaged ROC AUC | 0.9773 |

Most misclassifications fall within closely related cell differentiation pathways.

### Tissue classification (placenta, 9 tissue types)

Evaluated on 149,425 cell-graph nodes:

| Metric | Value |
|---|---|
| Overall accuracy | 68.34% |
| Top-2 accuracy | 91.14% |
| Top-3 accuracy | 97.10% |
| Macro-averaged ROC AUC | 0.8868 |

Misclassifications fall primarily within developmentally similar microstructures — villus
types are typically confused with other villus types, reflecting similarities in villus
growth and branching morphology.

## Training & evaluation data

| Model | Train | Validation | Test (held-out) |
|---|---|---|---|
| Nuclei detection (multi-organ YOLO) | 25,990 nuclei | 6,746 nuclei | 7,777 nuclei |
| Nuclei detection (placenta RetinaNet) | 11,755 nuclei | 2,374 nuclei | 2,754 nuclei |
| Cell classification | 13,842 cells (incl. validation) | — | 2,743 cells |
| Tissue classification (GNN) | 468,869 nodes (incl. validation) | — | 179,095 nodes |

## Usage

```bash
pip install huggingface_hub
# from the HAPPY repo:
python -m happy.db.download_models --project-name placenta
```

This downloads all four files into `projects/placenta/trained_models/`. They then resolve by
id via main.db database:

```bash
# nuclei + cell inference, then tissue inference
python cell_inference.py  --project-name placenta --organ-name placenta \
    --nuc-model-id 2 --cell-model-id 3 --run-id <run>
python tissue_inference.py --project-name placenta --organ-name placenta \
    --tissue-model-id 1 --run-id <run>
```


## Intended use & limitations

- **Intended use:** research on H&E histology WSIs, trained for placenta. The YOLO nuclei
  detector generalises across the organs benchmarked above.
- **Validate before use:** cell and tissue models are placenta-trained; on a new cohort of data, validate on a small amount of your own ground truth (see the repo's evaluation
  scripts) before relying on predictions.
- **Not for clinical use.** Research only.

## Citation

If you use HAPPY or these models, please cite the original methods paper (Vanea et al. 2024).
If you use these model weights or the v2/v3 pipeline, please also cite Walker et al. 2026.

```bibtex
@article{vanea2024happy,
  title   = {Mapping cell-to-tissue graphs across human placenta histology whole slide
             images using deep learning with HAPPY},
  author  = {Vanea, Claudia and D{\v{z}}igurski, Jelisaveta and Rukins, Valentina and Dodi,
             Omri and Siigur, Siim and Salum{\"a}e, Liis and Meir, Karen and Parks, W. Tony
             and Hochner-Celnikier, Drorith and Fraser, Abigail and Hochner, Hagit and Laisk,
             Triin and Ernst, Linda M. and Lindgren, Cecilia M. and Nell{\aa}ker, Christoffer},
  journal = {Nature Communications},
  volume  = {15},
  number  = {1},
  pages   = {2710},
  year    = {2024}
}

@article{walker2026happy,
  title   = {Biologically inspired digital histology for deep phenotyping of placental
             composition changes across major lesion types},
  author  = {Walker, Emma C. and Vanea, Claudia and Meir, Karen and Hochner-Celnikier,
             Drorith and Hochner, Hagit and Laisk, Triin and Lindgren, Cecilia and
             Glastonbury, Craig A. and Ernst, Linda M. and Nellaker, Christoffer},
  journal = {Placenta},
  year    = {2026}
}
```