Matrix plots

After importing fanc.plotting as fancplot, we have access to a range of Hi-C (and related) matrix plots. We already used the TriangularHicPlot as an example in Plotting API basics. In total there are four types of matrix visualisation built in to FAN-C:

• SquareHicPlot, which shows a square matrix, with colors typically representing contact strength between the two genomic regions on the X, and Y axes, respectively.

• TriangularHicPlot, which rotates the matrix by 45 degrees, so instead of a square, it now becomes a triangle. This can be particularly useful if features close to the matrix diagonal, such as TADs, are of interest, and if additional genomic tracks, such as CTCF binding, should be shown underneath

• SplitMatrixPlot, which is similar to the SquareHicPlot, but the values above and below the diagonal are from different matrices. This is a great way for direct matrix feature comparisons in the same plot.

• MirrorMatrixPlot, which can be used to show two matrix plots, particularly of the type TriangularHicPlot, mirrored at the X axis

All of these are built on the base class BasePlotterMatrix, so they share of lot of options and functionality. Let’s look at each of them in turn.

Square matrix

To generate a basic square matrix plot, run

hp = fancplot.SquareMatrixPlot(hic)
hp.plot('chr18:6mb-10mb')
hp.show()

Currently, the diagonal is about the only thing visible in this example, so let’s adjust the saturation of the plot with vmax (vmin can be used to set a lower bound)

To generate a basic square matrix plot, run

hp = fancplot.SquareMatrixPlot(hic, vmax=0.05)
hp.plot('chr18:6mb-10mb')
hp.show()

FAN-C uses the custom “germany” colormap as a default, built using the colormap scripts from Stéfan van der Walt and Nathaniel Smith, which have also been used to generate the default matplotlib colormaps. It is “perceptually uniform”, and thus well-suited to represent contact intensities. We are also including a colormap called “white_red”, for a more classic Hi-C matrix look, but equally perceptually uniform:

hp = fancplot.SquareMatrixPlot(hic, vmax=0.05, colormap='white_red')
hp.plot('chr18:6mb-10mb')
hp.show()

Any Matplotlib-compatible colormap can be used to change the look of your matrix. You can remove the colorbar, for example if you want to add your own on a different axis, using show_colorbar=False. Alternatively, if you have set up your axes manually, you can move the colorbar to an axis of your choice using cax=<your axis> in the constructor.

The exponential decay of contact intensities with distance between any two loci can sometimes make it difficult to visualise features close to the diagonal and far fro it simultaneously. Sometimes showing colors on a log scale can improve this:

hp = fancplot.SquareMatrixPlot(hic, vmax=0.05, norm='log')
hp.plot('chr18:6mb-10mb')
hp.show()

You can show uncorrected values using matrix_norm=False (note the color scale change):

hp = fancplot.SquareMatrixPlot(hic, vmax=30, matrix_norm=False)
hp.plot('chr18:6mb-10mb')
hp.show()

We can also show log2 observed/expected values using oe=True and log=True When not setting the colorbar limit explicitly, you can also make the colorbar symmetrical around 0 using colorbar_symmetry=0. We will also use a divergent colormap:

hp = fancplot.SquareMatrixPlot(hic, vmin=-2, vmax=2, oe=True, log=True,
                               colormap='RdBu_r')
hp.plot('chr18:6mb-10mb')
hp.show()

Triangular matrix

Any of the above customisations also work for the triangular version of the matrix plot, TriangularHicPlot.

hp = fancplot.TriangularMatrixPlot(hic, vmax=0.05)
hp.plot('chr18:6mb-10mb')
hp.show()

Additionally, we can control the height, at which the triangle is cut off, and therefore the maximum distance at which contacts are shown between two regions, with max_dist. This value is expressed in base pairs, but supports strings in genomic format:

hp = fancplot.TriangularMatrixPlot(hic, vmax=0.05, max_dist='2mb')
hp.plot('chr18:6mb-10mb')
hp.show()

Split matrix

The SplitMatrixPlot requires two Hi-C objects, one for above, and one for below the diagonal. Unless you explicitly set scale_matrices to False, the plot will first scale both matrices to the same sequencing depth, in order to make them more comparable. Depending on your normalisation, this may not be necessary.

Mirrored plot

To showcase the MirrorMatrixPlot, we can plot the Hi-C matrix, and its O/E transformation at the same time:

# first create two triangular plots
top_plot = fancplot.TriangularMatrixPlot(hic, vmax=0.05, max_dist='2mb')
bottom_plot = fancplot.TriangularMatrixPlot(hic, vmin=-2, vmax=2, oe=True, log=True, colormap='RdBu_r', max_dist='2mb')
# then merge them
hp = fancplot.MirrorMatrixPlot(top_plot, bottom_plot)
hp.plot('chr18:6mb-10mb')
hp.show()

Opposed to Split matrix, it is also possible to combine matrices of different resolution, or from different Hi-C experiments, as long as they are from the same organism.