MethScope — pretrained models

Pretrained models for 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.

Fetch & run

# fetch one model (or --local-dir models to grab all)
hf download zhou-lab/methscope hg38_celltype.clfx --local-dir .

methscope classify query.cg   hg38_celltype.clfx       # cell type / label
methscope upscale -o out.cg   hg38_wg.updecx  query.cg # genome-wide CpG upscaling
methscope inspect             hg38_sex.clfx            # framework, labels, features

The file extension names the model's role — .clfx classifier, .updecx upscale decoder. Both are the same MSBNDL1 container and are detected by magic, never by name. Classifiers used to be .ubjx, which described a payload format (a UBJSON booster) rather than a role and had already stopped being accurate for the non-booster frameworks; .ubjx is still accepted everywhere and nothing needs renaming locally.

Flat single-booster classifiers are no longer scoreable. A classifier is now always a routing tree — a model that does not branch is simply a one-node tree, so nothing expressible was lost — and methscope classify rejects the old flat format with a message telling you to retrain. The last one published here, mm10_celltype.ubjx, has been removed; use mm10_celltype_brain.clfx.

Small query .cg test fixtures (typed cells, a deconvolution mixture, an upscale input + truth) live in the GitHub repo 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; v5 primary upscaler (2.8 GB). Its decoder upgrade is deferred to v9.
hg38_10k1.updecx	CpG upscaling (single block)	MLP decoder	block 10k1 (10,000 CpGs); small demo model
hg38_celltype.clfx	cell-type annotation (human)	xgboost, routing tree	33 human cell types; 11-node tree + 3 satellites; cross-cohort accuracy 0.903 — see below
mm10_celltype_brain.clfx	cell-type annotation (mouse brain)	xgboost, routing tree	41 mouse-brain cell types; 4-node tree + 134 satellites; class-balanced accuracy 0.969 ± 0.001 at native coverage (10-fold CV). Brain only — a non-brain cell is forced onto the nearest brain type
hg38_sex.clfx	sex prediction	logistic	Female, Male (XCI Xa_hi/Xa_lo markers)

methscope inspect <model> prints the exact framework, full label list, and (for linear models) per-feature weights. Classifiers carry a required framework kind mark (tree / violation / threshold / logistic); classify rejects an unmarked bundle, and rejects the retired flat xgboost mark. Upscale decoders (.updecx) run via upscale.

Deconvolution takes a standalone .msdref, not a bundle:

methscope deconv hg38_62celltypes.msdref mixture.cg -o props.tsv

hg38_62celltypes.msdref (v8) is the primary deconvolution reference: 60 cell types from the Zhou 2025 single-cell atlas pseudobulks (early-embryonic SCT/VCT excluded) plus Loyfer hepatocytes and BLUEPRINT granulocytes, packed as uint16 M/U over the 11.8 M CpGs that could ever separate some class subset (40.1% of hg38). The single-cell backbone matters: against the 33-class reference, whose immune compartment is BLUEPRINT bulk, single-cell-derived immune mixtures misread badly (a 70/30 macrophage/monocyte mixture returned 0.14/0.56), while the 62-class reference reads the same mixtures to within a few points of truth and resolves T-cell sub-types (Tmem/Tnaive × CD4/CD8).

hg38_33celltypes.msdref is the earlier bulk-pooled reference: 33 human cell types from donor-resolved normal WGBS (7.9 M kept CpGs, 26.9% of hg38). It replaces hg38_65celltypes.refx, which was withdrawn — the current methscope can neither read nor produce that format. For both references the solver rebuilds its pattern set per query from the CpGs that query actually measured, so no pattern budget is baked in.

The routing-tree classifiers

hg38_celltype.clfx and mm10_celltype_brain.clfx are not single classifiers. Each is a tree of boosters over one shared MRMP chain. A query is scored at the root, then handed to the child node that owns the root's call and scored again against that node's smaller, sharper class set. A node splits off only where enough patterns segregate its classes to justify one, so the shape is learned from the reference, not declared.

Alongside the hard children sit satellites — soft children written <node>@<tag>. A satellite lends extra columns to its owner's booster but takes no cells and has no model of its own, which lets a pair of classes that keep colliding get features built specifically to separate them without carving out a routing branch that a misroute could trap a cell in. Human uses 3; mouse brain needs 134.

Both are trained across a 24-rung coverage ladder with reads binarised, so one model spans sparse single cells and deep pseudobulks instead of being pinned to the depth of its training data. Records too sparse to score come back NA rather than guessed.

Human — 33 types

Held out across cohorts (each class's reference and its test samples come from different studies), 113 donor-resolved pseudobulks: accuracy 0.903, against 0.842 for the parameterless violation rule it replaced (still available as a classify option, see below). Every residual error is a within-lineage confusion — Macrophage → Monocyte six times, T.Cell.CD8 → T.Cell.CD4 twice. Lineage is not the failure mode.

Single-cell tumours, where the origin claim is tested. Bian is split by anatomical site because that is the whole point — a colorectal cancer cell sitting in liver must still read as colon:

cohort	called Enterocyte.(Colon)	n
Bian 2018 CRC, liver metastases	99.6%	247
Bian 2018 CRC, lymph metastases	82.6%	299
Bian 2018 CRC, right colon	92.1%	291
Bian 2018 CRC, left colon	91.1%	235
Bian 2018 CRC, rectum	97.1%	34
Bian 2018 adjacent normal (within-patient control)	95.4%	87
GI overall (colon + small intestine)	99.9%	1,193

Gaiti 2019 CLL reads B.Cell in 97.3% of cells above 100k covered CpGs (84.9% across all 2,616, including the sparse tail). Chaligne 2021 glioma splits Neuron 30.5% / Oligodendrocyte 28.2%, which is the honest answer for a cohort whose true origins — OPC, astrocyte — are not classes in this atlas.

Mouse brain — 41 types

Class-balanced accuracy 0.969 ± 0.001 at native coverage over 10-fold cross-validation (micro 0.963 ± 0.001), with the same tree shape recovered in every fold. Macro leads because the cohort is 23× imbalanced and micro cannot hear the eleven classes under 50 cells.

This model is brain only. It has no non-brain class, so a hepatocyte handed to it is forced onto the nearest brain type with no signal that anything is wrong. Route by tissue first, or use the human model's low-margin behaviour as the template for what this one cannot do.

--framework violation — classify with no trained model

Not a model but an option on classify. Every MRMP already carries a binstring — the methylation state each reference class takes at that pattern — so a reference is a per-class prediction already. The rule just asks which class the query contradicts least, and there is nothing to fit:

methscope classify --framework violation query.cg ref.mrmp

E1 = patterns the class expects methylated;  E0 = expects unmethylated
w_j = sqrt(n_cpg_j)

v1 = Σ_{j∈E1, observed} w_j·[β_j ≤ 0.5] / Σ_{j∈E1, observed} w_j
v0 = Σ_{j∈E0, observed} w_j·[β_j >  0.5] / Σ_{j∈E0, observed} w_j

predict argmin_class (v1 + v0), needing ≥20 observed patterns per side

Tune with --call-threshold, --pattern-weight, --min-patterns and --top. Because nothing is fitted, changing one is not a retrain — it just scores again.

What it is for. You have a reference and no training data. Build an MRMP over it and you have a classifier the same minute, over any label set, with no cohort of examples to assemble first. It is also the honest baseline for a trained model on the same features: it uses the reference and nothing else, so whatever a booster gains over it is what the training data bought.

confidence is the margin to the runner-up, not a probability. Unlike a softmax it collapses toward zero when no class fits, which is how a query whose true type is missing from the reference announces itself. Records too sparse to clear --min-patterns come back NA rather than guessed. Margins are not comparable between references with different class counts, so recalibrate any threshold per reference.

ref.mrmp must be a single flat set. Do not point it at a routing-tree chain such as hg38_celltype.clfx: the rule pools every set it finds, and a tree's sets have different class memberships, so the binstrings being compared are not commensurable. It currently fails silently — labels come back, with near-zero confidences and no warning.

Accuracy is coverage-dependent, and on the 33-type human reference it plateaued near 0.85 above ~130k covered CpGs against 0.163 below 8k. Do not use it below ~30k covered CpGs. For a bulk tumour, deconvolve rather than classify: a classifier assigns one label to a mixture.

See the methscope-cli documentation for the full command reference and runnable examples.