hi-c-expected-value-calculation

hi-c-expected-value-calculation

Summary

Compute expected contact frequency as a function of genomic distance from a Hi-C contact matrix, producing a distance-binned expected value table that serves as a null model for detecting significant interactions and normalizing contact probability P(s) curves.

When to use

You have a cooler-format Hi-C contact matrix and need to establish a genome-wide baseline contact frequency by genomic distance. This is essential when you want to normalize observed contacts, compute O/E ratios, generate P(s) smoothing pipelines, or identify deviation from random polymer behavior. Use this skill before applying downstream analyses like saddle plots, insulation scoring, or contact probability smoothing.

When NOT to use

• You only have raw read counts and no contact matrix binned into a cooler file — first construct the Hi-C contact matrix.
• Your Hi-C dataset has extreme sparsity or low coverage (< 10 million valid contacts) — expected values will be unreliable and noise-dominated.
• You are working with a single locus or a small region and do not need genome-wide baseline statistics.

Inputs

• cooler file (.cool or .mcool format)
• bin resolution (in base pairs, typically 5 kb – 100 kb)
• optional: bin-level mask or filter (e.g., list of bad bins to exclude)

Outputs

• expected_cis table (TSV format with columns: dist_bp, contact_frequency, n_valid)
• optionally: expected_trans table for inter-chromosomal contacts

How to apply

Load a cooler Hi-C contact matrix at a chosen bin resolution (e.g., 10 kb or coarser). Use cooltools' expected module to sum contact counts across all pairs of bins at each genomic distance, accounting for valid bin pairs via masking or filtering. The function iterates over distance lags, aggregates contacts, normalizes by the number of valid bin pairs at each distance, and produces a table with columns: distance in base pairs (dist_bp), contact frequency (count or normalized frequency), and bin pair count statistics (n_valid). Export the resulting expected_cis table as TSV format. This precomputed table is then used as input to downstream smoothing (logbin_expected) or O/E normalization workflows.