1 Introduction

The bnbc package provides functionality to perform normalization and batch correction across samples on data obtained from Hi-C (Lieberman-Aiden et al. 2009) experiments.

In this package we implement tools for general subsetting of and data extraction from sets of Hi-C contact matrices, as well as smoothing of contact matrices, cross-sample normalization and cross-sample batch effect correction methods.

bnbc expects as input

1. a GRanges object representing the genome assayed, with individual ranges having the width that is equal to the bin size used to partition the genome.
2. a list of (square) contact matrices.
3. a DataFrame object containing sample-level covariates (i.e. gender, date of processing, etc).

library(bnbc)

2 The ContactGroup class from bnbc

bnbc uses the ContactGroup class to represent the set of contact matrices for a given set of genomic locis interactions. The class has 3 slots:

• rowData: a GRanges object that has 1 element for each bin of the partitioned genome.
• colData: a DataFrame object that contains information on each sample (i.e. gender).
• contacts: a list of contact matrices.

We expect each ContactGroup to represent data from 1 chromosome. We are thinking about a whole-genome container. An example dataset for chromosome 22 is supplied with the package.

data(cgEx)
cgEx

## Object of class `ContactGroup` representing contact matrices with
##  1283 bins
##  40 kb average width per bin
##  14 samples

Creating a ContactGroup object requires specifying the 3 slots above:

cgEx <- ContactGroup(rowData=rowData(cgEx),
                     contacts=contacts(cgEx),
                     colData=colData(cgEx))

Note that in this example, we used the accessor methods for each of these slots; there are also corresponding ‘setter’ methods, such as rowData(cgEx)<-.

Printing a ContactGroup object gives the number of bins represented by the rowData slot, the width of the bin in terms of genomic distances (i.e. 100kb) and the number of samples:

cgEx

## Object of class `ContactGroup` representing contact matrices with
##  1283 bins
##  40 kb average width per bin
##  14 samples

3 Getting your data into bnbc

To get data into bnbc you need a list of contact matrices, one per sample. We assume the contact matrices are square, with no missing values. We do not require that data have been transformed or pre-processed by various bias correction software and provide methods for some simple pre-processing techniques.

There is currently no standard Hi-C data format. Instead, different groups produces custom formats, often in forms of text files. Because contact matrices are square, it is common to only distribute the upper or lower triangular matrix. In that case, you can use the following trick to make the matrix square:

mat <- matrix(1:9, nrow = 3, ncol = 3)
mat[lower.tri(mat)] <- 0
mat

##      [,1] [,2] [,3]
## [1,]    1    4    7
## [2,]    0    5    8
## [3,]    0    0    9

## Now we fill in the lower triangular matrix with the upper triangular
mat[lower.tri(mat)] <- mat[upper.tri(mat)]
mat

##      [,1] [,2] [,3]
## [1,]    1    4    7
## [2,]    4    5    8
## [3,]    7    8    9

Below, we demonstrate the steps needed to convert a set of hypothetical contact matrices into a ContactGroup object. The object upper.mats.list is supposed to be a list of contact matrices, each represented as an upper triangular matrix. We also suppose LociData to be a GenomicRanges object containing the loci of the contact matrices, and SampleData to be a DataFrame of per-sample information (i.e. cell type, sample name etc). We first convert all contact matrices to be symmetric matrices, then use the constructor method ContactGroup() to create the object.

## Example not run
## Convert upper triangles to symmetry matrix
MatsList <- lapply(upper.mats.list, function(M) {
    M[lower.tri(M)] <- M[upper.tri(M)]
})
## Use ContactGroup constructor method
cg <- ContactGroup(rowData = LociData, contacts = MatsList, colData = SampleData)

For this to work, the contacts list has to have the same names as the rownames of colData.

4 Working with bnbc contact matrices

We provide setter and getter methods for manipulating individual matrix bands for contact matrices as well. First, we have functions for working with bands of individual matrices (not bnbc related):

mat.1 <- contacts(cgEx)[[1]]
mat.1[1000:1005, 1000:1005]

##      [,1] [,2] [,3] [,4] [,5] [,6]
## [1,]    5   30   36   32   53   20
## [2,]   30    7   36   38   50   16
## [3,]   36   36    3   44   51   15
## [4,]   32   38   44    4   89   39
## [5,]   53   50   51   89   36   55
## [6,]   20   16   15   39   55    5

b1 <- band(mat=mat.1, band.no=2)
band(mat=mat.1, band.no=2) <- b1 + 1
mat.1[1000:1005, 1000:1005]

##      [,1] [,2] [,3] [,4] [,5] [,6]
## [1,]    5   31   36   32   53   20
## [2,]   31    7   37   38   50   16
## [3,]   36   37    3   45   51   15
## [4,]   32   38   45    4   90   39
## [5,]   53   50   51   90   36   56
## [6,]   20   16   15   39   56    5

