hicAggregateContacts is a tool that allows plotting of aggregated Hi-C sub-matrices of a specified list of positions. Positions of interest can for example be binding sites of a specific protein that were determined by ChIP-seq or genetic elements as transcription start sites of active genes.


Takes a list of positions in the hic-matrix and makes a pooled image.

usage: hicAggregateContacts --matrix MATRIX --outFileName OUTFILENAME --BED
                            BED --range RANGE [--BED2 BED2]
                            [--numberOfBins NUMBEROFBINS]
                            [--transform {total-counts,z-score,obs/exp,none}]
                            [--avgType {mean,median}] [--help] [--version]
                            [--outFilePrefixMatrix OUTFILEPREFIXMATRIX]
                            [--outFileContactPairs OUTFILECONTACTPAIRS]
                            [--diagnosticHeatmapFile DIAGNOSTICHEATMAPFILE]
                            [--kmeans KMEANS] [--hclust HCLUST]
                            [--howToCluster {full,center,diagonal}]
                            [--chromosomes CHROMOSOMES [CHROMOSOMES ...]]
                            [--colorMap COLORMAP] [--plotType {2d,3d}]
                            [--vMin VMIN] [--vMax VMAX] [--dpi DPI]

Required arguments

--matrix, -m

Path of the Hi-C matrix to plot.

--outFileName, -out

File name to save the image.


Interactions between regions in this BED file are plotted.


Range of contacts that will be considered for plotting the aggregate contacts in bp with the format low_range:high_range for example 1000000:20000000. The range should start at contacts larger than TAD size to reduce background interactions.

Optional arguments


Optional second BED file. Interactions between regions in first and second BED file are plotted.


Number of bins to include in the submatrix. The bed regions will be centered between - half number of bins and the other half number of bins.

Default: 51


Possible choices: total-counts, z-score, obs/exp, none

Type of transformation for the matrix. The options are “none”, “total-counts”, “z-score” or “obs/exp”. If total counts are selected, then the sub-matrix values are divided by the total counts for normalization. If z-score or obs/exp are selected, then H-C matrix is converted into a z-score or observed / expected matrix.

Default: “none”


Possible choices: mean, median

Type of average to compute final matrix. Options are mean and median. Default is median.

Default: “median”


show program’s version number and exit


Optional parameter: Resolution for the image in case theouput is a raster graphics image (e.g png, jpg)

Default: 300

Output options


If this option is given, then the values underlying the final matrix will be saved to tab-delimited tables (one per chromosome) using the indicated prefix, for example TSS_to_TSS_chrX.tab. If clustering is performed, then the values are saved including the cluster_id a in TSS_to_TSS_chrX_cluster_1.tab


The value should be a prefix. If this option is given, then the position of the contacts positions are saved as (chrom1, start1, end1, chrom2, start2, end2) where chrom_n, start_n, end_n correspond to the pair of positions used to compute the submatrix. The data is saved per chromosome and per cluster separately (one file each). The format is {prefix}_{chrom}_{cluster_id}.tab. If no clusters were computed, then only one file per chromosome is produced.


If given, a heatmap file (per chromosome) is saved. Each row in the heatmap contains thediagonal of each of the submatrices centered on the bed file. This file is useful to get an idea of the values that are used for the aggregate matrix and to determine the fraction of sub-matrices that are aggregated that may have an enrichment at the center.

Clustering options


Number of clusters to compute. When this option is set, the submatrices are split into clusters (per chromosome)using the k-means algorithm.


Number of clusters to compute (per chromosome). When this option is set, then the matrix is split into clusters using the hierarchical clustering algorithm, using “ward linkage”. –hclust could be very slow if you have >1000 submatrices per chromosome. In those cases, you might prefer –kmeans


Possible choices: full, center, diagonal

Options are “full”, “center” and “diagonal”. The full clustering is the default and takes all values of each submatrix for clustering. “center”, takes only a square of length 3x3 from each submatrix and uses only this values for clustering. With the “diagonal” option the clustering is only carried out based on the submatrix diagonal (representing values at the same distance to each other.)

Default: “full”

Plotting options

--chromosomes, -C

List of chromosomes to plot.


Color map to use for the heatmap. Available values can be seen here: http://matplotlib.org/examples/color/colormaps_reference.html

Default: “RdYlBu_r”


Possible choices: 2d, 3d

Plot type.

Default: “2d”


Minimum value of the plotted score.


Maximum value of the plotted score.

Usage example

Below, you can find an example of an aggregate Hi-C matrix obtained from Drosophila melanogaster Hi-C data. The interactions are plotted at binding sites of a protein that were determined by ChIP-seq. We plot sub-matrices of 30 bins (1.5 kb bin size, 45 kb in total). The regions specified in the BED file will be centered between half number of bins and the other half number of bins.The considered range is 300-1000 kb. The range should be adjusted and only contain contacts larger than TAD size to reduce background interactions.

$ hicAggregateContacts --matrix Dmel.h5 --BED ChIP-seq-peaks.bed \
--outFileName Dmel_aggregate_Contacts --vMin 0.8 --vMax 2.2 \
--range 300000:1000000 --numberOfBins 30 --chromosomes X \
--avgType mean --transform obs/exp

This example was calculated using mean interactions of an observed vs expected transformed Hi-C matrix. Additional options for the matrix transformation are total-counts or z-score. Aggregate contacts can be plotted in 2D or 3D.