Hi-C track
Hi-C measures how often pairs of genomic loci contact each other in the nucleus.
JBrowse draws it as a triangular contact matrix, brighter where contacts are
more frequent, reading .hic files (Juicer and compatible pipelines) in place
over HTTP range requests.
Loading a Hi-C track
In the "Add a track" form, paste the URL to a .hic file (or open it from
disk). JBrowse detects the format from the extension and creates a Hi-C track.
To try it without preparing anything:
https://jbrowse.org/genomes/hg19/intra_nofrag_30.hicOnly the .hic format is supported. Cooler files (.cool, .mcool) need
converting first, e.g. with hicConvertFormat from HiCExplorer.
Reading the contact matrix
Mousing over the matrix draws a V-shaped guide down to the two positions the bin under the cursor pairs, with a tooltip giving both loci and the contact score. The guide tracks over empty bins too, so it reads positions anywhere in the triangle.
Adjusting resolution
JBrowse picks a resolution to fit the view width. Zoom in for finer bins, out for larger-scale structure. For manual control, open the Resolution item in the track menu: the Finer/Coarser buttons step through the binning levels stored in the file, disabling at the finest and coarsest available, and the menu stays open so you can step repeatedly. Stepping applies a persistent offset from the auto-selected level, so resolution still tracks your zoom, just shifted. Reset returns to auto.
Adjusting the color scale
Pick the ramp from the track menu's Color scheme:
- Juicebox - transparent to red, the default
- Fall - white through yellow and red to black
- Reds and Blues - white to red, and white to blue
- Viridis, Magma, Inferno and Cividis - perceptually uniform; cividis is the safest choice for readers with color vision deficiency
A bin with no contacts is left unpainted, so the page shows through it, and a
ramp that is dark at its low end would scatter dark specks across the sparse
long-range half of the matrix. So viridis, magma, inferno and cividis run light
to dark unless color.reverse says
otherwise, whether picked from the menu or named in a config. These are the
ramps every color scale in JBrowse names, so a config spells one as
color.scheme.
Color scheme → Emphasize faint contacts (95th percentile) decides what the ramp spans. Off, the diagonal owns the scale and everything below it washes out; on (the default) the scale saturates at the 95th percentile of counts and TAD structure separates from background.
Color scheme → Log scale maps counts to color on a log2 scale, compressing the diagonal further still.
The scale's top follows the loaded counts, so it moves as you zoom and differs
between tracks. To compare two tracks, or one region at two zooms, on one scale,
pin the top in each track's config with
color.domainMax:
"displayDefaults": { "color": { "domainMax": 500 } }Normalization
Raw contact counts have coverage biases from restriction-site density,
mappability, and GC content. .hic files ship precomputed matrix-balancing
vectors, and the track menu's Normalization submenu lists only the schemes
the file actually contains:
- KR - Knight-Ruiz, the recommended default
- SCALE - a faster approximation to KR
- VC and VC_SQRT - vanilla coverage
- NONE - raw observed counts
Vectors are stored per chromosome and binsize, so a file can list a scheme that is missing at the binsize on screen. The menu ticks the normalization the loaded matrix actually has rather than the one requested, and the unavailable entry says which scheme was substituted. Stepping to a finer resolution usually resolves it.
Comparing two regions
The matrix is fetched for every pair of displayed regions. Open a second region in the same view and the contacts between the two fill the space between their triangles — the same geometry that puts a bright off-diagonal block at a translocation's partner loci. The Hi-C structural variants tutorial shows that block on a real one, chr9 against chr22 in K562.
Inter-chromosomal matrices are commonly only stored at coarse binsizes. When the auto-picked resolution is finer than anything the file holds for that pair, the cross-block is absent while the intra-chromosomal triangles still draw. Step Coarser until it appears.
The same pairwise geometry scales to the whole genome. View → Zoom → Show all regions in assembly puts every chromosome in the view at once, which makes the fetch every chromosome against every other one and the drawing a block diagonal: each chromosome is a triangle along the bottom edge, each pair of chromosomes is the block between their two triangles, and the whole pyramid is the genome against itself.
How much figure this is depends on the file. A file storing only
intra-chromosomal contacts leaves every block between the triangles empty, so
check a candidate before reading anything into a blank off-diagonal. It also
decides the sensible ramp: a sparse file needs a log
color.scale to lift its decayed
long-range bins off the floor, and a dense one comes back solid under the same
setting, since every bin then reaches the top of the scale.
The track has to be tall here. A pair's contacts are drawn in the wedge between its two regions, so the drawing is as tall as the widest pair on screen is wide, and at whole-genome zoom that is chr1 against chrY: half the view. A hundred-pixel track shows the top slice of that pyramid, which is its faintest corner.
Fitting the triangle to the track height
The triangle's natural height is half the view width, so on a wide view it is taller than the track and the lower half is cut off. Show → Fit to display height squashes it vertically to whatever height the track is dragged to, trading square bins for seeing the whole triangle.
Overlaying loops and interactions as arcs
Loop and interaction calls (HiCCUPS loops, ABC/EPIraction enhancer–gene links) ship as BEDPE files with two endpoints per line. A mark display draws each call as a link from one end to its mate, so you can stack the called loops directly above the matrix they came from.
Add the BEDPE file from Add a track and pick Marks from the track menu's
display types: the display sees each call name its other end and draws the arcs
with nothing configured. Then add the .hic matrix as a separate track and
reorder so the links sit above it. A link's size sets its stroke width, and
encoding.size scales it by the score.
Compartments and subcompartments
At tens of megabases the matrix separates into two interleaved sets of regions
that preferentially contact their own kind: the A compartment, which is
gene-rich and active, and the B compartment, which is not. In a published figure
this reads as a checkerboard, but that picture is drawn from an
observed/expected matrix, where each bin has been divided by the average
contact at its separation and then correlated. JBrowse draws raw or
matrix-balanced counts, and against the steep decay of contact with distance the
compartment signal stays a faint texture. Balanced counts on a linear ramp show
the most of it; Log scale on a deeply sequenced file returns solid red.
Load the compartment call itself; the processing pipeline has already made it. ENCODE publishes two such files per Hi-C experiment, both derived from the matrix in the same track:
- The compartment eigenvector, a BigWig. Its sign is the compartment assignment and its magnitude is how strongly a bin belongs, so it loads as an ordinary quantitative track and draws as a two-color plot around zero.
- Subcompartments, a BED. Clustering the interaction profiles splits A and B
further, and the file has a color per class in its
itemRgbcolumn, so the track paints itself with no color configuration.
Two things about that figure are worth copying whenever you compare compartments between samples, since getting either wrong invents a difference.
Pin both eigenvector tracks to the same scale. Left to autoscale, each track scales to its own min and max, so the two stop being comparable. Set the min and max score by hand, from the track menu or in config.
An eigenvector identifies A only up to a sign. The decomposition that produces it is equally valid negated, so which sign means "active" is a property of the file, and comparing two files means their orientations have to agree as well. Both are checkable against the gene track: A is the gene-rich compartment by definition, so the sign that coincides with the dense stretches of the gene track is A. Do that check over a whole chromosome rather than in one frame, since a few megabases can be gene-poor in both samples and settle nothing. In both files above, positive is the gene-rich side.
The subcompartment classes need the same caution in a different place. The cluster numbers a caller emits are arbitrary labels rather than the published A1/A2/B1/B2/B3 naming, so a class number means nothing on its own and two files only compare because the same pipeline assigned the same colors. A class number can move between two files without the eigenvector moving at all, which is a relabelling rather than a switch.