# Cis Contact Frequency Analysis

> Use when when you have loaded a cooler file containing Hi-C contact matrices and need to quantify how contact probability decays with genomic distance within a single chromosome.

- Skill: `holobiomicslab/cis-contact-frequency-analysis` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/cis-contact-frequency-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/cis-contact-frequency-analysis/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/cis-contact-frequency-analysis

---


# cis-contact-frequency-analysis

## Summary

Compute and analyze contact frequency as a function of genomic distance within the same chromosome (cis contacts) using cooler-formatted Hi-C matrices. This is a foundational Hi-C analysis that reveals the prominent distance-dependent decay of chromatin contacts.

## When to use

When you have loaded a cooler file containing Hi-C contact matrices and need to quantify how contact probability decays with genomic distance within a single chromosome. This is typically one of the first analyses performed on Hi-C data to characterize the global organizational properties of chromatin and to validate data quality before proceeding to domain-level or structural feature detection.

## When NOT to use

- Input cooler file is already filtered, normalized, and pre-computed contact frequency tables exist — use those directly instead of recalculating.
- Trans (inter-chromosomal) contact analysis is the primary goal — this skill is specific to cis contacts within a single chromosome.
- You need to detect specific chromatin structures (TADs, loops, compartments) rather than global distance-decay properties — use domain-detection or loop-calling methods instead.

## Inputs

- cooler file (.cool or .mcool) containing Hi-C contact matrix
- target chromosome identifier
- genomic distance binning specification (bin size in base pairs)

## Outputs

- distance-binned contact frequency table (CSV/TSV with genomic separation and contact counts)
- P(s) curve (contact probability vs. genomic distance)
- visualization (log–log plot of contact frequency vs. distance)

## How to apply

Load the cooler file using the cooler library and extract the contact matrix for a target chromosome. Use cooltools functions to compute per-bin sequencing depth (coverage) to normalize for bias, then aggregate contacts across genomic distance bins (e.g., 1 kb, 5 kb, 10 kb bins) to produce a distance-binned contact frequency vector. Optionally compute the P(s) curve (probability of contact as a function of separation distance s) and smooth it to reduce noise. Export the results as a tabular format (CSV/TSV) with bin coordinates and normalized contact counts, and visualize as a log–log plot to assess the power-law decay characteristic of polymer-like chromatin behavior.

## Related tools

- **cooltools** (primary analysis library providing cis contact frequency computation and curve smoothing functions) — https://github.com/open2c/cooltools
- **cooler** (file format and I/O library for loading and querying Hi-C contact matrices) — https://github.com/open2c/cooler
- **Python** (scripting language for data manipulation, normalization, and export)

## Examples

```
import cooler; import cooltools; c = cooler.Cooler('sample.mcool::resolutions/5000'); coverage = cooltools.coverage(c, store_cis_counts=True); print(coverage.head())
```

## Evaluation signals

- Contact frequency decreases monotonically with increasing genomic distance (no unexplained inversions in the P(s) curve).
- Log–log plot of contact frequency vs. distance exhibits expected power-law behavior characteristic of polymer physics (slope between −1 and −2).
- Contact counts at shortest distances (same bin or adjacent bins) are higher than at larger separations by at least 1–2 orders of magnitude.
- Tabular output row counts match the number of distance bins specified and contain no NaN or negative values.
- Bias-normalized contact frequencies are consistent across replicates or technical duplicates (if available).

## Limitations

- Contact frequency calculation assumes uniform sequencing depth across bins; if bins have highly variable coverage, bias normalization (e.g., ICE, KNIGHT, or other balancing methods) must be applied first.
- P(s) smoothing is implemented but the API is not yet stable according to the article, so future changes to smoothing parameters or functionality may occur.
- Results are sensitive to cooler file resolution (bin size); coarser bins lose fine-scale distance detail and may obscure local structural features.
- Cis contacts exclude important trans-chromosomal interactions; a complete chromatin organization picture requires separate trans analysis.

## Evidence

- [readme] how to calculate contact frequency as a function of genomic distance-- the most prominent feature in Hi-C maps: "how to calculate contact frequency as a function of genomic distance-- the most prominent feature in Hi-C maps"
- [other] Call cooltools.coverage() on the loaded cooler object to compute per-bin sequencing depth: "Call cooltools.coverage() on the loaded cooler object to compute per-bin sequencing depth, optionally specifying whether to store total cis counts"
- [discussion] New functionality for smoothing P(s) and derivatives (API is not yet stable): "New functionality for smoothing P(s) and derivatives (API is not yet stable)"
- [intro] The recently-introduced cooler format readily handles storage of high-resolution datasets: "The recently-introduced ***cooler*** format readily handles storage of high-resolution datasets"