jukebox-hic

Lightweight Hi-C noise analysis toolkit for .hic (hicstraw) and cooler formats (.cool, .mcool, .scool).

Features

• Per-row noise estimates with optional subsampling simulations to gauge robustness.
• Configurable row filtering based on distance-normalized signal and window occupancy.
• Works with .hic, .cool, .mcool, and .scool input matrices (SciPy-backed pipeline for cooler formats).
• Whole-genome noise tracks at requested resolutions.
• Simple plotting helpers for comparing noise distributions (log-scaled histograms).

Installation

Default install — both backends (cooler + hicstraw):

pip install jukebox-hic

Single-backend profiles:

# cooler only (.cool / .mcool / .scool)
pip install "jukebox-hic[cooler]"

# hicstraw only (.hic)
pip install "jukebox-hic[straw]"

Windows users — known PyPI install error

hic-straw does not ship pre-built wheels for Windows on PyPI and may fail to compile from source. If pip install jukebox-hic errors during the hicstraw build step, bypass the default install and use the cooler-only profile:

pip install jukebox-hic --no-deps
pip install numpy pandas statsmodels matplotlib scipy cooler

To process .hic files on Windows, convert them first with hic2cool and use the cooler backend:

pip install hic2cool
hic2cool convert sample.hic sample.mcool --resolutions 10000
jukebox-hic sample-noise --hic sample.mcool --cooler_path /resolutions/10000 --res 10000 --out_dir outputs/

Command Line Usage

Sampled noise with subsampling summaries

jukebox-hic sample-noise \
  --hic sample.cool \
  --res 10000 \
  --min_mean_score 0.9 \
  --min_nonzero_frac 0.05 \
  --subsample_ratios 1.0,0.75,0.5,0.25 \
  --norm balance \
  --out_dir outputs/10kb \
  --seed 42 \
  --profile outputs/10kb/profile.csv

Produces one <chrom>_<res>.bedgraph for the original map and a subsample_summary.tsv table with mean/median/log noise, ACF, variability, and empty-bin ratios at each subsample.

Noise bedgraph (genome-wide)

jukebox-hic noise-bedgraph \
  --hic sample.hic \
  --res 5000,10000 \
  --out_dir outputs/
# Add --cpu <N> to parallelize per (chrom, res) tasks
jukebox-hic noise-bedgraph \
  --hic sample.hic \
  --res 5000,10000 \
  --out_dir outputs/ \
  --cpu 4
# For .mcool/.scool inputs you can add: --cooler_path /resolutions/10000

Plotting

jukebox-hic plot \
  --noise_bed outputs/chr1_10000_sampled.bedgraph \
  --out_png noise_density.png

Build a blacklist from bedgraphs

jukebox-hic blacklist \
  --input outputs/10kb/*.bedgraph \
  --out blacklist.bed \
  --top_quantile 0.95

This command removes any rows with NaN noise values and blacklists the top 5% most noisy intervals by default. Provide --zscore_cutoff to supply an explicit z-score threshold instead of using the percentile.

Python API

from jukebox_hic import noise_sampling

noise_sampling.compute_sampled_noise(
    hic_path="sample.cool",
    res=10_000,
    sample_fraction=1.0,
    min_mean_score=0.9,
    min_nonzero_frac=0.05,
    subsample_ratios=[1.0, 0.5, 0.25],
    norm="balance",
    out_dir="outputs",
    seed=42,
)

Notes

• For .mcool, the CLI selects the group matching --res (e.g. /resolutions/10000). Provide --cooler_path for .scool cell groups or custom URIs.
• --norm accepts none, balance (cooler weights / KR for .hic), or a path to a bedgraph/vector defining custom bin weights.
• All commands print a summary line with wall-clock time and memory usage; install the optional profile extra for psutil-backed RSS reporting.
• --profile writes per-chromosome runtime and memory metrics to a CSV for downstream plotting.
• --cpu <N> parallelizes noise-bedgraph by (chromosome, resolution) tasks (default 1, capped at available cores).
• Every CLI invocation now emits a contacts_overview.tsv summarizing per-chromosome totals at the coarsest resolution.

Backends

This project supports two I/O backends, both included in the default install:

Runtime guidance:

• If you pass a .hic file without hicstraw installed, the tool will suggest pip install "jukebox-hic[straw]".
• If you pass a cooler-format file without cooler installed, the tool will suggest pip install "jukebox-hic[cooler]".
• The same --cooler_path argument selects resolution groups in .mcool files and cell groups in .scool files.

Changelog

v0.3.0

• noise-bedgraph subcommand — renamed from full-noise for clarity. All existing flags are unchanged.
• Region-filtered --chrom_sizes — the chromosome sizes file now accepts optional region columns (cols 3+) in start:end or start-end format (0-based, half-open). When regions are present, only bins overlapping those regions are emitted. The noise window still extends up to --bindist_bp on each side of the region, with chromosome-end clamping applied as usual. A region smaller than one bin outputs the single overlapping bin. Regions that exceed the chromosome size produce a warning and are skipped; chromosomes with no valid regions are skipped entirely.

  # Example extended chrom_sizes file (TSV):
  # chrom    size         region1              region2
  chr1       248956422    0:50000000           100000000:150000000
  chr2       242193529
  chrX       156040895    5000000-10000000
  

• Multi-mode blacklist output — blacklist and default-run now produce four output directories per run (density_only/, noise_only/, union/, intersection/) instead of a single file, enabling comparison of conservative and permissive thresholds.
• Default transforms changed to log1p — both --density_transform and --noise_transform now default to log1p (previously none and sqrt respectively). log1p is more robust to outlier bins (repeats, centromeres) that can skew elbow detection.
• Both backends in default install — pip install jukebox-hic now includes both cooler and hic-straw. Single-backend profiles [cooler] and [straw] are available for constrained environments.

v0.2.4

• Initial public release.