Directionality index

Identical to its reference in the validationThe directionality index of Dixon et al. 2012, as domaincaller computes it. doi:10.1038/nature11082

In the app

Analysis panel, under 2D tasks: Directionality index

Command

chromosomix di

Reads

A contact map

Also known as

DI, TAD, domains, boundaries

The directionality index asks which way each bin’s contacts lean. Near a domain’s start nearly everything a bin touches is downstream, near its end upstream, so each domain is a run of positive values then negative ones, and the flip from negative to positive between two domains is a border.

Diamond insulation finds where little contact crosses a bin; the index, where a bin’s contacts change side. A border both agree about is a border: count how many of one set sit on the other with interval set overlap.

Running it

In the Analysis panel (4), choose Directionality index, tick the sequences, set the window, and press run. Three rows land in the Tracks card of the Annotations panel, marked *: the index, named after its window (DI · 2 Mb for the default 50 bins on a 40 kb map); DI borders, one-bin segments beside it; and DI domains, drawn on the map as the corner of each domain’s square. A called set’s display moves it between a 1D track and a map overlay.

The same run from a shell:

chromosomix di <map> [--<parameter> <value> …] --out <dir>

For example, Dixon et al.’s 2 Mb window on the 50 kb rung of an .mcool:

chromosomix di sample.mcool::/resolutions/50000 --window 40 --out results/

Parameters

Window is the one to set for your map: the bins summed either side of each bin. The default, 50, is Dixon et al.’s 2 Mb at 40 kb; the same 2 Mb is 200 bins on a 10 kb map. Give it insulation’s window to read the two at one scale. Below five bins, the drawer warns.

Parameter	Takes	Default	What it does
General
window--window <n>	a whole number, at least 1, in bins	50	Contacts are summed this many bins each way of every bin, 50 being Dixon et al.’s 2 Mb at the 40 kb they worked at.
sequences--sequences <name,…>	sequence names, comma-separated	Every sequence of the file when left out.	—
use balancing weights--no-balance	a switch	On wherever the file carries balancing weights; --no-balance reads the raw counts.	—
Quality
diagonals to ignore--ignoreDiags <n>	a whole number, at least 0	0	0 counts every cell; the bin’s contact with itself is never in either sum.
minimum coverage of each side--minValid <n>	a number, 0 to 1	0.5	Below this fraction of usable cells — on either side — the bin gets no score.
Borders
call borders--call / --no-call	on or off	on	Adds the borders as a set of their own, a 1D track under the index to begin with.
minimum prominence--prominence <n>	a number, 0 to 200	10	How many bins of steady bias the track must carry on both sides of a flip.
minimum spacing--spacing <n>	a whole number, at least 0, in bins	0	Two calls closer than this many bins keep only the stronger.
domains between them--domains / --no-domains	on or off	on	A second set, the span from each border to the next, drawn as corners along the diagonal to begin with.

What it writes

• profile: a value per bin: TSV, bedGraph and bigWig
• intervals: a set of intervals: TSV, and BED (or BEDPE for pairs, or bed3d and PDB for a 3D model)

On the command line every file goes into --out as <file stem>.di.<output>.<ext>, and each TSV opens with # lines naming the build, the file and every parameter that produced it.

Reading the result

The index

With A a bin’s contact with the window bins upstream and B with those downstream, its value is sign(B − A) · (A − B)² / (A + B): a signed χ² against a bin that favours neither side. Positive, the bin looks downstream, as a domain’s first half does; negative, upstream, as its second half does; near 0, it is even-handed. A χ² grows with sequencing depth, so compare the shapes of two tracks, not their values.

A bin needs a whole window on both sides: the first and last window bins of a linear sequence have no value, and a sequence no longer than twice the window is not scored. Minimum coverage of each side leaves out a bin where either side has less than that share of usable cells, as beside a dropped stretch the χ² would be huge exactly where a boundary is most tempting to believe.

Diagonals to ignore is 0 by default, where insulation’s is 2: the near-diagonal is in both sums and largely cancels.

The borders and the domains

The index is scaled by its median absolute value and summed along the sequence. The running sum climbs through downstream-leaning stretches and falls through upstream-leaning ones, so each border is a trough, and a stutter across zero only a dimple on its flank. Troughs are kept by prominence, as insulation’s boundaries are.

Minimum prominence is therefore in bins of steady bias, not χ²: at the default of 10, the track must carry about ten bins of ordinary lean on both sides of a flip. The units do not move with depth, so a prominence that worked on one map is worth trying on the next. Each border sits on the first bin of the new domain, one past its trough, is named border_1, border_2, … in genomic order, and is scored by its prominence. Minimum spacing keeps the stronger of two borders closer than that many bins.

The domains run from each border to the next on its sequence, named domain_1, domain_2, … and scored by their weaker border. A stretch with no value carries the running sum across it, but cannot be a trough’s floor.

What to watch for

• The window on this file. The same number of bins is a different distance at every resolution. The drawer says what it came to, as in A 50-bin window is 2 Mb at this file’s 40,000 bp resolution., and so does the track’s name: check it before comparing with a published window.
• Circular sequences. A sequence ticked circular in the Chromosomes table is read round its junction, so every bin is scored, but the domain spanning the junction is never reported.

Compared with domaincaller and Dixon et al.

The index is domaincaller’s calDI. In § 2 of the validation, on a mouse Hi-C map at 50 kb with a 2 Mb window, every bin both tools score agrees within float32 rounding; the bins only domaincaller scores are those this task’s coverage rule leaves out. The borders are not Dixon et al.’s hidden Markov model, which leaves stretches it calls unorganised in no domain, so a published domain set can have gaps that these domains do not.