Compartments

Equivalent to its reference in the validationThe first eigenvector (Lieberman-Aiden et al. 2009), as cooltools’ eigs_cis takes it. doi:10.1126/science.1181369

In the app

Analysis panel, under 2D tasks: Compartments

Command

chromosomix compartments

Reads

A contact map

Also known as

A/B, eigenvector, E1, PCA, saddle, correlation

Compartments finds the checkerboard of a chromosome’s two kinds of chromatin, each touching its own kind more than the other. E1, the leading component of the map over its expected, is the compartment track. Phased by genes, a track or GC content, it is cut by its sign into A and B, and the saddle plot measures how strongly they keep apart.

Running it

Open the map at a resolution that suits compartments: on a mammalian genome 250 kb is usual, 100 kb the fine end. To phase the result, load a gene model such as a GTF, a track, or the genome’s FASTA (Tracks and features, Reference sequences). In the Analysis panel (4), choose Compartments, check Phasing, and press run.

E1, and E2 and E3 with components at 2 or 3, land in the Tracks card of the Annotations panel, marked *, with A/B compartments beside E1. The drawer holds the Components table, the saddle (with draw the saddle on) and notes on the phasing and on bins with too little data.

The same run from a shell:

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

To phase by GC content, load the reference with --sequence and name it again for the parameter:

chromosomix compartments sample.mcool::/resolutions/100000 --sequence ref.fa.gz --phaseSequence ref.fa.gz --out results/

A gene model is loaded and named the same way, --features genes.gtf --phaseFeatures genes.gtf; a track is named alone, --phaseTrack signal.bw.

Parameters

Contacts and method decide the run. Cis only, the default, gives a track per chromosome and is the one that runs at a fine resolution; cis and trans gives one genome-wide answer; trans only leaves the distance decay out. Under cooltools, the default method, the tracks are on cooltools’ own scale; Lieberman-Aiden 2009 is the paper’s correlation of rows. The two agree where a chromosome has compartments, and part where it has none. Diagonals to ignore keeps the near-diagonal, the map’s largest and least structural cells, out of the matrix.

Parameter	Takes	Default	What it does
General
sequences--sequences <name,…>	sequence names, comma-separated	Every sequence of the file when left out.	One correlation per sequence under “cis only”, and one over all of them under “cis and trans” or “trans only”.
contacts--contacts <value>	cis, both or trans	cis	cis — one correlation per sequence, over its own contacts. The cheapest, and per chromosome; both — one correlation over everything ticked. Each half keeps its own expectation; trans — between sequences alone, so no distance decay enters the answer. Needs two or more.
diagonals to ignore--ignoreDiags <n>	a whole number, at least 0	2	0 keeps every cell; 1 drops the main diagonal; 2 drops it and the two beside it.
expected--expected <value>	distance or arms	distance	distance — the mean of each diagonal: the ordinary observed/expected; arms — also removes the secondary diagonal of a bacterial chromosome whose arms are aligned, reading the arms from the origin on the Chromosomes table — the first base unless set.
window along the arms--armWindow <n>	a whole number, at least 0, in bins	50	Each cell is compared within this far along the arms; 0 is the whole chromosome. Read only under other settings of this task.
method--method <value>	cooltools or correlation	cooltools	cooltools — observed/expected itself, clipped at its 99.9th percentile and less one, decomposed; correlation — the Pearson correlation of observed/expected’s rows, decomposed.
components--components <n>	a whole number, 1 to 3	1	E1 is the compartment track; E2 and E3 occasionally say something.
use balancing weights--no-balance	a switch	On wherever the file carries balancing weights; --no-balance reads the raw counts.	—
Phasing
phase by gene density--phaseFeatures <file>	a file: a feature set; optional	not used	Positive is made to mean the compartment these features are dense in.
phase by a track--phaseTrack <file>	a file: a signal track; optional	not used	Positive is made to follow this track, when no gene model is chosen.
phase by GC content--phaseSequence <file>	a file: a reference sequence; optional	not used	Used when neither a gene model nor a track is chosen.
least convincing correlation--minR <n>	a number, 0 to 1	0.1	Below this the sign is left alone and the drawer says the phasing was ambiguous.
Saddle
draw the saddle--saddle / --no-saddle	on or off	on	The compartment claim in one square, with AA, BB and AB under it.
quantile groups--quantiles <n>	a whole number, 5 to 100	50	—

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)
• matrix: a matrix, a pileup or a heatmap: TSV
• table: a table: TSV

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

