# Functional Analysis of DNAm Sequencing Data

KnowYourCG (KYCG) is a supervised learning framework designed for the functional analysis of DNA methylation data. Unlike existing tools that focus on genes or genomic intervals, KnowYourCG directly targets CpG dinucleotides, featuring automated supervised screenings of diverse biological and technical influences, including sequence motifs, transcription factor binding, histone modifications, replication timing, cell-type-specific methylation, and trait associations. KnowYourCG addresses the challenges of data sparsity in various methylation datasets, including low-pass Nanopore sequencing, single-cell DNA methylomes, 5-hydroxymethylation profiles, spatial DNA methylation maps, and array-based datasets for epigenome-wide association studies and epigenetic clocks.

The input to KYCG is a CpG set (query). The CpG sets can represent differential methylation, results from an epigenome-wide association studies, or any sets that may be derived from analysis. If analyzing sequencing data, the preferred format is a YAME-compressed binary vector of 0 and 1 to indicate whether the CpG is in set. This format assume a specific order of CpGs following the genomic coordinates. Since it’s a coordinate-free approach, the reference coordinate is critical. Please refer to the YAME documentation for details. https://zhou-lab.github.io/YAME/.

# QUICK START

    # Code that should run only on non-Windows systems
    library(knowYourCG)

    # Download query and knowledgebase datasets:
    temp_dir <- tempdir()
    knowledgebase <- file.path(temp_dir, "ChromHMM.20220414.cm")
    query <- file.path(temp_dir, "single_cell_10_samples.cg")
    knowledgebase_url <- "https://github.com/zhou-lab/KYCGKB_mm10/raw/refs/heads/main/ChromHMM.20220414.cm"
    query_url <- "https://github.com/zhou-lab/YAME/raw/refs/heads/main/test/input/single_cell_10_samples.cg"
    download.file(knowledgebase_url, destfile = knowledgebase)
    download.file(query_url, destfile = query)

    # test enrichment (require YAME installed in shell)
    res = testEnrichment(query, knowledgebase)
    KYCG_plotDot(res, short_label=TRUE)

# KNOWLEDGEBASES

The curated target features are called the knowledgebase sets. We have curated a variety of knowledgebases that represent different categorical and continuous methylation features such as CpGs associated with chromatin states, technical artifacts, gene association and gene expression correlation, transcription factor binding sites, tissue specific methylation, CpG density, etc.

Whole-genome knowledgebases are available as listed in the following tables.

Assembly | Link
--- | ---
human (hg38) | https://github.com/zhou-lab/KYCGKB_hg38
mouse (mm10) | https://github.com/zhou-lab/KYCGKB_mm10

# INPUT FORMAT

For non-array data, CpG sets (query, knowledgebase, and universe) should be formated using YAME. YAME supports binary representation of a set (format “b”) and optionally with a universe (format “d”). Format “d” can be created from format “b” using the `yame mask` function.

If you have a BED-formated data, you can pack it to YAME-“b” format using the following pipeline. This pipeline requires BEDTools and a reference coordinate file (YAME-“r”) available below:

Assembly | Link
--- | ---
human (hg38) | https://github.com/zhou-lab/KYCGKB_hg38/raw/refs/heads/main/cpg_nocontig.cr
mouse (mm10) | https://github.com/zhou-lab/KYCGKB_mm10/raw/refs/heads/main/cpg_nocontig.cr

    yame unpack cpg_nocontig.cr | bedtools intersect -a - -b [your_input.bed] -c -sorted |
      cut -f4 | yame pack -fb - > [your_input.cg]

The above assumes your input is already sorted. Check out the bedtools instersect if you encounter any problems at this step.

# ENRICHMENT TESTING

Then we simply run `yame summary` with `-m` feature file for enrichment testing. We have provided comprehensive enrichment feature files, and you can download them from th KYCG github page mm10/hg38. You can also create your own feature file with `yame pack`.

    yame summary -m feature.cm yourfile.cg > yourfile.txt

Detailed information of the output columns can be found on the `yame summary` page. Basically, a higher log2oddsratio indicates a stronger association between the feature being tested and the query set. Generally, a large log2 odds ratio is typically considered to be around 2 or greater, with values between 1 and 2 often being viewed as potentially important and worthy of further investigation, while values around 0.5 might be considered a small effect size. For significance testing, seasame R package provided the testEnrichmentFisherN function, which is also provided in the yame github R page. The four input parameters correspond to the four columns from yame summary output.

    ND = N_mask
    NQ = N_query
    NDQ = N_overlap
    NU = N_universe

We can create a coarse differential methylation datasets the following way

    yame pairwise -H 1 -c 10 sample1.cg sample2.cg -o output.cg

-H controls directionality and -c controls minimum coverage.

