# methscope # Agent-facing reference for the methscope CLI (DNA methylation inference). # Canonical: https://zhou-lab.github.io/methscope-cli/llms.txt # Human docs: https://zhou-lab.github.io/methscope-cli/ # Source of truth: docs/make_llms.py + the binary's own --help. ## What it is methscope infers cell-type composition, sample labels and CpG-level methylation from SPARSE methylomes -- the regime where a sample carries a few thousand to a few hundred thousand observed CpGs rather than whole-genome coverage. Pure C, no Python or R at inference, ~2 s per sample. Input is a YAME `.cg` store (see the yame tool). Models are self-contained bundles that carry their own feature definition: .updecx upscale decoder -- impute genome-wide CpG methylation .ubjx classifier -- cell type, sex .refx deconvolution ref -- cell-type proportions ## Install conda install -c zhou-lab -c conda-forge methscope conda install -c zhou-lab -c conda-forge methscope-cuda # linux-64, only # upscale-train # needs a GPU ## Getting models Models live on HuggingFace (zhou-lab/methscope) and are fetched through YAME's shared registry, which verifies each file against a pinned digest: yame fetch methscope/hg38/models # or mm10/models, hg38/data `methscope fetch` was RETIRED -- do not use it. Available: hg38_wg.updecx whole-genome upscale decoder (human) mm10_wg.updecx whole-genome upscale decoder (mouse) hg38_celltype.ubjx cell-type classifier (human, 62 types) mm10_celltype.ubjx cell-type classifier (mouse brain, 41 types) hg38_sex.ubjx sex classifier hg38_65celltypes.refx deconvolution reference (65 cell types) hg38_10k1.updecx upscale decoder for one 10k-CpG block (legacy, small) ## Traps These are the mistakes that are not visible in the usage strings. 1. `upscale` writes CONTINUOUS methylation fractions (YAME format 4). It used to threshold at 0.5 into 0/1 calls (format 6); `--binary` still does, but it is lossy and only appropriate when a downstream tool demands format 6. `--probs` emits a TSV of the same values. 2. One training msur serves MANY models. `upscale-featurize` stores the raw per-pattern summary (beta, covered count, observed set), not encoder input; `--features` and `--patterns` are chosen at TRAINING time and are just projections of it. So do not rebuild a msur to change either. `--patterns P` may be narrowed below the msur's pattern count but never widened past it, so featurize at the widest vocabulary you might want. 3. `inspect` describes ANY artifact -- bundle, .mrmp, .msui, .msur -- and is the fastest way to find out what an unlabeled file is and what it expects. 4. A bundle records what is needed to RUN a model, nothing about how it was trained. Provenance for the shipped models lives in the lab journal, not in the file. ## Commands mrmp-build Construct the MRMP artifact from a discretized reference .cg mrmp-export Emit the runtime .cm mask (and pattern / count tables) classify Classify a methylome -> labels + confidence classify-train Fit a label classifier (xgboost / threshold / logistic) deconv Estimate cell-type proportions (NNLS) from a mixture deconv-build-ref Build a .refx deconvolution reference (--matrix for the raw matrix) upscale Impute genome-wide CpG methylation from a sparse methylome upscale-featurize Build the MSURAW2/3 training msur from a truth .cg upscale-set-units Build the MSUIDX1 processing-unit index from a .mrmp upscale-train Train the whole-genome upscale decoder (CUDA) bundle Wrap a model + its MRMP into a self-contained bundle unbundle Unpack a bundle into its model, MRMP, and outcpg mask inspect Describe any artifact: bundle, .mrmp, .msui, or .msur ### methscope upscale Usage: methscope upscale [options] [input] Purpose: Impute CpG methylation from a sparse methylome. Unified UPDEC2 models predict the whole genome; legacy UPDEC1 block models remain readable. Both inference paths are pure C and require neither CUDA nor BLAS. Arguments: A bare decoder (.updec/.updec2) OR a bundle with the MRMP attached (.updecx, from `bundle`). The form selects the input below. [input] For .updec : a feature TSV (one row per sample, n_in numeric cols). For .updecx: a query .cg, featurized internally against the bundled MRMP. '-' or omitted reads from stdin; for .updec a header row is auto-detected and empty/NA fields are imputed with the model means. Options: -o Write output to a file instead of stdout (.cg is binary -- use -o). --binary Threshold predictions at 0.5 and write 0/1 calls (format 6). Lossy -- the default format 4 keeps the fraction itself. --probs Emit per-CpG probabilities as TSV instead of a .cg. -h Show this help message. Output: A YAME .cg (format 4: continuous methylation fraction), one record per input sample. UPDEC2 output is always in whole-genome CpG order. For legacy UPDEC1, if the bundle carries an outcpg.cm (the imputed-CpG locations), the .cg spans the whole genome with the block's CpGs predicted (no NA) and the rest NA; otherwise a dense block of n_out CpGs. With --binary, format 6 of 0/1 calls; with --probs, a TSV of per-CpG probabilities (one row per sample). ### methscope classify Usage: methscope classify [options] methscope classify [options] Purpose: Predict a label (cell type, sex, ... — whatever the model was trained on) and a confidence score for each query record, by featurizing the query against the MRMP reference and running the booster. Arguments: Query methylome(s); '-' reads a .cg stream from stdin (cells are then named 1,2,3,... as a stream has no index). A self-contained bundle of the booster + its MRMP (from `train -o model.ubjx` or `bundle`) — the recommended single-file form. MRMP pattern definition (a YAME .cm) to featurize the query (loose form). A bundle (.ubjx/.updecx) also works here. Loose booster with class labels embedded (see train / bundle -l). Options: -o Write output to a file instead of stdout. --probs Append one column per class with its predicted probability. --no-header Suppress the header line. -h Show this help message. Output columns: cell prediction_label confidence [ ... with --probs] ### methscope deconv Usage: methscope deconv [options] Purpose: Estimate per-cell cell-type proportions by non-negative least squares (NNLS) deconvolution against a cell-type signature reference. Arguments: Mixture methylome(s); '-' reads a .cg stream from stdin (cells are then named 1,2,3,... as a stream has no index). A self-contained reference bundle (signature + MRMP) from `matrix --refx`. '-' reads the .refx from stdin, so you can build + deconvolve in one pipe: matrix --refx -o - pseudobulk.cg ref.mrmp \ | deconv mixture.cg - Options: -o Write output to a file instead of stdout. --min-cov Per cell, only use patterns with >= k covered CpGs in the mixture (default: 1). Higher k (e.g. 3) drops thinly- covered, noisy patterns -- helps on sparse input. --no-header Suppress the header line. -h Show this help message. Output: One row per mixture cell; columns are cell types (proportions summing to 1). ### methscope inspect Usage: methscope inspect Purpose: Describe any methscope artifact without running it. The format is detected from its magic: .ubjx/.updecx/.refx bundle: kind mark, section layout, model breakdown .mrmp MRMPIDX1 pattern set: dimensions, binstring parameters, top ranks .msui MSUIDX1 processing-unit index: units, memberships, CpG split .msur MSURAW2/3 training msur: cells, replicates, embedded truth Options: --patterns .mrmp only: list the top-ranked patterns --top K .mrmp only: how many to list (default 20) -h Show this help message. ### Other commands Run `methscope -h` for these; they build or train artifacts and need a truth atlas, and upscale-train needs a GPU.