---
license: cc-by-4.0
tags:
- biology
- single-cell
- immunophenotyping
- protein
- adt
- cite-seq
- missionbio
- tapestri
- scikit-learn
library_name: scikit-learn
pipeline_tag: tabular-classification
---

# EspressoPro ADT Cell Type Models

## Model Summary

This repository provides pre-trained EspressoPro models for **cell type annotation from single-cell surface protein (ADT) data**, designed for **blood and bone marrow mononuclear cells** in protein-only settings (such as Mission Bio Tapestri DNA+ADT workflows).

The pipeline is available at: https://github.com/uom-eoh-lab-published/2026__EspressoPro

The release contains **one-vs-rest (OvR) binary classifiers per cell type** plus a **multiclass calibration layer** for **three annotation resolutions of increasing biological detail**.

## Model Details

- **Developed by:** Kristian Gurashi  
- **Model type:** Stacked ensemble OvR classifiers with Platt calibration  
  (logistic regression over XGB, NB, KNN, and MLP prediction probabilities)  
- **Input:** Per-cell ADT feature vectors (CLR-normalised surface protein expression)  
- **Output:** Per-cell class probabilities and predicted cell type labels  

### Included Files

The repository is organised by **reference atlas** (`Hao`, `Triana`, `Zhang`, `Luecken`) and by **label resolution** (`Broad`, `Simplified`, `Detailed`).  
Each atlas/resolution folder contains (i) the trained models, (ii) evaluation reports, and (iii) figures.

#### Models (`Release/<Atlas>/Models/<Resolution>/`)

- `Multiclass_models.joblib`  
  Main file for inference. Loads everything needed to run predictions for that atlas/resolution:
  - all per-class Platt calibrated OvR “heads”
  - `class_names` (probability column order)
  - excluded class list (if applicable)
  - multiclass temperature-scaling calibrator

#### Reports (`Release/<Atlas>/Reports/<Resolution>/`)

- `metrics/`  
  CSV exports of evaluation outputs, including:
  - multiclass accuracy metrics (precision/recall/F1/AUC) on the held-out test split
  - multiclass confusion matrix on the held-out test split
  - per-class accuracy metrics (precision/recall/F1/AUC) and confusion matrix on the held-out test split
  - per-class error rate pre and post calibrated on the held-out test split

- `probabilities/`  
  CSV exports comparing:
  - Multiclass label prediction probabilities on test set

#### Figures (`Release/<Atlas>/Figures/<Resolution>/`)

- `multiclass_confusion_matrix_on_test.png`  
  Multiclass confusion matrix for the held-out test split.

- `multiclass_confusion_matrix_on_test_with_percentage_agreement.png`  
  Multiclass confusion matrix for the held-out test split with % agreement between true label and predicted.

- `per_class/`  
  Per-class plots, including:
  - binary confusion matrix pre calibration
  - ROC curve (AUC) pre calibration
  - binary confusion matrix post calibration
  - ROC curve (AUC) post calibration
  - UMAP of the held-out train split
  - UMAP legend
  - calibration evaluation on the held-out test split
  - SHAP beeswarm on the held-out train split

## Uses

### Direct Use

Leveraged by **EspressoPro** to annotate cell types from **ADT-only** single-cell data (blood/bone marrow mononuclear cells), including Mission Bio Tapestri DNA+ADT datasets.

## Bias, Risks, and Limitations

- **Reference bias:** trained on human healthy donor PBMC/BMMC-derived references; performance may differ in disease or heavily perturbed samples. Not expected to work well in other tissues.
- **Panel dependence:** requires feature alignment to the expected ADT columns; missing/mismatched antibodies can reduce accuracy.
- **Class coverage:** Only classes which led to effective predictions from at least one of the four atlases were trained for prediction.
- **Interpretation:** probabilities are model-derived and should be validated with marker checks and expected biology.

## Testing Data, Factors & Metrics

### Testing Data
- **TRAIN**: used to train one-vs-rest (OvR) classifiers.  
- **CAL**: used only for probability calibration (Platt per class + multiclass temperature scaling).  
- **TEST**: used only for evaluation.

**Note:** CAL and TEST include only the classes learned from TRAIN; excluded or unknown labels are removed.

### Factors
- **RAW**: OvR probabilities before calibration.  
- **PLATT**: OvR probabilities after Platt calibration on CAL (skipped if CAL is single-class).  
- **CAL**: final multiclass probabilities after temperature scaling (fit on CAL, applied to TEST).

### Metrics
**Multiclass (TEST, using CAL probabilities):**
- Accuracy
- Precision / Recall / F1
- Confusion matrix

**Per-class (TEST, RAW vs CAL):**
- Confusion matrix (TP, FP, TN, FN)
- Precision, recall, F1
- ROC curve and AUC

**Calibration (per class, TEST):**
- LogLoss and Brier score before vs after Platt calibration