---
title: EnFormer Deep Ensemble Clustering
colorFrom: gray
colorTo: gray
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: apache-2.0
short_description: EnFormer ensemble clustering of two images
---

# EnFormer Deep Ensemble Clustering

Unsupervised clustering of **two image sets** built around
[**EnFormer**](https://github.com/En-Former/EnFormer) — *Deep Ensemble Clustering
for Visual Representation Learning*. The app runs out-of-the-box on a bundled
**clonogenic (colony-formation) assay** dataset of N2A cells irradiated at a range
of doses ± Vorinostat, and also accepts your own uploads.

## What it does

| Step | Component |
|------|-----------|
| **Feature extraction** | EnFormer-Small (ImageNet-1K pretrained) as a frozen backbone → 320-d embedding per image. Optional interpretable **morphology descriptors** (colour, stain darkness, edge/texture energy) are concatenated for stained micrographs. |
| **Ensemble Generation** | A diverse pool of base clusterers — **K-Means, Fuzzy C-Means, Gaussian-Mixture, Spectral, Agglomerative** — run over random feature subspaces. This mirrors EnFormer's own `PartitionalClustering / FuzzyClustering / ProbabilisticClustering` base modules. |
| **Consensus Aggregation** | Base partitions are fused into a **co-association matrix** (Evidence Accumulation Clustering) and the final partition is read off it (spectral / average-linkage). This mirrors EnFormer's Consensus Aggregation step. |
| **Outputs** | Per-cluster image montages · internal quality metrics (silhouette, Davies–Bouldin, Calinski–Harabasz) · alignment with any filename metadata (ARI / NMI) · 2-D t-SNE embedding · consensus heatmap · CSV of assignments. |

## Design honesty

These are small **5× tiles** of assay wells. Their colony density varies
*continuously* and each tile may show empty background, a well-edge arc, sparse
colonies, or dense staining. As a result:

- Clusters correspond to **coherent visual morphology modes** (empty · edge ·
  sparse-colony · dense), which is what unsupervised image clustering should
  recover. Silhouette is moderate (~0.15–0.25) *because the underlying variation is
  a continuum*, not because the clustering is poor — the per-cluster montages and
  the block structure of the co-association matrix confirm the groups are real.
- The **radiation dose / treatment label is *not* reliably recoverable** from a
  single tile (verified: neither deep features nor stain density track dose). The
  app reports this alignment as-is (ARI ≈ 0.05) instead of overstating it.

## Run locally

```bash
pip install -r requirements.txt
python app.py           # opens http://localhost:7860
```

## Model weights

The backbone weights (`weights/enformer_small.pth`, ~33 MB, model tensors only) are
bundled via Git LFS. If absent, the app downloads the official checkpoint from the
EnFormer GitHub release on first run, and if that also fails it falls back to a
torchvision **ConvNeXt-Tiny** backbone — so the Space always works.

## Files

- `app.py` — Gradio UI
- `pipeline.py` — images → features → consensus clustering → artifacts
- `features.py` — EnFormer / ConvNeXt feature extractor + morphology descriptors
- `ensemble_cluster.py` — ensemble generation + co-association consensus
- `data.py` — dataset loading & filename metadata parsing
- `enformer_models/` — vendored EnFormer model code (Apache-2.0, see `LICENSE_EnFormer`)
- `examples/1`, `examples/2` — bundled demo images (sampled from source folders 1 and 2)

## Credits

EnFormer model code and pretrained weights © the EnFormer authors, released under
Apache-2.0. This app vendors the classification backbone unchanged and uses it as a
feature extractor.