contact-frequency-smoothing-log-space

contact-frequency-smoothing-log-space

Summary

Apply logarithmic binning and smoothing to precomputed expected contact frequency tables to produce log-binned, smoothed contact probability P(s) curves suitable for Hi-C distance decay analysis. This skill transforms raw distance-frequency pairs into log-spaced bins with smoothed contact frequencies, essential for characterizing the relationship between genomic distance and contact probability.

When to use

You have a precomputed expected contact frequency table (TSV with columns: dist_bp, contact_frequency, n_valid) derived from cooler Hi-C matrices and need to generate a smoothed, log-binned P(s) curve for downstream analysis such as TAD detection, contact probability visualization, or comparison of contact decay across conditions or cell types.

When NOT to use

• Input is already a log-binned or smoothed contact frequency table; applying this skill twice will over-smooth and lose resolution.
• Raw contact matrix (cooler file) is available and you need to compute expected frequency de novo; use cooler's built-in expected/observed computation first.
• Analysis requires linear (not logarithmic) binning of distances, e.g., fixed-width bins for regulatory element analysis.

Inputs

• precomputed expected contact frequency table (TSV format with columns: dist_bp, contact_frequency, n_valid)
• cooler-derived Hi-C dataset (optional, if generating expected table de novo)

Outputs

• log-binned and smoothed P(s) table (TSV format with columns: dist_bp, count.avg.smoothed, bin statistics)
• log-space contact probability curve suitable for visualization and downstream analysis

How to apply

Load the expected_cis table (TSV format) into Python and apply the cooltools logbin_expected() function to perform logarithmic binning on distance values and apply smoothing to contact frequencies within each log bin. The function uses a logarithmic scale to group genomic distances such that relative changes in distance are equally represented, which is critical for Hi-C contact decay typically follows a power law. Configure the logarithmic bin spacing (e.g., base 2 or custom log factor) to balance resolution at short distances with coverage at long distances. The smoothing algorithm within logbin_expected() estimates mean smoothed contact frequency for each log bin, reducing noise while preserving the overall decay shape. Output the result as a TSV with columns for binned distance (dist_bp), mean smoothed contact frequency (count.avg.smoothed), and associated bin statistics (e.g., bin count, variance). Validate that the output curve is monotonically decreasing and spans the full input distance range.