README.md

---
license: cc-by-nc-nd-4.0
base_model: bioptimus/H-optimus-0
library_name: transformers
pipeline_tag: feature-extraction
tags:
  - computational-pathology
  - histopathology
  - foundation-model
  - feature-extraction
  - scanner-robustness
---

# Mettle

Mettle is a histopathology tile encoder derived from H-optimus-0. It is designed to improve representation consistency across slide scanners and staining variation while retaining biologically useful morphology.

Mettle is intended for research feature extraction. It is not a diagnostic system and has not been validated for autonomous clinical use.

## Model details

| Item | Value |
|---|---|
| Parent model | [H-optimus-0](https://huggingface.co/bioptimus/H-optimus-0) |
| Parent-model license | Apache-2.0 |
| Architecture | ViT-g/14, DINOv2 reg4 |
| Input | 224 × 224 RGB histology tile |
| Compatibility output | 1,536-dimensional headed CLS embedding |
| Public benchmark output | 3,072-dimensional CLS+mean-patch embedding |
| `model.safetensors` SHA-256 | `7754ef463e79dd13b072247b56db39791c884db10774e354d76f76367093ce4a` |

The public benchmark representation concatenates the headed CLS embedding with the mean of the spatial patch tokens:

```text
[headed CLS embedding (1536), mean spatial-patch embedding (1536)]
```

CLS and register tokens are excluded from the patch mean. The first 1,536 coordinates are exactly the compatibility CLS representation.

## Public benchmark results

All results in this table use the 3,072-dimensional CLS+mean representation. Higher is better. Values after `±` are standard deviations over five downstream probe runs. PathoROB Robustness Index is a point estimate without an uncertainty interval.

| Benchmark | Metric | Mettle | H-optimus-0 |
|---|---|---:|---:|
| PathoROB | Mean Robustness Index | **0.92227** | 0.8015 |
| HEST | Mean Pearson, 9 tasks | **0.43032** | 0.42526 |
| EVA BACH | Accuracy | **0.78168** ± 0.00567 | 0.7294 |
| EVA CRC | Accuracy | **0.96912** | 0.9578 |
| EVA PatchCamelyon | Balanced accuracy | **0.9476** | 0.9441 |

### PathoROB breakdown

| Cohort | Mettle |
|---|---:|
| Camelyon | 0.93859 |
| TCGA | 0.86521 |
| Tolkach ESCA | 0.96302 |
| **Mean** | **0.92227** |

PathoROB does not provide uncertainty estimates for its Robustness Index. Differences in point estimates should not be described as statistical superiority.

### HEST task breakdown

HEST uses PCA to 256 dimensions followed by ridge regression for a 50-gene panel. The metric is Pearson correlation averaged over official splits.

| HEST task | Mettle | H-optimus-0 (CLS+mean) |
|---|---:|---:|
| IDC | 0.6104 | **0.6106** |
| PRAD | **0.3789** | 0.36215 |
| PAAD | **0.5309** | 0.5106 |
| SKCM | **0.6745** | 0.6614 |
| COAD | **0.3331** | 0.3089 |
| READ | 0.2372 | **0.2401** |
| CCRCC | 0.2552 | **0.2919** |
| LUNG | **0.5777** | 0.5754 |
| LYMPH_IDC | **0.2751** | 0.2665 |
| **Unweighted mean** | **0.4303** | **0.4253** |

The H-optimus-0 column is our own evaluation of the unmodified model using the same CLS+mean representation and protocol. Published H-optimus-0 HEST results use the conventional CLS-only embedding and average 0.4150, which would make this margin appear larger.

## Usage

Install the dependencies listed in `requirements.txt`, then load the image processor and model through the standard Transformers auto classes.

```python
import torch
from PIL import Image
from transformers import AutoImageProcessor, AutoModel

model_id = "slideflow-labs/Mettle"
processor = AutoImageProcessor.from_pretrained(model_id)
model = AutoModel.from_pretrained(
    model_id,
    trust_remote_code=True,
).eval().cuda()

image = Image.open("tile.png").convert("RGB")
pixel_values = processor(
    images=image,
    return_tensors="pt",
)["pixel_values"].cuda()

with torch.inference_mode():
    # Representation used for the public benchmarks: (batch, 3072)
    cls_mean = model.encode(pixel_values, feature_view="cls_mean")

    # Conventional compatibility representation: (batch, 1536)
    cls = model.encode(pixel_values, feature_view="cls")
```

## Choosing a representation

The reported public benchmarks use the 3,072-dimensional CLS+mean representation. The loader also exposes the 1,536-dimensional CLS embedding for compatibility; CLS can also be stronger on some endpoints.

## Intended use

Mettle is intended for research involving histopathology representation learning, feature extraction, model development, and robustness analysis. Users should validate the model on the intended tissue, acquisition hardware, population, and downstream endpoint.

Do not use Mettle as a standalone diagnostic system. Appropriate human oversight, validation, and compliance requirements remain necessary.

## Limitations

- Performance can vary with tissue type, preparation, stain, scanner, compression, magnification, and downstream protocol.
- Scanner consistency does not guarantee preservation of every biological signal or subgroup.
- The two output representations are endpoint-dependent; neither dominates every benchmark.
- PathoROB Robustness Index is reported without uncertainty estimates.
- Benchmark results do not establish clinical efficacy or safety.
- The parent model's limitations and license obligations continue to apply.

## References

- [H-optimus-0 model card](https://huggingface.co/bioptimus/H-optimus-0)
- [Towards robust foundation models for digital pathology
  (PathoROB)](https://doi.org/10.1038/s41467-026-73923-2)
- [HEST-1k: A Dataset for Spatial Transcriptomics and Histology Image
  Analysis](https://papers.neurips.cc/paper_files/paper/2024/file/60a899cc31f763be0bde781a75e04458-Paper-Datasets_and_Benchmarks_Track.pdf)
- [eva: Evaluation framework for pathology foundation
  models](https://openreview.net/forum?id=FNBQOPj18N)

## Citation

An arXiv preprint is forthcoming.

## License

Mettle is licensed under CC-BY-NC-ND-4.0, and is available for academic, non-commercial use.