Initial demo: classification gallery + state-overlay/tracking videos

.gitattributes

@@ -33,3 +33,15 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/gallery/fp_int2prem_0.gif filter=lfs diff=lfs merge=lfs -text
+assets/gallery/miss_mit2int_0.gif filter=lfs diff=lfs merge=lfs -text
+assets/gallery/miss_prem2int_0.gif filter=lfs diff=lfs merge=lfs -text
+assets/gallery/miss_prem2int_1.gif filter=lfs diff=lfs merge=lfs -text
+assets/gallery/ok_interphase_0.gif filter=lfs diff=lfs merge=lfs -text
+assets/gallery/ok_interphase_1.gif filter=lfs diff=lfs merge=lfs -text
+assets/gallery/ok_mitosis_0.gif filter=lfs diff=lfs merge=lfs -text
+assets/gallery/ok_mitosis_1.gif filter=lfs diff=lfs merge=lfs -text
+assets/gallery/ok_premitosis_0.gif filter=lfs diff=lfs merge=lfs -text
+assets/gallery/ok_premitosis_1.gif filter=lfs diff=lfs merge=lfs -text
+assets/videos/state_overlay.mp4 filter=lfs diff=lfs merge=lfs -text
+assets/videos/trackid.mp4 filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,13 +1,33 @@
 ---
-title: Cell Cycle State Demo
-emoji: 📉
-colorFrom: yellow
-colorTo: purple
+title: Temporal Cell State Prediction
+emoji: 🔬
+colorFrom: blue
+colorTo: red
 sdk: gradio
-sdk_version: 6.16.0
-python_version: '3.13'
+sdk_version: 5.49.1
 app_file: app.py
 pinned: false
