Skip to contents

methscope-cli

methscope-cli.Rmd

Overview

MethScope is the R package interface for MRMP-based sparse methylome analysis. For users who prefer a standalone command-line workflow, we also provide methscope-cli, a pure-C implementation and the recommended interface for the newest MethScope models:

https://zhou-lab.github.io/methscope-cli/

methscope-cli provides a single methscope binary for:

  • building and inspecting MRMP feature sets
  • classifying sparse methylomes with bundled classifier models
  • deconvolving mixed samples with bundled reference panels
  • upscaling or imputing sparse CpG methylation profiles

It uses YAME .cg input files and fetchable model/data bundles. The current bundle formats are self-contained: classifier bundles (.clfx) carry the model, MRMP feature definition, and labels; deconvolution references (.msdref) carry the signature panel; upscaling decoders (.updecx) carry the decoder and runtime feature definition. No R runtime is required.

When to Use methscope-cli

Use the R package when you want an interactive analysis workflow inside R, including plotting, training, and integration with R objects.

Use methscope-cli when you want:

  • command-line batch processing
  • integration into shell/HPC workflows
  • a no-R-runtime implementation
  • direct CLI prediction, matrix generation, deconvolution, or upscaling

Install methscope-cli

The easiest installation path is conda:

conda create -n methscope -c zhou-lab -c conda-forge methscope yame
conda activate methscope

For Linux users who want the CUDA training backend for upscale-train, install the optional GPU package:

conda install -c zhou-lab -c conda-forge methscope-cuda

Most workflows, including MRMP building, classification, deconvolution, and upscaling inference, use the pure-C CPU binary and do not require a GPU.

You can also build from source:

git clone --recurse-submodules https://github.com/zhou-lab/methscope-cli.git
cd methscope-cli
make

Use make CUDA=1 if you are building the optional CUDA training backend.

Fetching Data and Models

The CLI documentation uses yame fetch -c to download digest-checked example data and pretrained models into the current working directory:

mkdir -p ~/tmp/methscope
cd ~/tmp/methscope

yame fetch -c hg38/data/human_hg38_celltypes.cg
yame fetch -c hg38/models/hg38_celltype.clfx

Downloads are written atomically and verified, which makes this workflow safe for scripted runs, containers, and HPC jobs.

Example Commands

The live documentation at https://zhou-lab.github.io/methscope-cli/ is the source of truth for the most current examples. The commands below summarize the main workflows.

Build and Inspect MRMPs

Build a small chr20 MRMP feature set and inspect the ranked patterns:

mkdir -p ~/tmp/methscope
cd ~/tmp/methscope

yame fetch -c hg38/data/human_hg38_40_celltypes_chr20.cg
methscope mrmp-build human_hg38_40_celltypes_chr20.cg chr20_40celltypes.mrmp
methscope inspect chr20_40celltypes.mrmp --patterns --top 5

Export a runtime .cm mask when you need inspection or interoperability with other tools:

methscope mrmp-export --top 1000 chr20_40celltypes.mrmp chr20_40celltypes.cm

Cell-Type Prediction 

mkdir -p ~/tmp/methscope
cd ~/tmp/methscope

yame fetch -c hg38/data/human_hg38_celltypes.cg
yame fetch -c hg38/models/hg38_celltype.clfx
methscope classify hg38_celltype.clfx human_hg38_celltypes.cg

The .clfx bundle contains the classifier, labels, and MRMP feature definition, so users do not need to pass a separate .cm file.

Inspect a Model Bundle 

yame fetch -c hg38/models/hg38_sex.clfx
methscope inspect hg38_sex.clfx

inspect reports the sections inside the bundle, including the MRMP feature definition, model kind, model payload, and labels.

Deconvolution 

mkdir -p ~/tmp/methscope
cd ~/tmp/methscope

yame fetch -c hg38/data/human_hg38_immune_mixture.cg
yame fetch -c hg38/models/hg38_62celltypes.msdref
methscope deconv hg38_62celltypes.msdref human_hg38_immune_mixture.cg

Use --report for a human-readable summary and --wide for a full sample-by-cell-type table:

methscope deconv --report hg38_62celltypes.msdref human_hg38_immune_mixture.cg
methscope deconv --wide hg38_62celltypes.msdref human_hg38_immune_mixture.cg

Upscaling 

mkdir -p ~/tmp/methscope
cd ~/tmp/methscope

yame fetch -c hg38/data/human_hg38_test.cg
yame fetch -c hg38/models/hg38_10k1.updecx
methscope upscale -o human_hg38_test_reconstructed.cg \
  hg38_10k1.updecx human_hg38_test.cg

The default output stores predicted methylation fractions. Use --binary when a downstream tool needs 0/1 calls:

methscope upscale --binary -o human_hg38_test_calls.cg \
  hg38_10k1.updecx human_hg38_test.cg

Train Your Own Classifier

The CLI can featurize training cells and labels once, then train a self-contained classifier bundle:

mkdir -p ~/tmp/methscope
cd ~/tmp/methscope

yame fetch -c hg38/data/human_hg38_40_celltypes_chr20.cg
methscope mrmp-build --flat human_hg38_40_celltypes_chr20.cg chr20.mrmp

cut -f1 human_hg38_40_celltypes_chr20.cg.idx > labels.txt
methscope classify-featurize -l labels.txt -o chr20.msfm \
  human_hg38_40_celltypes_chr20.cg chr20.mrmp
methscope classify-train --data chr20.msfm -o chr20_celltype.clfx
methscope classify chr20_celltype.clfx human_hg38_40_celltypes_chr20.cg

For custom labels, make sure the label file matches the query/sample order in the .cg.idx file and that the labels are compatible with the classes used to build the MRMP.

Train an Upscaling Decoder

Training a decoder is a three-step pipeline: build MRMP features, featurize the truth atlas, assign CpGs to processing units, then fit the decoder.

mkdir -p ~/tmp/methscope
cd ~/tmp/methscope

yame fetch -c hg38/data/human_hg38_40_celltypes_chr20.cg
methscope mrmp-build --flat --force human_hg38_40_celltypes_chr20.cg chr20.mrmp

methscope upscale-featurize --reps 20 --sample 8000 \
  human_hg38_40_celltypes_chr20.cg chr20.mrmp chr20.msur
methscope upscale-set-units --unit-cpgs 4096 \
  human_hg38_40_celltypes_chr20.cg chr20.msui
methscope upscale-train -i chr20.msur --units chr20.msui --mrmp chr20.mrmp \
  -o chr20.updecx --work-dir work/ --threads 8

The CPU backend is portable. A CUDA build can accelerate upscale-train, and checkpoints are interchangeable between CPU and GPU runs.

Relationship to the R Package

The two implementations are complementary:

  • MethScope R package: legacy interactive R analysis, plotting, training, visualization, and R-based downstream workflows.
  • methscope-cli: current standalone command-line workflow for production, batch, container, and HPC use, including the newest shipped models.

For the complete methscope-cli documentation, model bundle formats, and test examples, see:

https://zhou-lab.github.io/methscope-cli/

Notes on Input Order

methscope-cli emits one row per query record in query-file order. When supplying labels for training or evaluation, make sure the labels follow the same query record order. In the MethScope R package tutorial, the example labels follow the .cg.idx sample order.