Card for CELL-FM as a multi-family checkpoint repo

README.md

@@ -8,20 +8,34 @@ tags:
   - flow-matching
 ---
 
-# CELL-FM CondenSeq weights
+# CELL-FM
 
-Checkpoints behind the CELL-FM CondenSeq demo
-(`HuangLab/CELL-FM-condenseq-demo`, pending a Team/Enterprise plan on the org).
+Model checkpoints for **CELL-FM**, a flow-matching model that generates cell
+microscopy images from protein sequence.
 
-The demo code lives in `huggingface_space/` in the CELL-FM repository and pulls these
-files at startup via `CELLFM_MODEL_REPO`.
+One subfolder per model family. Point a loader at the subfolder it needs; the
+demo code does this through `CELLFM_MODEL_REPO` + a path prefix.
+
+## `condenseq/` — sequence-conditioned condensate imaging
+
+Trained on CondenSeq, 160x160 GFP images. Drives the condensate titration demo:
+sequence in, condensate-probability curve out, integrated into AUC and AAC.
 
 | File | Model | Source checkpoint |
 |---|---|---|
-| `cellfm_seq2img.bin` | CELL-FM CS sequence-to-image generator (includes the ESM-C 600M encoder) | `pretrain_condenseq/cellfm_seq2img/checkpoint-50000` |
-| `vae.bin` | Image VAE, 160x160, 3 down blocks, 4 latent channels | `pretrain_condenseq/vae/checkpoint-50000` |
-| `vit_cls.bin` | ViT condensed/diffuse classifier, 2-channel 160x160 input | `PT_CondenSeq_img_ViT_cls_R1/checkpoint-10000` |
+| `condenseq/cellfm_seq2img.bin` | CELL-FM CS sequence-to-image generator, ESM-C 600M encoder included (745 M params) | `pretrain_condenseq/cellfm_seq2img/checkpoint-50000` |
+| `condenseq/vae.bin` | Image VAE, 160x160, 3 down blocks, 4 latent channels | `pretrain_condenseq/vae/checkpoint-50000` |
+| `condenseq/vit_cls.bin` | ViT condensed/diffuse classifier, 2-channel 160x160 input (26 M params) | `PT_CondenSeq_img_ViT_cls_R1/checkpoint-10000` |
+
+Hyperparameters mirror `scripts/cell_fm_cs/evaluate_seq2img.sh` and
+`scripts/vit_cls_condenseq_img/pretrain.sh` in the CELL-FM repository, and are set
+in `huggingface_space/pipeline.py` there.
+
+Reference values at 512 images / 100 ODE steps / seed 6: NUP98 WT gives AUC 0.4896
+and AAC 0.0001; its 1F->S mutant gives AUC 0.4561.
+
+## Adding a model family
 
-Hyperparameters are set in `pipeline.py` in the Space and mirror
-`scripts/cell_fm_cs/evaluate_seq2img.sh` and
-`scripts/vit_cls_condenseq_img/pretrain.sh` in the CELL-FM repository.
+Upload under a new prefix (`hpa/`, `opencell_3d/`, ...) and add a section here.
+`upload_weights.py` in the demo takes a `{path_in_repo: local_checkpoint}` map, so
+new families need only a new entry.