Upload README.md with huggingface_hub

README.md

@@ -5,42 +5,53 @@ tags:
 - dna-methylation
 - methylation
 - wgbs
-- imputation
 - single-cell
+- imputation
+- deconvolution
+- cell-type-annotation
 ---
 
-# MethScope — whole-genome methylation upscaler (`hg38_wg.updecx`)
+# MethScope — pretrained models
 
-Pretrained **whole-genome CpG upscaler** for
-[methscope-cli](https://github.com/zhou-lab/methscope-cli). A single
-self-contained bundle (`.updecx`) — the `UPDEC2` decoder plus its 1000-pattern
-MRMP feature definition — that reconstructs dense CpG methylation from a sparse
-query methylome.
+Pretrained models for [**methscope-cli**](https://github.com/zhou-lab/methscope-cli):
+ultra-fast analysis of sparse DNA methylomes via MRMP (Most Recurrent Methylation
+Pattern) encoding. Each model is a **single self-contained bundle** that already
+carries its MRMP feature definition (and labels / signature), so a query `.cg`
+runs directly — no separate annotation files.
 
-## Usage
+## Fetch & run
 
 ```sh
-# fetch the model
-hf download zhou-lab/methscope hg38_wg.updecx --local-dir .
+# fetch one model (or --local-dir models to grab all)
+hf download zhou-lab/methscope hg38_celltype.ubjx --local-dir .
 
-# impute genome-wide CpG methylation from a sparse .cg
-methscope upscale -o imputed.cg hg38_wg.updecx sparse.cg
+methscope predict query.cg    hg38_celltype.ubjx      # cell type / label
+methscope deconv  mixture.cg  hg38_65celltypes.refx    # cell-type proportions (NNLS)
+methscope upscale -o out.cg   hg38_wg.updecx  query.cg # genome-wide CpG upscaling
+methscope inspect             hg38_sex.ubjx            # framework, labels, features
 ```
 
-Inference is pure C — no CUDA or BLAS at run time (~2 s / sample, ~3 GB RAM).
-
-## Model
-
-| | |
-|---|---|
-| genome | hg38 (29,401,795 CpGs) |
-| input | 1000 MRMP features (beta + missing indicator) |
-| architecture | `UPDEC2` — one processing unit per MRMP membership, N16 leaky low-rank factor, uniform rank |
-| training | Loyfer sorted-cell WGBS (207 cells), fixed-29k simulated sparse queries |
-| external validation | 2018_Zhou cohort, genome-uniform MAE **0.1076** (beats the per-block baseline; see the lab journal) |
-| size | 2.8 GB |
-
-Trained with `methscope upscale-train` (CUDA). See the
-[methscope-cli documentation](https://zhou-lab.github.io/methscope-cli/) and the
-[model catalog](https://github.com/zhou-lab/methscope_data) for the classifier
-and deconvolution bundles.
+Small query `.cg` test fixtures (typed cells, a deconvolution mixture, an
+upscale input + truth) live in the GitHub repo
+[`zhou-lab/methscope_data`](https://github.com/zhou-lab/methscope_data) under
+`test/`, alongside this catalog and the MRMP-construction reproducibility archive.
+
+## Models
+
+| file | task | framework | labels / notes |
+|------|------|-----------|----------------|
+| `hg38_wg.updecx` | whole-genome CpG upscaling | `UPDEC2` | all 29,401,795 hg38 CpGs; the primary upscaler (2.8 GB) |
+| `hg38_10k1.updecx` | CpG upscaling (single block) | MLP decoder | block 10k1 (10,000 CpGs); small demo model |
+| `hg38_celltype.ubjx` | cell-type annotation | xgboost | 62 human cell types |
+| `mm10_celltype.ubjx` | cell-type annotation | xgboost | 41 mouse-brain cell types |
+| `hg38_sex.ubjx` | sex prediction | logistic | Female, Male (XCI `Xa_hi`/`Xa_lo` markers) |
+| `hg38_65celltypes.refx` | cell-type deconvolution (NNLS) | refx | 65 types = 58 Zhou + 7 Loyfer organ/blood; split MRMP, 15,300 patterns |
+
+`methscope inspect <model>` prints the exact framework, full label list, and (for
+linear models) per-feature weights. Classifiers carry a required framework `kind`
+mark (`xgboost` / `threshold` / `logistic`); `predict` rejects an unmarked
+bundle. Upscale decoders (`.updecx`) run via `upscale`, deconvolution references
+(`.refx`, `kind=refx`) via `deconv`.
+
+See the [methscope-cli documentation](https://zhou-lab.github.io/methscope-cli/)
+for the full command reference and runnable examples.