cooler-file-loading-and-querying

cooler-file-loading-and-querying

Summary

Loading and querying high-resolution Hi-C contact matrices stored in cooler format, which is a sparse hierarchical data structure designed for efficient storage and random access to genome-wide contact frequency data. This is a foundational operation required before any downstream Hi-C analysis, including compartment detection, insulation scoring, or aggregate pattern extraction.

When to use

Your Hi-C data is stored in cooler format (a binary HDF5-based sparse matrix with associated genomic bins and genomic tracks); you need to programmatically access the contact matrix, bin coordinates, or track data (e.g., eigenvectors, GC content) for further analysis; or you need to validate that a cooler file is well-formed and compatible with downstream tools.

When NOT to use

• Your Hi-C data is in legacy or raw format (e.g., HiCPro .matrix and .bed files, or raw contact lists); convert or normalize to cooler first using cooler's build tools.
• You need to modify or create a new cooler file from scratch; use cooler.create_cooler() or cooler.dump_auto() instead of load-and-query.
• You are working with single-cell or very sparse Hi-C variants where the standard binned cooler model (uniform rectangular grid) is not applicable.

Inputs

• cooler file (.cool or .mcool HDF5 archive)
• file path (string)
• optionally: desired resolution for multi-resolution files

Outputs

• cooler.Cooler object (Python file-like accessor)
• pandas.DataFrame of bin coordinates (chrom, start, end, and any associated track columns)
• sparse contact matrix (scipy.sparse or pydata.sparse format on demand)
• metadata dictionary (genome assembly, bin size, normalization state)

How to apply

Import the cooler library and open a .cool or .mcool file using cooler.Cooler() or cooler.open_auto() to obtain a file-like object. Query the object's attributes to retrieve bin coordinates (cooler_obj.bins()), contact data (cooler_obj.matrix()), or genomic tracks (cooler_obj.bins()[:]) in a lazy, chunk-aware manner. Use the .info dictionary to inspect metadata such as bin size, genome assembly, and normalization status. For multi-resolution .mcool files, first list available resolutions using cooler.fileops.list_coolers() and open the desired resolution. Validate file integrity by checking that bin count matches the expected genome size and that contact matrix shape is consistent (N_bins × N_bins). Leverage cooler's sparse storage model to avoid loading the entire matrix into memory—only fetch regions of interest using slice notation (e.g., cooler_obj.matrix[start:end, start:end]).