---
title: "mHapTK: A comprehensive tool kit for analysis of DNA methylation haplotypes"
output:
  html_document:
    toc: true
---
***

mHapTk is a tool kit for analysis of DNA methylation haplotypes. It has 5 sub-commands: tanghulu, stat, genomeWide, R2 and MHBDiscovery. 

```
mHapTk 0.10 (A tool kit for analysis of DNA methylation haplotypes.)
Usage: mHapTk <command> [options]

Commands:
  genomeWide      calculate methylation metrics for mHaps that cover each CpG site across the genome
  stat            calculate methylation metrics for mHaps that cover predefined regions
  tanghulu        plot the DNA methylation status for mHaps in a region
  R2              calculate linkage disequilibrium between CpG sites within predefined regions
  MHBDiscovery    identification of methylation haplotype blocks within a region or genome-wide
```

## input
Previously, we have developped a general format for DNA methylation haplotypes (mHaps). The mHap file can be obtained by converting the bam file with [mhapTools](https://jiantaoshi.github.io/mHap/index.html). Besides, it also requires [CpG annotation files](https://jiantaoshi.github.io/mHap/AnnotationFiles.html). A typical command below will generate a sorted mhap file, which needs to be indexed.

```
mhaptools convert -i in.bam -c CpG.gz -o out.mhap.gz
tabix -b 2 -e 3 out.mhap.gz
```

## tanghulu

This function is to visualize the methylation status of the reads that cover a given region. Tanghulu plot was original introduced in [CGmapTools](https://cgmaptools.github.io/).

```
Usage: mHapTk tanghulu --mhapPath <in.mhap.gz> --cpgPath <CpG.gz> --outputFile <out> [--region chr:start-end] [--merge] [--simulation] [--outcut outcut]
Options:
  --mhapPath    str   input file, mhap.gz format, generated by mHapTools and indexed
  --cpgPath     str   genomic CpG file, gz format and indexed
  --region      str   one region, in the format of chr:start-end
  --outputFile   str   output file
  --merge       indicates whether identical mHaps should be merged
  --simulation	indicates whether mHaps should be simulated
  --outcut      int   the max length of region to plot, default is 2000
```

Example of usage:

```
mHapTk tanghulu --mhapPath SRX8208802.mhap.gz --cpgPath hg19_CpG.gz --region chr1:14435-14653 --outputFile SRX8208802_chr1_14435_14653.tanghulu.pdf
```
This command will output a PDF file `SRX8208802_chr1_14435_14653.tanghulu.pdf` .

==【图1】==


When setting the `--merge` option, identical mHaps will be merged. This can be helpful when there are too many reads in a region.

```
mHapTk tanghulu --mhapPath SRX8208802.mhap.gz --cpgPath hg19_CpG.gz --region chr1:14435-14653 --outputFile SRX8208802_chr1_14435_14653.tanghulu.pdf --merge
```

==【图2】==

When setting the `--simulation`, the methylation status of the CpG sites in the region can be simulated.

```
mHapTk tanghulu --mhapPath SRX8208802.mhap.gz --cpgPath hg19_CpG.gz --region chr1:14435-14653 --outputFile SRX8208802_chr1_14435_14653.simulation.pdf --simulation
```

==【图3】==


## stat

This function is to calculate the methylation statistics in a single region or multiple regions. When calculating a single interval, the region parameter should be given. If there are multiple intervals, the bed file needs to be given.

```
Usage: mHapTk stat --mhapPath <in.mhap.gz> --cpgPath <CpG.gz> --outputFile <out> [--metrics MM PDR CHALM MHL MCR MBS Entropy] [--region chr:start-end | --bedPath bed_file.bed ] [--minK minK] [--maxK maxK] [--K K] [--strand --strand]
Options:
  --metrics   str     mHap-level metrics, including MM, PDR, CHALM, MHL, MCR, MBS, Entropy, and R2 [None]
  --mhapPath  str     input file, mhap.gz format, generated by mHapTools and indexed
  --cpgPath   str     genomic CpG file, gz format and indexed
  --region    str     one region, in the format of chr:start-end
  --bedPath   str     input BED file
  --outputFile str    output file name
  --minK      integer minimum k-mer length for MHL [1]
  --maxK      integer maximum k-mer length for MHL [10]
  --K         integer k-mer length for entropy, PDR, and CHALM, can be 3, 4, or 5 [4]
  --strand    str     strand information, one of plus, minus and both [both]
```

The output is a TSV file with 10 or more columns, including `chr`, `start`, `end`,`nReads`, `mBase`,`cBase`, `tBase`, `K4plus`, `nDR` and `nMR`, as described below.

 >| column |                         Description                          |
 >| -----: | :----------------------------------------------------------: |
 >| nReads |                  the number of mapped reads                  |
 >|  mBase |           the methylated CpGs within mapped reads            |
 >|  cBase | the number of unmethylated CpGs in reads with discordant methylation |
 >|  tBase |           total number of CpGs within mapped reads           |
 >| K4plus |       the number of mapped reads with at least 4 CpGs        |
 >|    nDR | the number of reads with discordant methylation status among all reads defined by K4plus |
 >|    nMR |                the number of methylated reads                |

```r
<chr>   <start> <end> <nReads> <mBase> <cBase> <tBase> <K4plus> <nDR> 	<nMR>
chr1	566519	566816	5395	3900	940		35410	5204	230		658
chr1	912357	912395	41		105		101		590		41		14		14
chr1	913614	913814	331		1155	418		3182	323		111		159
chr1	915387	915494	370		852		137		2089	350		66		162
chr1	942361	942451	305		1214	306		3115	305		94		146
chr1	942459	942498	240		1008	269		2531	227		80		114
chr1	942658	942734	312		1029	278		2452	290		97		153
chr1	960268	960349	186		450		236		1352	186		56		94
chr1	968439	968491	154		615		543		2734	154		56		65
chr1	968558	968583	141		539		299		2509	141		42		49
```

Moreover, when DNA methylation metrics were specified through `--metrics` option, additional columns will shown.
Here are some examples. Get the mean methylation level within a region:

```
mHapTk stat --metrics MM --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --region chr1:566520-566816 --outputFile outStat.tsv
```

Get the mean methylation level with regions in a BED file:

```
mHapTk stat --metrics MM --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --bedPath esophagus_T_MHB.bed --outputFile outStat.tsv
```

Get the value of all statistics within a region:

```
mHapTk stat --metrics MM PDR CHALM MHL MCR MBS Entropy R2 --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --region chr1:566520-566816 --outputFile outStat.tsv
```

Get the value of all statistics with regions in a BED file:

```
mHapTk stat --metrics MM PDR CHALM MHL MCR MBS Entropy R2 --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz  --bedPath esophagus_T_MHB.bed --outputFile outStat.tsv
```

## genomeWide

The mHapTK can also calcuate mHap-level summary statistics for all reads that cover each individual CpG sites in a genome-wide manner and save the results as a [bedGraph](https://genome.ucsc.edu/goldenpath/help/bedgraph.html) file.

```
Usage: mHapTk genomeWide --tag <tag> --metrics <MM PDR CHALM MHL MCR MBS Entropy R2>
--mhapPath <in.mhap.gz> --cpgPath <CpG.gz> --outputDir <out> [--minK minK] [--maxK maxK] [--K K] [--strand strand]
Options:
  --tag     str   prefix of the output file(s)
  --metrics     str     mHap-level metrics, including MM, PDR, CHALM, MHL, MCR, MBS, Entropy, and R2
  --mhapPath    str     input file, mhap.gz format, generated by mHapTools and indexed
  --cpgPath     str     genomic CpG file, gz format and indexed
  --outputDir   str     output directory, created in advance
  --minK        integer minimum k-mer length for MHL [1]
  --maxK        integer maximum k-mer length for MHL [10]
  --K           integer k-mer length for entropy, PDR, and CHALM, can be 3, 4, or 5 [4]
  --strand      str     strand information, one of plus, minus and both [both]
```

Depending on the mHap-level metrics specified through `--metrics` option, mHapTK outputs one or more bedGraph files, named as `tag_metric.bedGraph`.

Here are some examples. Calculate the mean methylation level under genome-wide:

```
mHapTk genomeWide --tag esophagus_T --metrics MM --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --outputDir outGW
```

Calculate the value of all statistics under genome-wide:

```
mHapTk genomeWide --tag esophagus_T --metrics MM PDR CHALM MHL MCR MBS Entropy R2 --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --outputDir outGW
```

Calculate the MHL value under genome-wide, and set the maximum and minimum length of K-mer:

```
mHapTk genomeWide --tag esophagus_T --metrics MHL --minK 1 --maxK 10 --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --outputDir outGW
```

Calculate the PDR CHALM and Entropy value under genome-wide, and set the length of K-mer:

```
mHapTk genomeWide --tag esophagus_T --metrics PDR CHALM and Entropy --K 4 --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --outputDir outGW
```

In addition, the output file is a bedGraph format, which can be converted into a bigwig file and then combine with IGV , pyGenomeTrack or washU browser for visualization.

```
# Convert bedGraph file to bigwig
bedGraphToBigWig esophagus_T_MM_GW.bedGraph chrom_sizes esophagus_T_MM_GW.bw

# Visualize with pyGenomeTrack
make_tracks_file --trackFiles esophagus_T_MM_GW.bw -o tracks.ini
pyGenomeTracks --tracks tracks.ini --region chr8:76130000-76240000 -o track.pdf
```

Meanwhile, it can also be combined with deepTools software to creates a heatmap for scores associated with genomic regions.

```
# Convert bedGraph file to bigwig
bedGraphToBigWig esophagus_T_MM_GW.bedGraph chrom_sizes esophagus_T_MM_GW.bw

# Prepares an intermediate matrix that can be used with plotHeatmap
computeMatrix reference-point -S esophagus_T_MM_GW.bw -R esophagus_T_MHB.bed -a 1000 -b 1000 -out matrix.tab.gz

# Creates a heatmap for scores
plotHeatmap --plotFileFormat pdf -m matrix.tab.gz -out heatmap.pdf 
```

## R2

In addition, this tool can calculate the linkage relationship between all CpG sites in a given region, and also can draw a heatmap and reads distribution map of it. 

```
Usage: mHapTk R2 --tag <tag> --mhapPath <in.mhap.gz> --cpgPath <CpG.gz> --region chr:start-end --outputDir <out> [--cpgHp] [--strand strand]
Options:
  --tag         str   prefix of the output files
  --mhapPath    str   input file, mhap.gz format, generated by mHapTools and indexed
  --cpgPath     str   genomic CpG file, gz format and Indexed
  --region      str   one region, in the format of chr:start-end
  --outputDir   str   output directory, created in advance
  --cpgHp       plot linkage disequilibrium patterns of pair-wise CpGs
  --strand      str   strand information, one of plus, minus and both [both]
  --longrange	indicates whether generate a file in longrange format
```

This function summerizes rsquare and pvalue in pre-defined regions. The output file is a genomic position-based format with 9 columns, including `N00`,  `N01`, `N10`, `N11`, `Chr`, `posi`, `posj `, `r2` and `pvalue`. 

 >| column |                        Description                         |
 >| :----: | :--------------------------------------------------------: |
 >|  N00   |  the number of reads that are unmethylated at both CpG sites  |
 >|  N01   | the number of reads methylated at the second CpG site only |
 >|  N10   | the number of reads methylated at the first CpG site only  |
 >|  N11   | the number of reads that are methylated at both CpG sites  |
 >|  Chr   |     the chromosomes where the two CpG sites locate |
 >|  posi  |      the location of the first CpG site on the genome |
 >|  posj  |     the location of the second CpG site on the genome |
 >|   r2   |              r-square               |
 >| pvalue |                p-value              |

```
<N00>	<N01>	<N10>	<N11>	<Chr>	<posi>	<posj>	<r2>		<pvalue>
105		0		0		11		chr1	2121159	2121174	1.0			0.9999999991901031
53		0		0		6		chr1	2121159	2121246	1.0			0.9999973045762146
45		1		0		4		chr1	2121159	2121256	0.7826087	0.999948551681479
43		0		0		4		chr1	2121159	2121258	1.0			0.9999762644707205
35		1		0		4		chr1	2121159	2121270	0.77777778	0.9998605394246142
23		0		0		4		chr1	2121159	2121282	1.0			0.9997254327364771
15		0		0		2		chr1	2121159	2121294	1.0			0.9984410126219724
```

Here are some examples. Get the rsquare between all CpG sites in a given region:

```
mHapTk R2 --tag esophagus_T --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --region chr1:2121159-2121449 --outputDir outR2
```

Generate a file in longrange format, which can be directly put into washU to see the track, by using the option `--longrange` :

```
mHapTk R2 --longrange --tag esophagus_T --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --region chr1:2121159-2121449 --outputDir outR2
```

The output file format is as follows：

```
chr1	2121159	2121160	chr1:2121174-2121175,1.0
chr1	2121159	2121160	chr1:2121246-2121247,1.0
chr1	2121159	2121160	chr1:2121256-2121257,0.7826087
chr1	2121159	2121160	chr1:2121258-2121259,1.0
chr1	2121159	2121160	chr1:2121270-2121271,0.77777778
chr1	2121159	2121160	chr1:2121282-2121283,1.0
chr1	2121159	2121160	chr1:2121294-2121295,1.0
```

Get the rsquare between all CpG sites in a given interval, and plot a heatmap of it by using the option `--cpgHp`:

```
mHapTk R2 --cpgHp --tag esophagus_T --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --region chr1:2121159-2121449 --outputDir outR2
```

The upper part of the figure shows the coverage and methylation status of reads. Grey part indicates that the site is not covered by the read,  the black part means the site is methylated, and white is not methylated; the figure below shows a heatmap of the rsquare between any two points:

==【图4】==

## MHBDiscovery

This function is to find the methylation haplotype blocks in a given region or all regions on the genome, which is defined by default as regions in which a minimum of 2 adjacent CpG sites exhibit a linkage disequilibrium measurement r2 greater than 0.5.

```
Usage: mHapTk MHBDiscovery --mhapPath <in.mhap.gz>  --cpgPath <CpG.gz> [--region chr:start-end | -bedPath bed_file.bed ] --outputFile <out>  [--window window] [--r_square r_square] [--p_value p_value]
Options:
  --mhapPath    str     input file, mhap.gz format, generated by mHapTools and indexed
  --cpgPath     str     genomic CpG file, gz format and Indexed
  --region      str     one region, in the format of chr:start-end
  --bedPath     str     input BED file
  --outputFile   str    output file
  --window      integer size of core window [5]
  --r_square    float   R-square cutoff [0.5]
  --p_value     float   P-value cutoff [0.05]
```

The output file is a BED format file with 3 columns, including `chr`,  `start`, `end`. Here are some examples. Get methylation haplotype blocks in a given region:
```
mHapTk MHBDiscovery --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --region chr1:10468-88851 --window 5 --r_square 0.5 --p_value 0.05 --outputFile out_MHB.bed
```

Get methylation haplotype blocks with regions in a BED file:
```
mHapTk MHBDiscovery --mhapPath esophagus_T.mhap.gz --cpgPath hg19_CpG.gz --bedPath hg19_1000CpG.bed --window 5 --r_square 0.5 --p_value 0.05 --outputFile out_MHB.bed
```
