# Methylation Haplotype Analysis
# Version 1.2
# Updated: 2017-05-31
# Contact: Dinh Diep (hdinhdp@gmail.com)

README
This software was developed for methylation haplotype analysis. 

Requirements:
(1) Unix based environment with capability of running perl and shell scripts
(2) samtools version 1.2 or above must be installed
(3) bedtools v2.26.0 or above must be installed 

No installation of this package is required. 

The following are modules included in this package for methylation haplotype analysis:

(1) analyzeMethylation - quantify methylation levels from haplotype files with one of AMF, IMF, or MHL. A matrix file will be generated for each individual haploinfo file in the given list.
USAGE:   analyzeMethylation.sh [list of haplotype files] [region file] <MHL|AMF|IMF> 

(2) MethylationHaplotypeGenerator_V1 - generate methylation haplotype files using version 1 code. Note that this version only works for data that have been aligned to hg19. This software must used with BAM files generated from BisReadMapper pipeline. Please make sure your BAM files contains flags for Crick reads in the reverse complementary orientation and that PE reads are matched by identical read IDs. Quality scores must be in phred 33 base. Please make sure to modify the MethylationHaplotypeGenerator_V1.sh script in order to provide the correct paths to the files required for running this software. Once the variables have been set, MethylationHaplotypeGenerator_V1.sh script can be run using command line in the Unix terminal. 

USAGE:   MethylationHaplotypeGenerator_V1.sh <RRBS|WGBS> [BAM file] [Output name] 

(3) MethylationHaplotypeGenerator_V2 - generate methylation haplotype files using version 2 code. This software was developed for methylation linkage disequilibrium analysis and methylation haplotypes analysis using aligned bisulfite sequencing reads. This software is best used with BAM files generated from BisReadMapper pipeline. Please make sure your BAM files contains flags for Crick reads in the reverse complementary orientation and that PE reads are matched by identical read IDs. Quality scores must be in phred 33 base. Make sure to modify the MethylationHaplotypeGenerator_V2.sh script in order to provide the correct paths to the files required for running this software. Once the variables have been set, MethylationHaplotypeGenerator_V2.sh script can be run using command line in the Unix terminal.

USAGE:   MethylationHaplotypeGenerator_V2.sh [BAM file] [Output name] 

(4) make_mappable_bins - generate mappable regions file from BAM

USAGE:   ./scripts/make_mappable_bins.sh [merged bam file] [minimum mapping depth]

(5) getMHBs - generate methylation haplotype blocks using version 1 code. Make mappable bins first using the make_mappable_bins.sh shell script. BAMfile for chr22 is provided to produce the mappable bins. Next, methylation haplotype block calling must be done with MethylationHaplotypeGenerator scripts V1 or V2. V2 script can call a significantly greater number of haplotypes. In Guo et. al. 2017, we set a highly stringent phred score cut off using V1 which resulted in fewer methylation haplotypes. See information for methylation haplotype generator softwares. Version 1 of MethylationHaplotypeGenerator will require the mappable bin file above to be used as the target file. Methylation haplotype block identification can be performed with V1 or V2 Methylation Haplotypes file. Haploinfo file for chr22 from the 61 WGBS in Guo et. al. 2017 is provided to reproduce the MHBs for chr22.

USAGE:   getMHBs.sh [haplotype file] [mappable bin file] [minimum linkage disequilibrium R2 cutoff]


Below are the instructions for processing the example files.

==== analyzeMethylation.sh ====

Here are example commands that can be run in the current directory of this README.txt.

# Make MHL (methylation haplotype load) matrix:
./scripts/analyzeMethylation.sh my_haplotypes my_mhbs MHL

# Make AMF (average methylation frequency) matrix:
./scripts/analyzeMethylation.sh my_haplotypes my_mhbs AMF

# Make IMF (individual methylation frequency) matrix:
./scripts/analyzeMethylation.sh my_haplotypes my_mhbs IMF

# Make PDR (percent discordant reads) matrix:
./scripts/analyzeMethylation.sh my_haplotypes my_mhbs PDR

# Make LD (linkage disequilibrium) matrix:
./scripts/analyzeMethylation.sh my_haplotypes my_mhbs LD

==== MethylationHaplotypeGenerator_V1 ====

Here are example commands that can be run in the current directory of this README.txt.

# For RRBS data: 
./scripts/MethylationHaplotypeGenerator_V1.sh RRBS Expected_results/small_targets.txt allcpg/cpg.small.txt BAMfiles/Colon_primary_tumor_sept9_promoter.bam Colon_promoter

# For WGBS data:
./scripts/MethylationHaplotypeGenerator_V1.sh WGBS Expected_results/small_targets.txt allcpg/cpg.small.txt BAMfiles/Colon_primary_tumor_sept9_promoter.bam Colon_promoter

==== MethylationHaplotypeGenerator_V2 ====

Here are example commands that can be run in the current directory of this README.txt.

# For generation of CpG position file using "chr10.fa.gz" file (reference genome file can be downloaded from UCSC genome browser (http://hgdownload.cse.ucsc.edu/goldenPath/hg19/chromosomes/)):# Generate CpG position file for individual chromosomes and then concatenate the CpG position files for faster processing of RRBS datasets. WGBS datasets are recommended to be processed by each chromosomes individually.

./scripts/genomePrep.pl chr10.fa.gz

# For generating methylation haplotypes:

./scripts/MethylationHaplotypeGenerator_V2.sh allcpg/cpg.small.txt BAMfiles/Colon_primary_tumor_sept9_promoter.bam Colon_promoter

==== getMHBs ====

# Here are example commands that can be run in the current directory of this README.txt.

./scripts/make_mappable_bins.sh BAMfiles/Colon_primary_tumor_sept9_promoter.bam 1

# After the haplotype files have been generated, run the block identifier: 

./scripts/getMHBs.sh HaploInfo/WGBS_pooled_mappable_bins.chr22.hapInfo.txt genomecov.bed 0.5 chr22.mhbs



