README.md

---
title: OpenMHC Leaderboard
emoji: 🫀
colorFrom: red
colorTo: gray
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# OpenMHC Leaderboard

Self-rendering leaderboard website for the OpenMHC wearable-health benchmark.
Currently serves **Track 2 — Imputation**, computed live from per-user error
substrate in the
[`MyHeartCounts/OpenMHC-leaderboard-data`](https://huggingface.co/datasets/MyHeartCounts/OpenMHC-leaderboard-data)
dataset.

## How it works

- `GET /` renders the leaderboard table (HTML).
- On first request the app downloads each method's `imputation/<method>.parquet`
  substrate, reduces it to paired skill scores + cross-method ranks using the
  canonical `openmhc` point-flow reducers, and caches the result in-process.
- `GET /health` — liveness + method count.

There is **no JSON API** — this Space *is* the leaderboard UI.

## Files

| file | role |
|---|---|
| `Dockerfile` | builds the container (slim deps + `openmhc --no-deps`) |
| `app.py` | FastAPI app: computes + renders the HTML leaderboard |
| `leaderboard_compute.py` | downloads substrate + runs the canonical reducers |
| `requirements.txt` | slim runtime deps (no torch) |

## Configuration

The substrate dataset is private, so set an **`HF_TOKEN`** Space secret with read
access (Settings → Variables and secrets). Making the dataset public removes this
requirement.

## Local dev

```bash
pip install -r requirements.txt
pip install --no-deps "openmhc @ git+https://github.com/AshleyLab/myheartcounts-dataset@<ref>"
export HF_TOKEN=hf_...
uvicorn app:app --reload --port 7860
# open http://localhost:7860/
```