genomic-coordinate-conversion

genomic-coordinate-conversion

Summary

Convert genomic coordinates between reference frames or extract region-specific Hi-C data by mapping bin indices to genomic intervals. This skill is essential when working with cooler files where bin-level analyses (e.g., insulation scores, contact frequencies) must be linked back to genomic positions for visualization, validation, or downstream annotation.

When to use

You need to map computed per-bin metrics (insulation scores, boundary calls, contact frequencies) back to genomic coordinates for export to BED/GFF format, cross-reference with external annotations, or validate that computed features fall within expected genomic ranges. Specifically, when cooltools.insulation or similar functions return bin-indexed DataFrames that lack explicit chromosome and position columns.

When NOT to use

• Input metrics are already in genomic coordinate space (chrom, start, end columns present and validated)
• You are working with raw contact matrices and have not yet computed per-bin features
• Coordinate mapping is not required for your downstream analysis (e.g., pure contact frequency correlation studies)

Inputs

• cooler file (.cool or .mcool) containing Hi-C contact matrix and bin table
• pandas DataFrame with per-bin metrics indexed by bin ID (e.g., from cooltools.insulation output)
• cooler bin table (chrom, start, end, weight, etc.)

Outputs

• pandas DataFrame with genomic coordinates (chrom, start, end) and annotated metrics (e.g., insulation_score, is_boundary)
• BED-format file for visualization or downstream analysis
• validated coordinate table with numeric value ranges and schema checks

How to apply

After computing per-bin metrics from a cooler file, extract the bin table (which contains chrom, start, end columns) and merge or join it with your metric output on bin index. The cooler API provides direct access to the bin table via the cooler object's .bins() method, which returns a pandas DataFrame indexed by bin ID. Join this bin table with your insulation scores or boundary annotations by index to recover genomic coordinates. Validate the join by checking that row counts match, that all required columns (region1, region2, chrom, start, end) are present, and that coordinate values are numeric and within expected chromosome boundaries. Export the merged result as a BED-format file for downstream visualization or comparison with known domain structures.