The output is a query CG sets with proper universe background. Selecting the appropriate background for enrichment testing is crucial because it can significantly impact the interpretation of the results. Usually, we use the background set that is measured in the experiment under different conditions.

    yame mask -c query.cg universe.cg | yame summary -m feature.cm - > yourfile.txt

The following is an analysis example in R that explicitly call `yame` in R.

    df = tibble(read.table(text=system("yame summary -m ~/references/mm10/KYCGKB_mm10/stranded/kmer10.20231201.cm /mnt/isilon/zhou_lab/projects/20230727_all_public_WGBS/mm10_stranded/20231201_neuron_MeCP2.cg", intern=TRUE), head=T))

# SESSION INFO

    sessionInfo()

    ## R version 4.5.0 RC (2025-04-04 r88126 ucrt)
    ## Platform: x86_64-w64-mingw32/x64
    ## Running under: Windows Server 2022 x64 (build 20348)
    ##
    ## Matrix products: default
    ##   LAPACK version 3.12.1
    ##
    ## locale:
    ## [1] LC_COLLATE=C
    ## [2] LC_CTYPE=English_United States.utf8
    ## [3] LC_MONETARY=English_United States.utf8
    ## [4] LC_NUMERIC=C
    ## [5] LC_TIME=English_United States.utf8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats4    stats     graphics  grDevices utils     datasets  methods
    ## [8] base
    ##
    ## other attached packages:
    ##  [1] sesame_1.26.0               knitr_1.50
    ##  [3] gprofiler2_0.2.3            SummarizedExperiment_1.38.0
    ##  [5] Biobase_2.68.0              GenomicRanges_1.60.0
    ##  [7] GenomeInfoDb_1.44.0         IRanges_2.42.0
    ##  [9] S4Vectors_0.46.0            MatrixGenerics_1.20.0
    ## [11] matrixStats_1.5.0           sesameData_1.25.0
    ## [13] ExperimentHub_2.16.0        AnnotationHub_3.16.0
    ## [15] BiocFileCache_2.16.0        dbplyr_2.5.0
    ## [17] BiocGenerics_0.54.0         generics_0.1.3
    ## [19] knowYourCG_1.4.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] DBI_1.2.3               bitops_1.0-9            rlang_1.1.6
    ##  [4] magrittr_2.0.3          compiler_4.5.0          RSQLite_2.3.9
    ##  [7] png_0.1-8               vctrs_0.6.5             reshape2_1.4.4
    ## [10] stringr_1.5.1           pkgconfig_2.0.3         crayon_1.5.3
    ## [13] fastmap_1.2.0           XVector_0.48.0          fontawesome_0.5.3
    ## [16] rmarkdown_2.29          tzdb_0.5.0              UCSC.utils_1.4.0
    ## [19] preprocessCore_1.70.0   purrr_1.0.4             bit_4.6.0
    ## [22] xfun_0.52               cachem_1.1.0            jsonlite_2.0.0
    ## [25] blob_1.2.4              DelayedArray_0.34.0     BiocParallel_1.42.0
    ## [28] parallel_4.5.0          R6_2.6.1                bslib_0.9.0
    ## [31] stringi_1.8.7           RColorBrewer_1.1-3      jquerylib_0.1.4
    ## [34] Rcpp_1.0.14             wheatmap_0.2.0          readr_2.1.5
    ## [37] Matrix_1.7-3            tidyselect_1.2.1        abind_1.4-8
    ## [40] yaml_2.3.10             codetools_0.2-20        curl_6.2.2
    ## [43] lattice_0.22-7          tibble_3.2.1            plyr_1.8.9
    ## [46] withr_3.0.2             KEGGREST_1.48.0         evaluate_1.0.3
    ## [49] Biostrings_2.76.0       pillar_1.10.2           BiocManager_1.30.25
    ## [52] filelock_1.0.3          plotly_4.10.4           RCurl_1.98-1.17
    ## [55] BiocVersion_3.21.1      hms_1.1.3               ggplot2_3.5.2
    ## [58] munsell_0.5.1           scales_1.3.0            glue_1.8.0
    ## [61] lazyeval_0.2.2          tools_4.5.0             data.table_1.17.0
    ## [64] grid_4.5.0              tidyr_1.3.1             AnnotationDbi_1.70.0
    ## [67] colorspace_2.1-1        GenomeInfoDbData_1.2.14 cli_3.6.4
    ## [70] rappdirs_0.3.3          S4Arrays_1.8.0          viridisLite_0.4.2
    ## [73] dplyr_1.1.4             gtable_0.3.6            sass_0.4.10
    ## [76] digest_0.6.37           SparseArray_1.8.0       ggrepel_0.9.6
    ## [79] htmlwidgets_1.6.4       memoise_2.0.1           htmltools_0.5.8.1
    ## [82] lifecycle_1.0.4         httr_1.4.7              bit64_4.6.0-1