HAPPY — trained model weights

Trained weights for the HAPPY histology pipeline (Histology Analysis Pipeline.PY): a three-stage workflow of nuclei detection → cell classification → tissue classification over whole slide images. Models are provided for placenta, umbilical cord and fetal membranes.

• 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).
• Umbilical cord and fetal membrane models: Currently under development. Please contact us if using these models.

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%
cell/resnet50_cord_cell_classifier.pt	Cell classification	ResNet-50	Umbilical cord (7 cell types)	Val acc 89.63%
cell/resnet50_membrane_cell_classifier.pt	Cell classification	ResNet-50	Fetal membranes (10 cell types)	Val acc 79.76%
tissue/clustergcn_cord_tissue_classifier.pt	Tissue classification	ClusterGCN (GNN)	Umbilical cord (9 tissue types)	Val acc 88.16%
tissue/clustergcn_membrane_tissue_classifier.pt	Tissue classification	ClusterGCN (GNN)	Fetal membranes (5 tissue types)	Val acc 92.19%

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.

Umbilical cord and fetal membrane models

Cell and tissue models for H&E sections of umbilical cord and fetal membranes (membrane rolls). Both use the multi-organ YOLO detector for nuclei detection.

	Umbilical cord	Fetal membranes
--organ-name	cord	membrane
Nuclei detection	--nuc-model-id 2 (YOLO)	--nuc-model-id 2 (YOLO)
Cell classification	--cell-model-id 4	--cell-model-id 5
Tissue classification	--tissue-model-id 2	--tissue-model-id 3

Results

Model	Validation accuracy
Umbilical cord cell classification	89.63%
Fetal membrane cell classification	79.76%
Umbilical cord tissue classification	88.16%
Fetal membrane tissue classification	92.19%

Training

• Cell models: ResNet-50, 40 epochs, batch size 50, learning rate 1e-4.
• Tissue models: ClusterGCN, 16 layers, 256 hidden units, 2,000 epochs, learning rate 1e-3, class-weighted loss, on graphs of standardised cell embeddings with intersection edges.

Recommended settings

• Nuclei detection with the multi-organ YOLO detector (--nuc-model-id 2).
• Graph built from intersection edges and standardised embeddings - tissue_inference.py defaults.

Postprocessing runs automatically. With --organ-name cord or membrane, tissue_inference.py also reclassifies the predictions based on spatial analysis and saves them alongside the tissue predictions as run_<id>_reclassed.hdf5:

• Umbilical cord: umbilical arteries and veins are relabelled so each vessel has a single label, with the largest vessel of each cord as the vein.
• Both: cells whose predicted type cannot occur in their predicted tissue are reassigned to the most likely type that can.

The original predictions are not changed. The cross-sectional area (cord) and colocalisation analyses in projects/cord_membrane/ read the reclassified file.

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 (placenta)	13,480 cells	2,723 cells	2,743 cells
Tissue classification (placenta)	471,944 nodes	156,225 nodes	140,641 nodes
Cell classification (umbilical cord)	7,873 cells	2,209 cells	2,214 cells
Cell classification (fetal membranes)	19,204 cells	5,391 cells	5,401 cells
Tissue classification (umbilical cord)	698,172 nodes	254,297 nodes	241,500 nodes
Tissue classification (fetal membranes)	92,137 nodes	21,114 nodes	21,668 nodes

The fetal membrane cell model was trained on the membrane and umbilical cord annotations together (of its training cells, 11,331 are from membranes and 7,873 from cord). The umbilical cord and fetal membrane tissue models were trained on 16 and 7 annotated slides; validation and test nodes come from held-out regions of the same slides.

Cell and tissue types

Cell types

• Placenta (11): cytotrophoblast (CYT), syncytiotrophoblast (SYN), syncytial knot (KNT), extra villus trophoblast (EVT), fibroblast (FIB), Hofbauer cell (HOF), mesenchymal cell (MES), vascular endothelial (VEN), vascular myocyte (VMY), maternal decidua (MAT), leukocyte (WBC).
• Umbilical cord (7): epithelial cell (EPI), vascular endothelial (VEN), mesenchymal cell (MES), fibroblast (FIB), myofibroblast (MFB), vascular myocyte (VMY), leukocyte (WBC).
• Fetal membranes (10): epithelial cell (EPI), vascular endothelial (VEN), mesenchymal cell (MES), fibroblast (FIB), myofibroblast (MFB), vascular myocyte (VMY), leukocyte (WBC), cytotrophoblast (CYT), extra villus trophoblast (EVT) and maternal decidua (MAT).

Tissue types (all three tissue models also predict an Unlabelled class)

• Placenta (9): villus sprout, terminal villi, mature intermediate villi, stem villi, anchoring villi, avascular villi, chorionic plate, basal plate/septum, fibrin
• Umbilical cord (9): amniotic epithelium; subamniotic, intermediate and perivascular Wharton's jelly; umbilical artery; umbilical vein; allantoic duct remnant; vitelline duct remnant; vitelline vessel remnant.
• Fetal membranes (5): amnion, chorion laeve, villous remnant, decidua capsularis, spiral artery.

Usage

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:

# 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>

For umbilical cord and fetal membranes:

python -m happy.db.download_models --project-name cord_membrane

This downloads the four cord and membrane files into projects/cord_membrane/trained_models/, and the YOLO nuclei detector into projects/placenta/trained_models/, where main.db expects them.

# umbilical cord; for fetal membranes use --organ-name membrane --cell-model-id 5 --tissue-model-id 3
python cell_inference.py  --project-name cord_membrane --organ-name cord \
    --nuc-model-id 2 --cell-model-id 4 --slide-id <slide>
python tissue_inference.py --project-name cord_membrane --organ-name cord \
    --tissue-model-id 2 --run-id <run> --k 10

Intended use & limitations

• Intended use: research on H&E histology WSIs of placenta, umbilical cord and fetal membranes. The YOLO nuclei detector generalises across the organs benchmarked above.
• Validate before use: cell and tissue models are trained on specific cohorts; 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. UC and MR models currently still under development so paper is not currently out, please contact us if using these models

@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}
}