bed-compare ✨

Compare BED tracks by base-pair overlap, genome complements, enrichment, and clustered Jaccard heatmaps. 🧬

Requirements ✅

Use uv to install and run the tool. The project metadata defines the required Python version and dependencies.

Install 📦

The Git repository is:

https://gitlab.fht.org/david.mas/bed-compare

Install globally from Git:

uv tool install git+https://gitlab.fht.org/david.mas/bed-compare

Install from a local checkout:

git clone https://gitlab.fht.org/david.mas/bed-compare
cd bed-compare
uv tool install --editable .

Check the installed command:

bed-compare --help

Usage 🚀

bed-compare currently provides three modes:

bed-compare compare   --genome genome.fai --output compare.tsv   tracks/*.bed
bed-compare enrich    --universe universe.bed --output enrich.tsv tracks/*.bed
bed-compare visualize --genome genome.fai --output heatmap.html  tracks/*.bed

Input Files 📁

All modes use BED inputs:

• 🧾 BED files: two or more .bed or .bed.gz files.
• 📤 Output path: provided with --output / -o.

BED parsing uses the first three BED columns: chromosome, start, and end. Extra columns are ignored. Empty lines, comments, track lines, and browser lines are skipped.

For compare and visualize, --genome is required and must be a FASTA .fai index or a whitespace-delimited genome file where the first two columns are chromosome name and chromosome length. Coordinates must be valid for the provided genome file.

For enrich, --universe is required and can be a BED/BED.gz file, a FASTA .fai index, or a genome file. Input tracks are clipped to the universe before enrichment counts are computed.

Overlapping or adjacent intervals within each BED are merged before comparisons are computed.

compare Output 🔍

compare writes a TSV table of pairwise shared-base and Jaccard comparisons.

The comparison set includes each input BED track and its generated genome complement, so output row counts include original-vs-original, original-vs-complement, and complement-vs-complement pairs.

Columns:

track_a
track_b
bases_a
bases_b
shared_bases
union_bases
jaccard

enrich Output 📈

enrich writes a TSV table of pairwise enrichment tests across the original input BED files only. It does not generate or compare complements.

Columns:

track_a
track_b
both_included
bed2_included_bed1_excluded
bed2_excluded_bed1_included
neither_included
odds_ratio
p_value
reverse_p_value
two_sided_p_value

The enrichment test uses base-pair counts over --universe. p_value is the one-sided Fisher exact p-value for enrichment (odds_ratio > 1), reverse_p_value is the one-sided p-value for depletion (odds_ratio < 1), and two_sided_p_value tests for either direction (odds_ratio != 1). If the universe is a BED file, all input tracks are intersected with that BED first, and bases in the universe that are not covered by either track become neither_included. If the universe is a genome or .fai file, the universe is the full set of chromosome spans.

visualize Output 🌡️

visualize writes an interactive HTML heatmap.

The heatmap uses the same Jaccard comparisons as compare, including generated complements. Rows and columns are clustered by Jaccard distance, and the output can be opened in a browser.