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:

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

methscope-cli implements the main command-line path:

query .cg + MRMP reference -> cell-by-pattern matrix -> prediction/deconvolution/upscaling

It uses YAME for .cg/.cm input/output and summary computation, and links libxgboost for model inference. It does not require an R runtime.

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

Build methscope-cli

methscope-cli depends on YAME, vendored as a git submodule, and libxgboost from conda-forge.

# Clone with the YAME submodule
git clone --recurse-submodules https://github.com/zhou-lab/methscope-cli.git
cd methscope-cli

# Install libxgboost
conda create -n methscope -c conda-forge libxgboost
conda activate methscope

# Build the CLI
make

If libxgboost is installed outside the active conda environment, pass its prefix explicitly:

make XGB_PREFIX=/path/to/conda/env

The built binary is named methscope.

Example Commands

The exact model and fixture files are documented in the methscope-cli repository. The commands below show the main usage pattern.

Cell-Type Prediction 

methscope predict query.cg model.ubjx > prediction.tsv

Here, query.cg is a YAME .cg file and model.ubjx is a bundled methscope-cli XGBoost classifier. Model bundles can carry their own MRMP reference, so users do not need to pass a separate .cm file when using a self-contained bundle.

Generate a Feature Matrix 

methscope matrix query.cg model_or_mrmp > input_pattern.tsv

This generates a sample-by-MRMP feature matrix analogous to GenerateInput() in the R package.

Deconvolution 

methscope deconv mixture.cg reference.refx > deconv.tsv

The .refx file is a methscope-cli deconvolution reference bundle (a signature + its MRMP, built with matrix --refx). Deconvolution uses all patterns in the reference.

Upscaling 

methscope upscale -o reconstructed.cg upscale_model.updecx sparse_input.cg

This reconstructs CpG-level methylation calls from sparse input using an upscaling decoder bundle.

Runnable example

A complete, copy-pasteable example. It downloads a pretrained classifier and a small test .cg from the methscope_data repository and runs cell-type prediction (assumes the methscope binary is on your PATH).

# fetch a classifier bundle + 4 typed test cells from methscope_data
MD=https://raw.githubusercontent.com/zhou-lab/methscope_data/main
wget -q $MD/models/hg38_celltype.ubjx
wget -q $MD/test/human_hg38_celltypes.cg $MD/test/human_hg38_celltypes.cg.idx

# predict cell types — the .ubjx bundle carries its own MRMP reference
methscope predict human_hg38_celltypes.cg hg38_celltype.ubjx

Expected output — each query cell (named by its Loyfer 2023 ground truth) gets the concordant Zhou2025 label and a confidence score:

cell             prediction_label  confidence
Oligodendrocyte  ODC               0.915
Pancreas-Beta    Beta              0.931
Blood-NK         NK CD16           0.813
Blood-Monocytes  Mono              0.836

For deconvolution, fetch the whole-body reference and a simulated mixture, then run deconv:

wget -q $MD/models/hg38_65celltypes.refx
wget -q $MD/test/human_hg38_immune_mixture.cg
methscope deconv human_hg38_immune_mixture.cg hg38_65celltypes.refx
#   -> Macrophage ~70%, Mono ~30%   (the other ~63 cell types ~0)

Relationship to the R Package

The two implementations are intended to be complementary:

  • MethScope R package: interactive R analysis, plotting, training, visualization, and R-based downstream workflows.
  • methscope-cli: standalone command-line processing for production, batch, and HPC workflows.

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

https://github.com/zhou-lab/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.