---
title: "MethScope-Input"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{MethScope-Input}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
## Overview
MethScope uses YAME `.cg` files as methylation input. A `.cg` file is a compact
binary representation of methylation data in a fixed CpG order. Before running
`GenerateInput()`, the query `.cg` file and the MRMP reference `.cm` file must be
based on the same genome build and CpG coordinate order.
This tutorial shows common input-preparation patterns for:
- BED-like methylation files
- ALLC files
- beta or methylation fraction tables
- binary presence/absence tracks
For complete YAME command documentation, see .
YAME documentation describes the supported CX formats and the requirement that
input rows match the reference CpG coordinates exactly.
For ALLC files, this tutorial follows the ALLCools definition:
.
## Install command-line dependencies
Install YAME and bedtools before converting files.
```{bash, eval=FALSE}
conda install -c bioconda yame bedtools
```
## Choose the correct CpG reference
Use the CpG reference that matches the genome build of your data and the MethScope
MRMP reference. For example, use an `mm10` CpG reference with
`mm10_Liu2021.cm`, and use an `hg38` CpG reference with `hg38_Zhou2025.cm` or
`hg38_Loyfer2023.cm`.
The examples below assume that you have a YAME CpG reference file called
`cpg_reference.cr`. Convert it to BED once:
Reference `.cr` files can be downloaded from the Zhou lab KYCG knowledge-base
repositories:
- Human hg38:
- Mouse mm10:
```{bash, eval=FALSE}
yame unpack cpg_reference.cr | gzip > cpg_reference.bed.gz
```
The BED file created from the `.cr` reference defines the required row order for
the output `.cg` file.
## Convert M/U count BED files
Use YAME format 3 (`-f3`) when the input has methylated and unmethylated read
counts. This is the recommended format for bisulfite sequencing data when read
depth is available.
Expected input:
```text
chr1 3000826 3000827 4 6
chr1 3001006 3001007 0 8
```
where columns are:
```text
chrom start end M U
```
Align the file to the reference CpG coordinates and pack:
```{bash, eval=FALSE}
bedtools sort -i sample_mu.bed > sample_mu.sorted.bed
bedtools intersect \
-a cpg_reference.bed.gz \
-b sample_mu.sorted.bed \
-loj \
-sorted | \
awk 'BEGIN{OFS="\t"} {if ($8==".") print 0,0; else print $8,$9}' | \
yame pack -f3 - > sample.cg
```
Check the result:
```{bash, eval=FALSE}
yame info sample.cg
yame summary sample.cg
```
## Convert ALLC files
ALLC files are tab-separated base-resolution cytosine count tables. In the
ALLCools convention, each row has 7 mandatory columns and no header:
```text
chromosome position strand sequence_context mc cov methylated
```
where `position` is 1-based, `mc` is the count of reads supporting methylation,
and `cov` is total read coverage. For MethScope, convert CG-context rows to
YAME format 3 by setting:
```text
M = mc
U = cov - mc
```
The command below keeps rows whose sequence context begins with `CG`, converts
the 1-based ALLC position to a 0-based BED interval, derives `U`, aligns the
result to the CpG reference, and packs the final two-column `M U` stream.
```{bash, eval=FALSE}
zcat sample.allc.tsv.gz | \
awk 'BEGIN{OFS="\t"}
$4 ~ /^CG/ {
chrom = $1
start = $2 - 1
end = $2
m = $5
u = $6 - $5
if (u < 0) u = 0
print chrom, start, end, m, u
}' | \
bedtools sort -i - > sample_mu.sorted.bed
bedtools intersect \
-a cpg_reference.bed.gz \
-b sample_mu.sorted.bed \
-loj \
-sorted | \
awk 'BEGIN{OFS="\t"} {if ($8==".") print 0,0; else print $8,$9}' | \
yame pack -f3 - > sample.cg
```
If your ALLC file is not compressed, replace `zcat sample.allc.tsv.gz` with
`cat sample.allc.tsv`.
## Convert beta or methylation fraction files
Use YAME format 4 (`-f4`) when the input already contains methylation fractions
or beta values. Missing CpGs should be encoded as `NA`.
Expected input:
```text
chr1 3000826 3000827 0.42
chr1 3001006 3001007 0.81
```
Convert to `.cg`:
```{bash, eval=FALSE}
bedtools sort -i sample_beta.bed > sample_beta.sorted.bed
bedtools intersect \
-a cpg_reference.bed.gz \
-b sample_beta.sorted.bed \
-loj \
-sorted | \
awk 'BEGIN{OFS="\t"} {if ($8==".") print "NA"; else print $8}' | \
yame pack -f4 - > sample_beta.cg
```
Format 4 stores methylation fractions but does not retain read depth.
## Convert binary BED tracks
Use YAME format 0 (`-fb`) when each CpG is represented as present or absent.
This is useful for binary tracks, peak overlaps, or binarized methylation states.
```{bash, eval=FALSE}
bedtools sort -i binary_track.bed > binary_track.sorted.bed
bedtools intersect \
-a cpg_reference.bed.gz \
-b binary_track.sorted.bed \
-sorted \
-c | \
cut -f4 | \
awk '{if ($1 > 0) print 1; else print 0}' | \
yame pack -fb - > binary_track.cg
```
## Use the converted file in MethScope
After creating `sample.cg`, use an MRMP reference `.cm` from the same genome
build.
```{r, eval=FALSE}
library(MethScope)
query_file <- "sample.cg"
reference_pattern <- "mm10_Liu2021.cm"
input_pattern <- GenerateInput(query_file, reference_pattern)
model <- Liu2021_MouseBrain_P1000()
prediction_result <- PredictCellType(model, input_pattern)
```
For a full MethScope test, clone the GitHub repository and run the tutorial with
`inst/extdata/example.cg` and `inst/extdata/mm10_Liu2021.cm`.
## Troubleshooting
If `GenerateInput()` fails or returns unexpected values, check these items first:
- The query `.cg` and reference `.cm` use the same genome build.
- The query `.cg` was packed against the same CpG coordinate order used by the
`.cm` reference.
- `yame info sample.cg` reports the expected number of CpGs.
- `yame summary sample.cg` shows nonzero coverage for real sequencing data.
- For format 3 input, no-coverage CpGs should be `0 0`.
- For format 4 input, missing values should be `NA`.
## Related resources
- YAME documentation:
- YAME documentation:
- KYCGKB hg38 reference files:
- KYCGKB mm10 reference files:
- ALLCools input-file documentation:
- MethScope tutorial: