Interval set overlap

Identical to its reference in the validationbedtools’ intersect and jaccard, with a shuffle null (Quinlan and Hall 2010). doi:10.1093/bioinformatics/btq033

In the app

Analysis panel, under 1D tasks: Interval set overlap

Command

chromosomix overlap

Reads

Tracks and interval files, with or without a contact map

Also known as

intersect, Jaccard, bedtools

How many of my peaks sit on a promoter? Interval set overlap measures what two interval sets share, in bases and in features, and with a shuffled null whether that is more than chance.

Running it

Load two interval sets, such as a BED, narrowPeak or GTF, or a set another task called. Open Interval set overlap on the 1D tasks card of the Analysis panel and choose the first set and the second set; no map is needed. The drawer shows Overlap, and with shuffled null on, a second table against the shuffles.

The same run from a shell:

chromosomix overlap <map> --features <a.bed> --a <a.bed> --features <b.bed> --b <b.bed> [--<parameter> <value> …] --out <dir>

Parameters

least of a feature covered is the share of a feature that must lie inside the other set for it to be hit; the default is any overlap at all for a feature shorter than a megabase. shuffled null turns the test on, and set that moves is the set shuffled, which matters: are my peaks on promoters moves the peaks. More shuffles give a finer p.

Parameter	Takes	Default	What it does
first set--a <file>	a file: a feature set	—	—
second set--b <file>	a file: a feature set	—	—
least of a feature covered--minFraction <n>	a number, 0 to 1	0.000001	A feature counts as hit when this fraction of it is inside the other set.
shuffled null--shuffle / --no-shuffle	on or off	off	Relocates one set at random within the sequences it already occupies, keeping its count and its lengths, and reports the observed overlap against that null.
set that moves--shuffleWhich <value>	a or b	a	a — “Are the first set’s features on the second’s?”; b — the second. Read only under other settings of this task.
shuffles--iterations <n>	a whole number, 20 to 100000	1000	The smallest p a run can report is one over this, plus one. Read only under other settings of this task.
seed--seed <n>	a seed, a whole number	1	The same seed gives the same null twice. Read only under other settings of this task.

What it writes

• table: a table: TSV

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

Reading the result

The overlap

• Jaccard (bases): the shared bases over the bases in either set, from 0 to 1 and the same whichever set is first; 1 is two identical sets.
• Shared bases, Bases in either and each set’s own bases count a base once, after a set’s own overlaps are merged, such as a GTF’s transcripts.
• First set hit and Second set hit: the share of each set’s features that touch the other, with the counts. They are not symmetric: forty peaks of a hundred on a promoter is not forty promoters of a thousand on a peak.

Against the shuffles

Forty per cent of a set on another may be what any intervals covering that much of the genome would give. The second table sets the observed Jaccard, shared bases and features hit against the shuffles:

• Observed, and Expected, the null’s mean;
• Fold, observed over expected, and z;
• p, a permutation p on the tail the observation fell on, named under Tail as enriched or depleted.

A good result is a fold well away from 1 with a small p. The p never reaches zero: with 1,000 shuffles the smallest is about 0.001, and a p at that floor may fall with more shuffles. The same seed gives the same null.

What to watch for

The shuffle needs each sequence’s length. Where the session does not know one, it uses the furthest position either set reaches there, which overstates the enrichment, and names the sequence. Open the map, a chrom.sizes or a bigWig beside the sets to give it the real lengths.

Compared with bedtools

In the validation, the counts are those of bedtools’ jaccard and intersect -u, and the null is distributed as bedtools shuffle -chrom’s.