Reading the result

Phasing: which way up

An eigenvector’s sign means nothing until something phases it. Phasing uses the first of these that is chosen:

1. phase by gene density: a gene model, positive where its features are dense;
2. phase by a track: any loaded or computed track, positive where it is high;
3. phase by GC content: a reference sequence, positive where it is GC-rich.

Gene density and GC content start on what you loaded, the starred set or sequence or else the first; a track starts unset. Any interval set counts as a gene model, so check it before you run: if it is a set of peaks, pick another or Do not use a gene model.

A component is turned to correlate positively with the signal once that correlation reaches least convincing correlation. Below it, the drawer says the phasing was ambiguous: do not compare E1’s sign with another run’s. With no phasing at all, every sign is arbitrary.

E1, E2 and E3

Components are ranked by eigenvalue alone, so E1 always has the largest; phasing signs them but never picks among them. If E1 does not follow the phasing signal, E2 is worth a look. The Components table has a row per sequence and component:

• eigenvalue;
• of contacts: the share of the map’s departure from expected (observed/expected, clipped, less one) that this component’s checkerboard carries; the shares of several components add up;
• r with phasing: Pearson’s r with the phasing signal, positive once the sign is fixed;
• variance, under Lieberman-Aiden 2009 only: how alike the rows are, rather than how much of the map.

Bins with too little data are gaps in the tracks, not zeros.

A and B

Each run of bins on one side of zero is a segment, A where E1 is positive and B where it is negative. A is the compartment the phasing signal is high in, and means nothing more. Segments never cross into the next sequence, and save as a BED for signal by group or interval set overlap.

The saddle

The saddle sorts a sequence’s bins by E1 into quantile groups (50 by default) and draws the mean observed/expected between every two groups, from B to A on both axes, with 1 in the middle of its scale. Under cis only there is one per sequence. Under it are three corner means, each over the fifth of the groups at that end: AA, the most A-like bins with each other; BB, the most B-like; AB, the two with each other. A map with compartments has AA and BB above 1 and AB below: bright corners on the diagonal, dark ones off it. The further apart, the stronger the compartments. Under an ambiguous phasing the saddle also shows the phasing r, as AA and BB may be the wrong way round.

What to watch for

• Size. A matrix past 8,192 bins a side is refused: under cis only that sequence is skipped and named; otherwise the run says what to untick or how coarse to open the file. Under Lieberman-Aiden 2009 the cost grows as the cube of the bins, and past about 2,000 the price beside run names a resolution that fits.
• A chromosome with no compartments. E1 still carries whatever dominates its map; a small of contacts and a weak r with phasing give it away.
• Circular sequences. A sequence ticked circular in the Chromosomes table is divided by its decay the short way round.
• Bacterial chromosomes. Where the two arms are held together, the map has a second diagonal, and divided by the distance decay alone E1 follows the arms rather than compartments: on a Pseudomonas aeruginosa map, the distance from the origin. Expected at decay along both arms, under cis only, removes both diagonals within window along the arms bins (0 is the whole chromosome), and on that map E1 then follows GC content. The arms are read from the origin in the Chromosomes table, the first base unless set; Inter-arm alignment measures the second diagonal.

Compared with cooltools

Under the default method all three components are cooltools.eigs_cis‘s on the same balanced matrix. In § 3 of the validation, on a mouse Hi-C map at 100 kb phased by GC content, E1 agrees with cooltools’ to 5·10⁻⁶ in any bin, the eigenvalues agree, and the A/B call is the same in every bin.

The badge says equivalent because of the sign: cooltools phases by Spearman’s correlation, this task by Pearson’s r, left alone below least convincing correlation, so an E2 or E3 that barely follows GC content can come out the other way round. The saddle matches cooltools.saddle (§ 21) to the digits written. The Lieberman-Aiden 2009 method is not validated.