gunz_cm.loaders#

Module contents#

This module provides a unified interface to parse various contact matrix file formats and load them into memory.

It acts as a facade, dispatching calls to the appropriate format-specific loader (e.g., for .hic, .cool, .csv) while providing a consistent API to the user.

Functions:

load_cm_data: Load a contact matrix from a file into memory. get_chrom_infos: Query chromosome names and lengths from a file. get_bin_size_bps: List the available bin sizes (in bp) in a file. get_resolutions: Deprecated alias for get_bin_size_bps (will be

removed in v2.13.0).

get_balancing: List available balancing methods for a specific region.

Note: The resolution parameter was removed in v2.11.0. Use bin_size_bp instead (matrix geometry axis). The get_resolutions function was renamed to get_bin_size_bps in v2.11.2 for consistency with the parameter naming.

Examples

class gunz_cm.loaders.Balancing(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: BaseStrEnum

Enumeration for matrix balancing (normalization) methods.

Examples

KR = 'KR'#

NONE = 'NONE'#

VC = 'VC'#

VC_SQRT = 'VC_SQRT'#

class gunz_cm.loaders.BpFrag(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: BaseStrEnum

Enumeration for binning units (Base Pairs vs. Fragments).

Examples

BP = 'BP'#

FRAG = 'FRAG'#

class gunz_cm.loaders.Counts(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: BaseStrEnum

Enumeration for different types of interaction counts.

Examples

EXPECTED = 'expected'#

OBSERVED = 'observed'#

OE = 'oe'#

class gunz_cm.loaders.DataStructure(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: BaseStrEnum

Enumeration for in-memory data representations.

Examples

COO = 'coo'#

DF = 'df'#

RC = 'rc'#

RCV = 'rcv'#

class gunz_cm.loaders.Format(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: BaseStrEnum

Enumeration for supported file formats.

Uses BaseStrEnum for case-insensitivity and aliases.

Examples

COO = 'coo'#

COOLER = 'cooler'#

CSV = 'csv'#

GINTERACTIONS = 'ginteractions'#

HIC = 'hic'#

MCOO = 'mcoo'#

MCSV = 'mcsv'#

MEMMAP = 'npdat'#

NPY = 'npy'#

PICKLE = 'pickle'#

TSV = 'tsv'#

class gunz_cm.loaders.GenomeBuild(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: BaseStrEnum

Enumeration for standard genome builds.

Examples

HG19 = 'hg19'#

HG38 = 'hg38'#

MM10 = 'mm10'#

MM9 = 'mm9'#

class gunz_cm.loaders.Region(chromosome: int | str, region: tuple[int, int] | gunz_cm.loaders.utils.Constant)[source]#

Bases: object

Represent a range of loci and interface with the textual UCSC style in the form ‘chr22:1,000,000-1,500,000’ Use static method Region.from_string to parse USCS string. Converting back to string will canonicalize

chromosome#

1-22 or string X/Y/M (use chromname() to get chrN string)

Type:: int or str

region#

For ‘chr1:100-500’, region.start == 100 and region.end == 500

Type:: ClosedInterval or the constant Region.ALL_LOCI

Examples

Parsing tries to be more lenient than the canonical form requires.

>>> str(Region.from_string('1:1,000-1,500')) == 'chr1:1000-1500'
True

>>> str(Region.from_string('chry')) == 'chrY'
True

ALL_LOCI = <gunz_cm.loaders.utils.Constant object>#

chromname() → str[source]#

Function chromname.

Returns:: The formatted chromosome string.
Return type:: str

Examples

Notes

static from_string(region: str) → Region[source]#

Function from_string.

Parameters:: region (str) – The string to parse.
Returns:: The parsed Region object.
Return type:: Region

Examples

Notes

is_full_chrom() → bool[source]#

This region describes the full chromosome, so region is 0:N

Returns:: True if region is the full chromosome, False otherwise.
Return type:: bool

Examples

gunz_cm.loaders.gen_memmap_fpaths(base_fpath: str | pathlib.Path) → tuple[pathlib.Path, pathlib.Path][source]#

Generates paths for the binary data and JSON metadata files.

Parameters:: base_fpath (t.Union[str, pathlib.Path]) – The base path for the memmap, without an extension.
Returns:: A tuple containing the path to the binary (.npdat) file and the metadata (.json) file.
Return type:: tuple[pathlib.Path, pathlib.Path]

Examples

gunz_cm.loaders.get_balancing(fpath: str, bin_size_bp: int, chrom: str) → list[str][source]#

Gets available balancing methods for a region in a .hic or .cool file.

Parameters:

fpath (str) – The path to the contact matrix file.
bin_size_bp (int) – The bin size in base pairs (matrix geometry axis).
chrom (str) – The chromosome of interest (e.g., ‘chr1’).

Returns:

A list of available balancing methods (e.g., [‘KR’, ‘VC_SQRT’]).

Return type:

list[str]

Examples

gunz_cm.loaders.get_bin_size_bps(fpath: str) → list[int][source]#

Gets the available bin sizes (in base pairs) in a contact matrix file.

Note: returns matrix geometry (bin size in bp), not data-quality metrics such as read depth or coverage.

Parameters:: fpath (str) – The path to the contact matrix file.
Returns:: A list of available bin sizes in base pairs.
Return type:: list[int]

Examples

gunz_cm.loaders.get_bins(fpath: str | pathlib.Path, bin_size_bp: int) → DataFrame[source]#

Gets the binnified index from a .hic or .cool file.

Parameters:

fpath (t.Union[str, pathlib.Path]) – The path to the contact matrix file.
bin_size_bp (int) – The bin size in base pairs (matrix geometry axis).

Returns:

A DataFrame with columns: ‘chrom’, ‘start’, ‘end’.

Return type:

pd.DataFrame

Examples

gunz_cm.loaders.get_chrom_infos(fpath: str) → dict[str, int][source]#

Queries chromosome names and lengths from a .hic or .cool file.

Parameters:: fpath (str) – The path to the contact matrix file.
Returns:: A mapping of chromosome names to their lengths.
Return type:: dict[str, int]

Examples

gunz_cm.loaders.get_resolutions(fpath: str) → list[int][source]#: Deprecated alias for get_bin_size_bps().

Deprecated since version 2.11.2: Use get_bin_size_bps() instead. Will be removed in v2.13.0.

gunz_cm.loaders.is_file_standard_cm(fpath: str) → bool[source]#

Checks if the file is a standard contact matrix file format.

Parameters:: fpath (str) – The path to the file.
Returns:: True if standard contact matrix format, False otherwise.
Return type:: bool

Examples

gunz_cm.loaders.is_memmap_exists(base_fpath: str | pathlib.Path) → bool[source]#

Checks if both the binary and metadata files for a memmap exist.

base_fpatht.Union[str, pathlib.Path]
The base path for the memmap to check.

bool
True if both the .npdat and .json files exist, False otherwise.

Examples

gunz_cm.loaders.load_cm_data(fpath: Path, bin_size_bp: int | None = None, region1: str | None = None, region2: str | None = None, balancing: gunz_cm.consts.Balancing | list[gunz_cm.consts.Balancing] | None = None, output_format: DataStructure = DataStructure.DF, fformat: gunz_cm.consts.Format | None = None, backend: gunz_cm.consts.Backend | None = None, return_raw_counts: bool = False, **kwargs) → pandas.core.frame.DataFrame | tuple[numpy.ndarray, ...] | numpy.ndarray | tuple[Any, ...][source]#

Loads contact matrix data from various file formats.

This function acts as a dispatcher, routing the call to the appropriate format-specific loader based on the file’s extension or the fformat argument.

Parameters:

fpath (pathlib.Path) – Path to the contact matrix file.
bin_size_bp (int) – Bin size in base pairs (matrix geometry axis).
region1 (str, optional) – First genomic region (e.g., ‘chr1’). Defaults to None.
region2 (str, optional) – Second genomic region. If None, loads intra-chromosomal data for region1. Defaults to None.
balancing (Balancing | list[Balancing], optional) – Balancing (normalization) method(s) to apply. Defaults to None.
out_datastructure (DataStructure, optional) – Desired output format (‘df’ or ‘coo’). Defaults to DataStructure.DF.
fformat (Format, optional) – Explicitly specify file format, otherwise inferred from extension. Defaults to None.
backend (Backend, optional) – Select the underlying backend library for loading. For COOLER: ‘cooler’, ‘hictk’. For HIC: ‘hicstraw’, ‘hictk’, ‘straw’. Defaults to None (uses standard backend for format).
return_raw_counts (bool, optional) – If True, return raw counts alongside the primary (balanced) counts. Defaults to False.
**kwargs – Additional keyword arguments passed to the specific loader, (e.g., encoding for CSV files).

Returns:

The loaded contact matrix data in the specified output format.

Return type:

pd.DataFrame | tuple[np.ndarray, …] | np.ndarray | tuple[t.Any, …]

Raises:

FormatError – If the file format is not recognized or supported, or if an invalid backend is selected for the format.
NotImplementedError – If return_raw_counts is True for unsupported formats.

Examples

gunz_cm.loaders.load_memmap(base_fpath: str | pathlib.Path, mode: str = 'r') → ContactMatrix[source]#

Loads a NumPy array from a memory-mapped file lazily.

Parameters:

base_fpath (t.Union[str, pathlib.Path]) – The base path to the memmap files.
mode (str, optional) – The file open mode for the memmap. Defaults to DEFAULT_MODE.

Returns:

A ContactMatrix object wrapping the loaded data.

Return type:

ContactMatrix

Examples