Quickstart

This guide provides a rapid introduction to loading and manipulating genomic contact matrices using Gunz-CM.

1. Loading a Contact Matrix

The load_cm_data function is the universal entry point for all supported formats (.cool, .mcool, .hic, .csv).

from gunz_cm.loaders import load_cm_data

# Load a specific genomic region from a cooler file
cm = load_cm_data(
    fpath="data/sample.cool",
    bin_size_bp=10000,        # 10 kb resolution
    region1="chr1",           # genomic region to load
)

print(f"Loaded {cm.chromosome1} at {cm.bin_size_bp} bp resolution.")

2. Accessing the Data

The resulting ContactMatrix object carries the loaded data and metadata. To convert to alternative formats, use the free functions in gunz_cm.structs.cm_views (replaces the legacy ContactMatrix.as_* methods removed in v2.25.0):

from gunz_cm.structs.cm_views import cm_to_coo, cm_to_dataframe

# As a Pandas DataFrame (long-form COO: row_ids, col_ids, counts)
df = cm_to_dataframe(cm)
print(df.head())

# As a SciPy COO sparse matrix
coo = cm_to_coo(cm)

For dense output, cm.toarray() is still available directly on ContactMatrix.

3. High-Performance Filtering

Gunz-CM provides optimized filters for cleaning your data before analysis:

from gunz_cm.preprocs import filter_empty_rowcols

# Remove bins with zero total contacts (unalignable regions)
cm_filtered = filter_empty_rowcols(cm)

print(f"Original shape: {cm.toarray().shape}")
print(f"Filtered shape: {cm_filtered.toarray().shape}")

4. Metadata and Genomic Info

Query file-level information without loading the full matrix into memory:

from gunz_cm.loaders import get_chrom_infos, get_bin_size_bps

# Check available resolutions in an .mcool file
res_list = get_bin_size_bps("data/multires.mcool")
print(f"Available resolutions: {res_list}")

# Get chromosome sizes (returns dict mapping chrom name -> length in bp)
chroms = get_chrom_infos("data/sample.cool")
print(f"Chromosome 1 size: {chroms['chr1']} bp")