In this example, the main diagonal of the contact matrix is also the main diagonal of the printed example above. Similarly, band number two, which is also the first off-diagonal, is also the first off-diagonal of the printed example. As can be seen from the printed example, updating a matrix band is a symmetric operation, and updated the first off-diagonal in both the upper and lower triangles of the matrix.

To utilize this across a list of contact matrices, we have the cgApply() function which applies the same function to each of the matrices. It supports parallelization using parallel.

5 Per-Sample Adjustments

To adjust for differences in depth sequencing, we first apply the logCPM transform (Law et al. 2014) to each contact matrix. This transformation divides each contact matrix by the sum of the upper triangle of that matrix (adding 0.5 to each matrix cell and 1 to sum of the upper triangle), scales the resulting matrix by \(10^6\) and finally takes the log of the scaled matrix (a fudge factor is added to both numerator and denominator prior to taking the logarithm)..

cgEx.cpm <- logCPM(cgEx)

Additionally, we smooth each contact matrix with a square smoothing kernel to reduce artifacts of the choice of bin width. We support both box and Gaussian smoothers.

cgEx.smooth <- boxSmoother(cgEx.cpm, h=5)
## or
## cgEx.smooth <- gaussSmoother(cgEx.cpm, radius=3, sigma=4)

6 Cross Sample Normalization

BNBC operates on each matrix band separately. For each matrix band \(k\), we extract each sample’s observation on that band and form a matrix \(M\) from those bands; if band \(k\) has \(d\) entries, then after logCPM transformation, \(M \in \mathbb{R}^{n \times d}\). For each such matrix, we first apply quantile normalization (Bolstad et al. 2003) to correct for distributional differences, and then ComBat (Johnson, Li, and Rabinovic 2007) to correct for batch effects.

Here we will use bnbc to do batch correction on the first 10 matrix bands, beginning with the second matrix band and ending on the eleventh.

cgEx.bnbc <- bnbc(cgEx.smooth, batch=colData(cgEx.smooth)$Batch,
                  threshold=1e7, step=4e4, nbands=11, verbose=FALSE)

## Standardizing Data across genes
## Standardizing Data across genes
## Standardizing Data across genes
## Standardizing Data across genes
## Standardizing Data across genes
## Standardizing Data across genes
## Standardizing Data across genes
## Standardizing Data across genes
## Standardizing Data across genes
## Standardizing Data across genes

7 sessionInfo()

## R version 3.6.0 (2019-04-26)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 18.04.2 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.9-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.9-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] stats4    parallel  stats     graphics  grDevices utils     datasets 
## [8] methods   base     
## 
## other attached packages:
##  [1] bnbc_1.6.0                  SummarizedExperiment_1.14.0
##  [3] DelayedArray_0.10.0         BiocParallel_1.18.0        
##  [5] matrixStats_0.54.0          Biobase_2.44.0             
##  [7] GenomicRanges_1.36.0        GenomeInfoDb_1.20.0        
##  [9] IRanges_2.18.0              S4Vectors_0.22.0           
## [11] BiocGenerics_0.30.0         BiocStyle_2.12.0           
## 
## loaded via a namespace (and not attached):
##  [1] genefilter_1.66.0      locfit_1.5-9.1         xfun_0.6              
##  [4] splines_3.6.0          lattice_0.20-38        htmltools_0.3.6       
##  [7] yaml_2.2.0             mgcv_1.8-28            blob_1.1.1            
## [10] XML_3.98-1.19          survival_2.44-1.1      DBI_1.0.0             
## [13] EBImage_4.26.0         bit64_0.9-7            jpeg_0.1-8            
## [16] GenomeInfoDbData_1.2.1 sva_3.32.0             stringr_1.4.0         
## [19] zlibbioc_1.30.0        htmlwidgets_1.3        evaluate_0.13         
## [22] memoise_1.1.0          knitr_1.22             AnnotationDbi_1.46.0  
## [25] preprocessCore_1.46.0  Rcpp_1.0.1             xtable_1.8-4          
## [28] BiocManager_1.30.4     limma_3.40.0           annotate_1.62.0       
## [31] XVector_0.24.0         abind_1.4-5            bit_1.1-14            
## [34] png_0.1-7              digest_0.6.18          stringi_1.4.3         
## [37] tiff_0.1-5             bookdown_0.9           grid_3.6.0            
## [40] tools_3.6.0            bitops_1.0-6           magrittr_1.5          
## [43] RCurl_1.95-4.12        RSQLite_2.1.1          Matrix_1.2-17         
## [46] rmarkdown_1.12         fftwtools_0.9-8        nlme_3.1-139          
## [49] compiler_3.6.0