+license: mit
+short_description: Frozen V-JEPA-2 predicts cell-cycle state in microscopy
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Temporal Cell State Prediction in Microscopy
+
+A frozen **V-JEPA-2 ViT-L** encoder + a small attentive-pool head predicts per-cell
+cell-cycle state (interphase / pre-mitosis / mitosis) directly from short single-cell
+clips — replacing the *classify* stage of the conventional segment → track → classify
+pipeline with a single clip → state model.
+
+This Space serves **pre-computed** results (no heavy model load on the free CPU tier):
+
+1. **Classification gallery** — correct calls + the characteristic failure modes.
+2. **Videos** — whole-FOV predicted-state overlay + a Trackastra-style tracking view.
+3. **Counting** — the same frozen encoder probed for per-state cell counts (honest: beats a null on total, not per-state).
+4. **VLM point-reasoning** — a zero-shot "point at each nucleus then sum" baseline.
+
+**Study finding:** in this small-data regime, **data scaling, not model scaling, is the
+binding constraint** — moving the baseline from a small to a larger labelled dataset lifts
+macro-F1 far more than an ~80× larger encoder does.
+
+- Models: [`DnaRnaProteins/vjepa2-cell-cycle-vit-l`](https://huggingface.co/DnaRnaProteins/vjepa2-cell-cycle-vit-l), [`DnaRnaProteins/unet-bilstm-cell-cycle-baseline`](https://huggingface.co/DnaRnaProteins/unet-bilstm-cell-cycle-baseline)
+- Data: MICCAI Cell Tracking Challenge — Fluo-N2DL-HeLa. Labels derived from lineage trees (no manual annotation).

app.py

@@ -0,0 +1,123 @@
+"""
+Temporal Cell State Prediction — interactive demo (HF Space).
+
+Frozen V-JEPA-2 ViT-L + a small attentive-pool head predicts per-cell cell-cycle
+state (interphase / pre-mitosis / mitosis) directly from short single-cell clips,
+replacing the classify stage of the segment->track->classify pipeline.
+
+The Space serves PRE-COMPUTED results (no heavy model load on the free CPU tier):
+a classification gallery (successes + failure modes), state-overlay + tracking videos,
+the per-state counting probe, and a zero-shot VLM point-reasoning baseline.
+
+Thesis of the study: in this small-data regime, *data scaling*, not model scaling,
+is the binding constraint.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import gradio as gr
+
+ASSETS = Path(__file__).parent / "assets"
+
+
+def _load_json(name: str, default):
+    p = ASSETS / name
+    return json.loads(p.read_text()) if p.exists() else default
+
+
+METRICS = _load_json("metrics.json", {})
+GALLERY = _load_json("gallery/gallery_manifest.json", [])
+
+
+# ── Header / thesis ───────────────────────────────────────────────────────────
+HEADER = """
+# 🔬 Temporal Cell State Prediction in Microscopy
+**Frozen V-JEPA-2 ViT-L + attentive-pool head → per-cell cell-cycle state**, straight from a tracked clip —
+no segment→track→**classify** hand-off.
+
+> **Finding:** a frozen video foundation model is competitive with a purpose-built
+> morphology–temporal baseline, and the binding constraint is **data scale, not model capacity.**
+"""
+
+
+def _metrics_md() -> str:
+    m = METRICS
+    if not m:
+        return "_metrics.json not found_"
+    cm = m.get("confusion")
+    lines = [
+        "### Held-out HeLa (sequence 02, n=%s)" % m.get("n", "?"),
+        "",
+        "| model | macro-F1 | mitosis F1 | mitosis event P/R (±3fr) |",
+        "|---|---|---|---|",
+        f"| U-Net+BiLSTM baseline (3.8M) | {m.get('baseline_macro_f1','?')} | {m.get('baseline_mitosis_f1','?')} | {m.get('baseline_mit_pr','?')} |",
+        f"| **frozen V-JEPA-2 head-only** | **{m.get('vjepa_macro_f1','?')}** | {m.get('vjepa_mitosis_f1','?')} | {m.get('vjepa_mit_pr','?')} |",
+        "",
+        f"*Data scaling (GOWT1→HeLa) lifts the same baseline +0.186 macro-F1; ~80× model scaling adds only +0.046.*",
+        f"*Seed band: {m.get('seed_band','0.635 ± 0.098')} — single-seed gaps <0.08 are not significant.*",
+    ]
+    if cm:
+        lines += [
+            "",
+            "**Confusion matrix** (rows = true, cols = pred):",
+            "",
+            "| true ⧵ pred | interphase | pre-mitosis | mitosis | recall |",
+            "|---|---|---|---|---|",
+        ]
+        names = ["interphase", "pre-mitosis", "mitosis"]
+        for i, nm in enumerate(names):
+            row = cm[i]; rec = row[i] / max(sum(row), 1)
+            lines.append(f"| **{nm}** | {row[0]} | {row[1]} | {row[2]} | {rec:.2f} |")
+        lines.append("")
+        lines.append("*Dominant error: pre-mitosis→interphase — a soft, lineage-defined 8-frame window with no sharp morphological boundary.*")
+    return "\n".join(lines)
+
+
+def _gallery_items():
+    items = []
+    for g in GALLERY:
+        img = ASSETS / "gallery" / g.get("gif", g.get("png", ""))
+        if img.exists():
+            tag = "✅" if g.get("correct") else "❌"
+            items.append((str(img), f"{tag} {g['title']} — {g['caption']}"))
+    return items
+
+
+def build():
+    with gr.Blocks(title="Cell State Prediction Demo", theme=gr.themes.Soft()) as demo:
+        gr.Markdown(HEADER)
+        with gr.Tabs():
+            with gr.Tab("① Classification gallery"):
+                gr.Markdown("Single-cell clips → predicted state. Correct calls **and** the characteristic failure modes.")
+                gr.Gallery(value=_gallery_items(), columns=4, height=420,
+                           object_fit="contain", label="input clip → prediction")
+                gr.Markdown(_metrics_md())
+
+            with gr.Tab("② Videos"):
+                gr.Markdown("Whole field-of-view over the held-out sequence.")
+                with gr.Row():
+                    so = ASSETS / "videos" / "state_overlay.mp4"
+                    ti = ASSETS / "videos" / "trackid.mp4"
+                    if so.exists():
+                        gr.Video(str(so), label="Predicted cell-cycle state (blue=interphase, amber=pre-mitosis, red=mitosis)", autoplay=True)
+                    if ti.exists():
+                        gr.Video(str(ti), label="Trackastra-style tracking (colour = track ID)", autoplay=True)
+
+            with gr.Tab("③ VLM point-reasoning (zero-shot)"):
+                gr.Markdown("A frontier VLM prompted to **point at each nucleus while reasoning**, then sum per state — "
+                            "the 'visual primitives' recipe. Zero-shot baseline (no fine-tune); OOD-limited, shown for interpretability.")
+                vlm = ASSETS / "vlm" / "vlm_overlay.png"
+                if vlm.exists():
+                    gr.Image(str(vlm), label="VLM predicted points (○) vs ground-truth centroids (×)")
+                gr.Markdown((ASSETS / "vlm" / "vlm_trace.md").read_text() if (ASSETS / "vlm" / "vlm_trace.md").exists() else "")
+
+        gr.Markdown("---\nModels: `DnaRnaProteins/vjepa2-cell-cycle-vit-l`, `DnaRnaProteins/unet-bilstm-cell-cycle-baseline` · "
+                    "Data: MICCAI Cell Tracking Challenge (Fluo-N2DL-HeLa). Labels derived from lineage trees (no manual annotation).")
+    return demo
+
+
+if __name__ == "__main__":
+    build().launch()

assets/gallery/gallery_manifest.json

@@ -0,0 +1,132 @@
+[
+  {
+    "gif": "ok_interphase_0.gif",
+    "png": "ok_interphase_0.png",
+    "true": "interphase",
+    "pred": "interphase",
+    "conf": 1.0,
+    "caption": "true=interphase -> pred=interphase (1.00)",
+    "category": "ok_interphase",
+    "title": "Correct: interphase",
+    "cell_id": 2,
+    "t": 9,
+    "correct": true
+  },
+  {
+    "gif": "ok_interphase_1.gif",
+    "png": "ok_interphase_1.png",
+    "true": "interphase",
+    "pred": "interphase",
+    "conf": 1.0,
+    "caption": "true=interphase -> pred=interphase (1.00)",
+    "category": "ok_interphase",
+    "title": "Correct: interphase",
+    "cell_id": 460,
+    "t": 62,
+    "correct": true
+  },
+  {
+    "gif": "ok_premitosis_0.gif",
+    "png": "ok_premitosis_0.png",
+    "true": "pre-mitosis",
+    "pred": "pre-mitosis",
+    "conf": 1.0,
+    "caption": "true=pre-mitosis -> pred=pre-mitosis (1.00)",
+    "category": "ok_premitosis",
+    "title": "Correct: pre-mitosis",
+    "cell_id": 369,
+    "t": 45,
+    "correct": true
+  },
+  {
+    "gif": "ok_premitosis_1.gif",
+    "png": "ok_premitosis_1.png",
+    "true": "pre-mitosis",
+    "pred": "pre-mitosis",
+    "conf": 1.0,
+    "caption": "true=pre-mitosis -> pred=pre-mitosis (1.00)",
+    "category": "ok_premitosis",
+    "title": "Correct: pre-mitosis",
+    "cell_id": 259,
+    "t": 32,
+    "correct": true
+  },
+  {
+    "gif": "ok_mitosis_0.gif",
+    "png": "ok_mitosis_0.png",
+    "true": "mitosis",
+    "pred": "mitosis",
+    "conf": 1.0,
+    "caption": "true=mitosis -> pred=mitosis (1.00)",
+    "category": "ok_mitosis",
+    "title": "Correct: mitosis",
+    "cell_id": 711,
+    "t": 44,
+    "correct": true
+  },
+  {
+    "gif": "ok_mitosis_1.gif",
+    "png": "ok_mitosis_1.png",
+    "true": "mitosis",
+    "pred": "mitosis",
+    "conf": 1.0,
+    "caption": "true=mitosis -> pred=mitosis (1.00)",
+    "category": "ok_mitosis",
+    "title": "Correct: mitosis",
+    "cell_id": 298,
+    "t": 32,
+    "correct": true
+  },
+  {
+    "gif": "miss_prem2int_0.gif",
+    "png": "miss_prem2int_0.png",
+    "true": "pre-mitosis",
+    "pred": "interphase",
+    "conf": 1.0,
+    "caption": "true=pre-mitosis -> pred=interphase (1.00)",
+    "category": "miss_prem2int",
+    "title": "Failure: pre-mitosis read as interphase",
+    "cell_id": 584,
+    "t": 38,
+    "correct": false
+  },
+  {
+    "gif": "miss_prem2int_1.gif",
+    "png": "miss_prem2int_1.png",
+    "true": "pre-mitosis",
+    "pred": "interphase",
+    "conf": 1.0,
+    "caption": "true=pre-mitosis -> pred=interphase (1.00)",
+    "category": "miss_prem2int",
+    "title": "Failure: pre-mitosis read as interphase",
+    "cell_id": 302,
+    "t": 8,
+    "correct": false
+  },
+  {
+    "gif": "miss_mit2int_0.gif",
+    "png": "miss_mit2int_0.png",
+    "true": "mitosis",
+    "pred": "interphase",
+    "conf": 1.0,
+    "caption": "true=mitosis -> pred=interphase (1.00)",
+    "category": "miss_mit2int",
+    "title": "Failure: missed mitosis (read as interphase)",
+    "cell_id": 586,
+    "t": 46,
+    "correct": false
+  },
+  {
+    "gif": "fp_int2prem_0.gif",
+    "png": "fp_int2prem_0.png",
+    "true": "interphase",
+    "pred": "pre-mitosis",
+    "conf": 1.0,
+    "caption": "true=interphase -> pred=pre-mitosis (1.00)",
+    "category": "fp_int2prem",
+    "title": "Failure: interphase over-called pre-mitosis",
+    "cell_id": 783,
+    "t": 8,
+    "correct": false
+  }
+]

assets/metrics.json

@@ -0,0 +1,28 @@
+{
+  "baseline_macro_f1": "0.629",
+  "baseline_mitosis_f1": "0.599",
+  "baseline_mit_pr": "0.65 / 0.62",
+  "vjepa_mitosis_f1": "0.681",
+  "vjepa_mit_pr": "0.69 / 0.74",
+  "seed_band": "0.635 \u00b1 0.098 (3 seeds)",
+  "counting_md": "**Total count:** the density head beats a mean-count null and a classical blob detector by ~3\u20135\u00d7. **Per-state:** it does *not* beat the null \u2014 interphase MAE stays high and pre-mitosis/mitosis look low only because predicting ~0 is almost right. The data bottleneck recurs (report Appendix C).",
+  "n": 5312,
+  "vjepa_macro_f1": "0.6776",
+  "confusion": [
+    [
+      4550,
+      211,
+      52
+    ],
+    [
+      173,
+      136,
+      14
+    ],
+    [
+      44,
+      7,
+      125
+    ]
+  ]
+}

assets/videos/state_overlay.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:991fc1ed3db265d3b86776566a89f4d911b0969247eaa19b6e9dd169c3fd72cc
+size 22679054

assets/videos/trackid.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fe2b552191a1b145602db385554e90040fa542b2c4536ad26ba4982db6cc871e
+size 22132096

requirements.txt

@@ -0,0 +1 @@
+gradio>=5