README.md

In dozmorovlab/HiCcompare: HiCcompare: Joint normalization and comparative analysis of multiple Hi-C datasets

HiCcompare

Stansfield, John C., Kellen G. Cresswell, Vladimir I. Vladimirov, and Mikhail G. Dozmorov. HiCcompare: An R-Package for Joint Normalization and Comparison of HI-C Datasets.” BMC Bioinformatics 19, no. 1 (December 2018).

Overview

HiCcompare provides functions for joint normalization and difference detection in multiple Hi-C datasets. HiCcompare operates on processed Hi-C data in the form of chromosome-specific chromatin interaction matrices. HiCcompare is available as an R package, the major releases can be found on Bioconductor here.

If you have more than two Hi-C datasets which you need to normalize or compare please see our other package, multiHiCcompare, which is available on Bioconductor here.

HiCcompare accepts three-column tab-separated text files storing chromatin interaction matrices in a sparse matrix format which are available from several sources such as the http://aidenlab.org/data.html and http://cooler.readthedocs.io/en/latest/index.html. HiCcompare is designed to give the user the ability to perform a comparative analysis on the 3-Dimensional structure of the genomes of cells in different biological states. HiCcompare first can jointly normalize two Hi-C datasets to remove biases between them. Then it can detect signficant differences between the datsets using a genomic distance based permutation test. The novel concept of the MD plot, based on the commonly used MA plot or Bland-Altman plot is the basis for these methods. The log Minus is plotted on the y axis while the genomic Distance is plotted on the x axis. The MD plot allows for visualization of the differences between the Hi-C datasets.

The main functions are: + hic_loess() which performs joint loess normalization on the Hi-C datasets + hic_compare() which performs the difference detection process to detect significant changes between Hi-C datasets and assist in comparative analysis

Several Hi-C datasets are also included in the package.

Read the full paper describing the methods behind HiCcompare here

Installation

First make sure you have all dependencies installed in R.

install.packages(c('dplyr', 'data.table', 'ggplot2', 'gridExtra', 
                   'mgcv', 'parallel', 'devtools'))

if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install(c("InteractionSet", "GenomicRanges", "IRanges", 
           "BiocParallel", "QDNAseq", "GenomeInfoDbData"))             

To install HiCcompare from bioconductor open R and enter the following commands. Currently it is recommended to use the GitHub release or the development version of the bioconductor release.

# Bioconductor development version and Github Release contain major changes for difference detection
# it is recommended to use the github release until the next Bioconductor update
## try http:// if https:// URLs are not supported
if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("HiCcompare")
library(HiCcompare)

Or to install the latest version of HiCcompare directly from the github release open R and enter the following commands.

library(devtools)
install_github('dozmorovlab/HiCcompare', build_vignettes = TRUE)
library(HiCcompare)

Usage

First you will need to obtain some Hi-C data. Data is available from the sources listed in the overview along with many others. You will need to extract the data and read it into R as either a 3 column sparse upper triangular matrix or a 7 column BEDPE file. For more details on data extraction see the vignette included with HiCcompare.

Below is an example analysis using HiCcompare. The data in 3 column sparse upper triangular matrix format is loaded and the first step is to create a hic.table object using the create.hic.table() function. Next, the two Hi-C matrices are jointly normalized using the hic_loess() function. Finally, difference detection can be performed using the hic_compare() function. The hic_loess() and hic_compare() functions will also produce an MD plot for visualizing the differences between the datasets.

# load data
library(HiCcompare)
data("HMEC.chr22")
data("NHEK.chr22")

# create the `hic.table` object
chr22.table = create.hic.table(HMEC.chr22, NHEK.chr22, chr = 'chr22')
head(chr22.table)

# Jointly normalize data for a single chromosome
hic.table = hic_loess(chr22.table, Plot = TRUE)
head(hic.table)

# input hic.table object into hic_compare
hic.table = hic_compare(hic.table, Plot = TRUE)
head(hic.table)

Refer to the HiCcompare vignette for full usage instructions. For a full explanation of the methods used in HiCcompare see the manuscript here.

To view the usage vignette:

browseVignettes("HiCcompare")

Tutorial for Differential Analysis of Hi-C Data

For more detailed instructions and examples on how to perform differential analyses on Hi-C data please see our tutorial paper "R Tutorial: Detection of Differentially Interacting Chromatin Regions From Multiple Hi‐C Dataset" published in Current Protocols in Bioinformatics. https://doi.org/10.1002/cpbi.76

Branches

• Master: contains the current stable release of HiCcompare
• supplemental: contains supplementary files and data, see Additional Vignettes section below
• manuscript_bioinformatics: contains write up for submission to Bioinformatics
• test_version: contains versions of HiCcommpare currently in development. This version of the software may be unstable and is not reccomended for users.

Additional Vignettes

The HiCcompare paper included several supplemental files that showcase some of the usage and reasoning behind the methods. Below are the titles and brief descriptions of each of these vignettes along with links to the compiled .pdf and the source .Rmd files.

Normalization method comparison.

Comparison of several Hi-C normalization techniques to display the persistence of bias in individually normalized chromatin interaction matrices, and its effect on the detection of differential chromatin interactions.

Compiled

Source

S2 File. Estimation of the IF power-law depencence.

Estimation of the power-law depencence between the $log_{10}-log_{10}$ interaction frequencies and distance between interacting regions. This vignette displays the reasoning behind using a power-law function for the simulation of the signal portion of Hi-C matrices.

Compiled

Source

S3 File. Estimation of the SD power-law dependence.

Estimation of the power-law depencence between the $log_{10}-log_{10}$ SD of interaction frequencies and distance between interacting regions. This vignette displays the reasoning behind using a power-law function for the simulation of the noise component of Hi-C matrices.

Compiled

Source

S4 File. Estimation of proportion of zeros.

Estimation of the depencence between the proportion of zeros and distance between interacting regions. This vignette shows distribution of zeros in real Hi-C data. The results were used for modeling the proportion of zeros in simulated Hi-C matrices with a linear function.

Compiled

Source

S5 File. Evaluation of difference detection in simulated data.

Extended evaluation of differential chromatin interaction detection analysis using simulated Hi-C data. Many different classifier performance measures are presented. Note: if trying to compile the source .Rmd this will take a long time to knit.

Compiled

Source

S6 File. Evaluation of difference detection in real data.

Extended evaluation of differential chromatin interaction detection analysis using real Hi-C data. Many different classifier performance measures are presented. Note: if trying to compile the source .Rmd this will take a long time to knit.

Compiled

Source

S7 File. loess at varying resolution.

Visualization of the loess loint normalization over varying resolutions. This vignette shows that increasing sparsity of Hi-C matrices with increasing resolution causes loess to become less useful for normalization at high resolutions.

Compiled

Source

Citation

Please cite HiCcompare if you use it in your analysis.

John C. Stansfield, Kellen G. Cresswell, Vladimir I. Vladimirov, Mikhail G. Dozmorov, HiCcompare: an R-package for joint normalization and comparison of HI-C datasets. BMC Bioinformatics. 2018 Jul 31;19(1):279. doi: 10.1186/s12859-018-2288-x.

Contributions & Support

Suggestions for new features and bug reports are welcome. Please create a new issue for any of these or contact the author directly: @jstansfield0 ([e-mail])

Contributors

Authors: @jstansfield0 ([e-mail]) & @mdozmorov ([e-mail])

dozmorovlab/HiCcompare documentation built on June 30, 2023, 3:09 a.m.