gunz_cm package#

Subpackages

Module contents

Gunz-CM: Tools for Hi-C contact matrix processing and 3D reconstruction.

This module provides a unified interface to the most commonly used APIs from the gunz_cm package. For full functionality, import from submodules directly (e.g., from gunz_cm.loaders import load_cm_data).

Commonly Used Exports#

  • ContactMatrix: Data structure for contact matrices

  • load_cm_data: Load contact matrix data from files

  • Balancing, Format, DataStructure: Key enumerations

  • Conversion functions: convert_to_cm_coo, convert_to_gzcm

  • Metrics: comp_hicrep_coo, comp_hic_spector_coo

  • Reconstructions: gen_h3dg_coo, gen_shneigh_coo

Examples

>>> from gunz_cm import load_cm_data, ContactMatrix, Balancing
>>> cm = load_cm_data("data.hic", bin_size_bp=1_000_000, balancing=Balancing.KR)
class gunz_cm.Backend(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: BaseStrEnum

Enumeration for interaction matrix loader backends.

Examples

COOLER = 'cooler'#
HICSTRAW = 'hicstraw'#
HICTK = 'hictk'#
STRAW = 'straw'#
class gunz_cm.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.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.ContactMatrix(chromosome1: str, bin_size_bp: int, loader_func: Callable[[...], Any], *, loader_kwargs: dict[str, Any] | None = None, chromosome2: str | None = None, metadata: dict[str, Any] | None = None, n_pairs: int = 0, coverage_ratio: float = 1.0, effective_resolution_bp: int | None = None, fragment_resolution_bp: int | None = None, protocol_type: str | None = None, resolution: int | None = None)[source]#

Bases: object

A data container for a contact matrix and its associated metadata.

This class acts as a simple, data-oriented container to group a contact matrix (as a pandas DataFrame or a SciPy sparse matrix) with important metadata like its genomic coordinates and resolution. It supports lazy loading of data via a loader function.

chromosome1#

The name of the first chromosome.

Type:

str

bin_size_bp#

The bin size (resolution) of the contact matrix in base pairs.

Type:

int

loader_func#

A function or callable that returns the raw data when called.

Type:

callable

loader_kwargs#

Keyword arguments to pass to the loader function.

Type:

dict

chromosome2#

The name of the second chromosome, if different from the first (for inter-chromosomal matrices). Defaults to chromosome1.

Type:

str, optional

metadata#

A dictionary to hold any other relevant metadata.

Type:

dict

n_pairs#

Total number of valid (filtered) read pairs used to build the matrix. Default is 0.

Type:

int

coverage_ratio#

Ratio of observed coverage versus canonical depth expectation. Default is 1.0.

Type:

float

effective_resolution_bp#

The effective (usable) resolution computed from the data. Computed lazily via compute_effective_resolution(). Default is None.

Type:

int | None

fragment_resolution_bp#

Physical limit imposed by fragment size (e.g., from restriction enzyme). Optional; None if unknown or not applicable.

Type:

int | None

protocol_type#

Experimental protocol type (e.g., “Hi-C”, “Micro-C”, “HiChIP”). Optional; None if unknown.

Type:

str | None

Examples

>>> from gunz_cm.matrix import ContactMatrix
>>> import numpy as np
>>> def dummy_loader(n): return np.eye(n)
>>> cm = ContactMatrix("chr1", 10000, loader_func=dummy_loader, loader_kwargs={"n": 5})
>>> print(cm.data.shape)
(5, 5)
bin_size_bp: int#
chromosome1: str#
chromosome2: str | None = None#
coverage_ratio: float = 1.0#
property data: Any#

The raw contact matrix data, loaded lazily.

Returns:

The raw data returned by the loader function (usually a DataFrame or Sparse Matrix).

Return type:

object

effective_resolution_bp: int | None = None#
fragment_resolution_bp: int | None = None#
loader_func: Callable[[...], Any] = Field(name=None,type=None,default=<dataclasses._MISSING_TYPE object>,default_factory=<dataclasses._MISSING_TYPE object>,init=True,repr=False,hash=None,compare=True,metadata=mappingproxy({}),kw_only=<dataclasses._MISSING_TYPE object>,_field_type=None)#
loader_kwargs: dict[str, Any] = Field(name=None,type=None,default=<dataclasses._MISSING_TYPE object>,default_factory=<class 'dict'>,init=True,repr=False,hash=None,compare=True,metadata=mappingproxy({}),kw_only=<dataclasses._MISSING_TYPE object>,_field_type=None)#
metadata: dict[str, Any] = Field(name=None,type=None,default=<dataclasses._MISSING_TYPE object>,default_factory=<class 'dict'>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=<dataclasses._MISSING_TYPE object>,_field_type=None)#
n_pairs: int = 0#
protocol_type: str | None = None#
class gunz_cm.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.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.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.GZCMReader(fpath: str | pathlib.Path)[source]#

Bases: object

Reader for GZCM container format.

Supports reading GZCM v1, v2, and v3 files.

Parameters:

fpath (str | pathlib.Path) – Input file path.

Examples

>>> reader = GZCMReader("data.gzcm")
>>> version = reader.version
>>> metadata = reader.get_metadata()
>>> matrix = reader.get_array("matrix")
decode_compressed_tile(payload: bytes) → ndarray[source]#

Decode a compressed tile using CMC.

Parameters:

payload (bytes) – Encoded compressed data.

Returns:

Decoded contact matrix tile.

Return type:

np.ndarray

get_array(name: str, mode: str = 'r') → memmap[source]#

Get a memory-mapped array from the container.

Parameters:

  • name (str) – Array name.

  • mode (str, default="r") – Memory-map mode (‘r’ for read-only, ‘r+’ for read-write).

Returns:

Memory-mapped array.

Return type:

np.memmap

get_compressed_tile(name: str, index: int = 0, return_shape: bool = False) → bytes | tuple[bytes, tuple[int, int]][source]#

Read a compressed tile without decoding.

v3 GZCM tiles carry an 8-byte (rows, cols) int32 header that the zstd/bsc decoders consume. Pass return_shape=True to also recover the tile shape from that header alongside the raw payload bytes.

Parameters:

  • name (str) – Tile name (e.g., “tile_0”).

  • index (int, default=0) – Tile index for tile streams.

  • return_shape (bool, default=False) – When True, return (payload, (rows, cols)). When False (default), return only the raw payload bytes for backward compatibility with existing callers.

Returns:

Encoded compressed data; optionally paired with the (rows, cols) shape decoded from the 8-byte header.

Return type:

bytes, or tuple of (bytes, tuple of (int, int))

Raises:

ValueError – If the payload is shorter than 8 bytes when return_shape is requested, or if the CRC32 checksum does not match.

get_metadata() → dict[source]#

Get user-defined metadata from header.

Returns:

Metadata dictionary.

Return type:

dict

keys() → list[str][source]#

Get names of all arrays in the container.

Returns:

Array names.

Return type:

list[str]

class gunz_cm.GZCMWriter(fpath: str | pathlib.Path, overwrite: bool = False, version: int = 1)[source]#

Bases: object

Writer for GZCM container format.

Supports writing GZCM v1, v2 (dense arrays) and GZCM v3 (compressed tiles).

Parameters:

  • fpath (str | pathlib.Path) – Output file path.

  • overwrite (bool, default=False) – Overwrite existing file.

  • version (int, default=1) – GZCM format version. Use 3 for compressed tiles.

Examples

>>> writer = GZCMWriter("output.gzcm", overwrite=True)
>>> writer.add_array("matrix", data)
>>> writer.write()
add_array(name: str, data: ndarray, dtype: str | numpy.dtype | None = None) → None[source]#

Register a complete array to be written.

Data is not written until write() is called.

Parameters:

  • name (str) – Array name.

  • data (np.ndarray) – Array data to write.

  • dtype (str | np.dtype | None, optional) – Override dtype for storage.

add_compressed_tile(name: str, payload: bytes, uncompressed_size: int, checksum: int | None = None) → None[source]#

Add a pre-encoded compressed tile.

Parameters:

  • name (str) – Tile name (e.g., “tile_0”).

  • payload (bytes) – Encoded compressed data.

  • uncompressed_size (int) – Original uncompressed size in bytes.

  • checksum (int | None, optional) – CRC32 checksum for integrity verification.

get_array_writable(name: str) → memmap[source]#

Returns a writable memmap for a specific array in the container.

Parameters:

name (str) – Array name.

Returns:

Writable memory-mapped array.

Return type:

np.memmap

init_compressed_tile_stream(name: str, n_tiles: int, max_tile_size: int) → None[source]#

Reserve space for streaming tile writes.

Parameters:

  • name (str) – Base name for tiles.

  • n_tiles (int) – Number of tiles to reserve.

  • max_tile_size (int) – Maximum tile size in bytes.

init_streaming_array(name: str, shape: tuple[int, ...], dtype: str | numpy.dtype) → None[source]#

Reserve space for an array to be written incrementally.

Parameters:

  • name (str) – Array name.

  • shape (tuple[int, ...]) – Array shape.

  • dtype (str | np.dtype) – Data type.

set_metadata(meta: dict) → None[source]#

Set user-defined metadata.

Parameters:

meta (dict) – Metadata dictionary to store in header.

write() → None[source]#

Finalize the header and layout, and open the file for writing.

class gunz_cm.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.Pipeline(steps: list[tuple[str, Callable[[Any], Any]]])[source]#

Bases: object

A simple data-oriented pipeline that chains callable steps.

Examples

run(initial_data: Any = None) → Any[source]#

Executes the pipeline sequentially.

initial_dataAny, optional

The initial data to pass into the first pipeline step. Defaults to None.

Any

The output data from the final pipeline step.

Examples

gunz_cm.comp_hic_spector_coo(coo_cm1: coo_matrix, coo_cm2: coo_matrix, with_loop: bool = True, num_eig_vecs: int = 20, ipr_cutoff: float = 5, op: str = 'union', single_graph_laplacian: bool = False, intersect_valid_eigvecs: bool = False, verbose: bool = False) → float[source]#

Calculate the HiCSpector reproducibility score between two sparse matrices.

Parameters:

  • coo_cm1 (sp.coo_matrix) – First contact matrix in COO format.

  • coo_cm2 (sp.coo_matrix) – Second contact matrix in COO format.

  • with_loop (bool, optional) – If True, include loops in the calculation. By default True.

  • num_eig_vecs (int, optional) – Number of eigenvectors to consider. By default 20.

  • ipr_cutoff (float, optional) – Cutoff value for the IPR filter. If None, no filter is applied. By default 5.

  • op (str, optional) – The operation for filtering common rows/columns (‘union’ or ‘intersection’). By default “union”.

  • single_graph_laplacian (bool, optional) – Flag to treat the matrix as a single graph. By default False.

  • intersect_valid_eigvecs (bool, optional) – If True, intersect valid eigenvector IDs from both matrices based on the IPR cutoff. By default False.

  • verbose (bool, optional) – Enable verbose logging output. By default False.

Returns:

The HiCSpector reproducibility score.

Return type:

float

Notes

This function computes the HiCSpector metric using spectral decomposition. It assumes input matrices are in COO Upper Triangle format.

Examples

gunz_cm.comp_hicrep_coo(cm1_coo: coo_matrix, cm2_coo: coo_matrix, max_k: int = None, remove_main_diag: bool = True, downsample: bool = False, half_win_size: int | None = None, ena_common_region: bool = True, ena_reshaping: bool = True) → ndarray[source]#

Compute the HiCRep score for two contact matrices.

This is the main entry point for calculating the HiCRep score between two sparse contact matrices.

Parameters:

  • cm1_coo (sp.coo_matrix) – First contact matrix in COO format.

  • cm2_coo (sp.coo_matrix) – Second contact matrix in COO format.

  • max_k (int, optional) – The maximum genomic distance (in bins) to consider.

  • remove_main_diag (bool, optional) – Whether to exclude the main diagonal, by default True.

  • downsample (bool, optional) – Whether to down-sample the matrices, by default False.

  • half_win_size (int, optional) – The half-size of the smoothing window. If None, no smoothing.

  • ena_common_region (bool, optional) – Whether to filter for common non-empty rows/columns, by default True.

  • ena_reshaping (bool, optional) – Whether to enforce a square shape on matrices, by default True.

Returns:

The final HiCRep SCC score.

Return type:

float

Raises:

  • TypeError – If inputs are not COO matrices.

  • ValueError – If inputs are empty, non-square, or have different shapes.

Notes

Both input matrices must be in scipy.sparse.coo_matrix format.

Examples

gunz_cm.comp_superrec_obj_perf(region1: str, bin_size_bp: int, balancing: str, input_fpath: str, points_fpath: str, region2: str | None = None) → dict[source]#

Compute the performance metrics (Spearman and Pearson correlation) for Euclidean distances predicted by SuperRec.

Notes

This function loads the count data for a specified region and bin size, computes the Euclidean distance matrix from the points file, and then calculates the Spearman and Pearson correlation coefficients between the counts and the distances. The function assumes that the points file contains valid points and that the row and column IDs are mapped to these valid points.

Parameters:

  • region1 (str) – The first region for which to compute the performance metrics.

  • bin_size_bp (int) – The bin size (in base pairs).

  • balancing (str) – The balancing method to use when loading the data.

  • input_fpath (str) – The file path to the input data.

  • points_fpath (str) – The file path to the points data.

  • region2 (Optional[str], optional) – The second region for which to compute the performance metrics, by default None.

Returns:

A dictionary containing the region, Spearman correlation coefficient, Pearson correlation coefficient, and data ratio.

Return type:

dict

gunz_cm.convert_all_intra_to_cm_coo(input_fpath: Path, output_dpath: Path, bin_size_bp: int, balancing: gunz_cm.consts.Balancing | None, on_conflict: Literal['error', 'overwrite', 'skip'] = 'skip', res_to_one: bool = False, to_mcoo: bool = False, gen_pseudo_weights: bool = False, output_delimiter: str = '\t', columns_order: list[str] | None = None, n_jobs: int = 1) → None[source]#

Converts all intra-chromosomal matrices in a file to COO format.

This function iterates through all chromosomes found in the input file, extracts the intra-chromosomal contact matrix for each, and saves it as a separate COO file in the specified output directory.

Parameters:

  • input_fpath (pathlib.Path) – Path to the input contact matrix file.

  • output_dpath (pathlib.Path) – Directory where the output COO files will be saved.

  • bin_size_bp (int) – The bin size (in bp) of the contact matrices.

  • balancing (Balancing, optional) – The balancing method to apply.

  • overwrite (bool, optional) – If True, overwrite existing output files. Defaults to False.

  • res_to_one (bool, optional) – If True, normalize bin coordinates. Defaults to False.

  • to_mcoo (bool, optional) – If True, convert to modified COO format. Defaults to False.

  • gen_pseudo_weights (bool, optional) – If True, generate corresponding .weights files. Defaults to False.

  • output_delimiter (str, optional) – Delimiter for the output files. Defaults to a tab.

  • columns_order (list[str], optional) – The specific order of columns for the output files. Defaults to None.

  • n_jobs (int, optional) – The number of jobs to run in parallel. Defaults to 1.

Examples

>>> from gunz_cm.converters.coo import convert_all_intra_to_cm_coo
>>> convert_all_intra_to_cm_coo("sample.hic", "output_dir", bin_size_bp=10000)
gunz_cm.convert_to_cm_coo(input_fpath: Path, output_fpath: Path, region1: str | None, bin_size_bp: int, balancing: gunz_cm.consts.Balancing | None, region2: str | None = None, on_conflict: Literal['error', 'overwrite', 'skip'] = 'error', res_to_one: bool = False, to_mcoo: bool = False, gen_pseudo_weights: bool = False, output_delimiter: str = '\t', columns_order: list[str] | None = None) → None[source]#

Converts contact matrix data to a COO format and saves it to a file.

This function loads data using the main loader, optionally creating a “modified COO” (mCOO) format with both raw and normalized counts, and saves the result to a specified text file.

Parameters:

  • input_fpath (pathlib.Path) – Path to the input contact matrix file (e.g., .hic, .cool).

  • output_fpath (pathlib.Path) – Path where the output COO text file will be saved.

  • region1 (str | None) – The identifier for the first region/chromosome. If None, loads all chromosomes (format-dependent; may not be supported for all formats).

  • bin_size_bp (int) – The bin size (in bp) for binning the contact matrix.

  • balancing (Balancing, optional) – The balancing method to apply. Required if to_mcoo is True.

  • region2 (str, optional) – The identifier for the second region, if applicable. Defaults to None.

  • overwrite (bool, optional) – If True, overwrite the output file if it exists. Defaults to False.

  • exist_ok (bool, optional) – If True, do nothing if the output file already exists. Defaults to False.

  • res_to_one (bool, optional) – If True, normalize bin coordinates by the bin size. Defaults to False.

  • to_mcoo (bool, optional) – If True, create a modified COO with raw and normalized counts. Defaults to False.

  • gen_pseudo_weights (bool, optional) – If True, generate a corresponding .weights file. Defaults to False.

  • output_delimiter (str, optional) – The delimiter for the output text file. Defaults to a tab.

  • columns_order (list[str], optional) – The specific order of columns for the output file. Defaults to None.

Raises:

  • FileExistsError – If the output file exists and neither overwrite nor exist_ok is True.

  • ConverterError – If to_mcoo is True but balancing is not provided.

Examples

>>> from gunz_cm.converters.coo import convert_to_cm_coo
>>> convert_to_cm_coo("sample.cool", "output.csv", bin_size_bp=10000)
gunz_cm.convert_to_gzcm(fpath: Path, output_fpath: Path, region1: str | None, bin_size_bp: int, balancing: gunz_cm.consts.Balancing | None = None, backend: Backend = Backend.HICTK, dtype: str = 'float32', overwrite: bool = False, version: int = 1, block_size: int = 1024, tile_size: int = 512, compression: str | None = None, layout: str | None = None, region_layouts: dict[str, str] | None = None, adaptive_codec: bool = False, codec_candidates: tuple[str, ...] | None = None, chunk_size: int = 10000000) → None[source]#

Converts a Hi-C file to a .gzcm container with matrix and weights.

Supports GZCM v1 (dense), v2 (tiled, csr, block_sparse), and v3 (compressed tiles). For v3, compression codecs are:

(*) cmc_zstd is the recommended default: best balance of compression ratio and convert speed. Real HiC chr1 @ 50kb bin_size_bp benchmarked.

Parameters:

  • fpath (pathlib.Path) – Input Hi-C file path.

  • output_fpath (pathlib.Path) – Output .gzcm file path.

  • region1 (str) – Genomic region (e.g., “chr1”).

  • bin_size_bp (int) – Hi-C bin size in bp.

  • balancing (Balancing, optional) – Balancing method.

  • backend (Backend, default=HICTK) – Backend to use for loading.

  • dtype (str, default="float32") – Data type for matrix storage.

  • overwrite (bool, default=False) – Overwrite existing file.

  • version (int, default=1) – GZCM version: 1 (dense), 2 (tiled/sparse), 3 (compressed tiles).

  • block_size (int, default=1024) – Block size for v2 tiled layouts.

  • tile_size (int, default=512) – Tile size for v3 compression.

  • compression (str, optional) – Compression codec for v3: “cmc”, “cmc_zstd” (recommended default), “zstd”, or “bsc”.

Examples

gunz_cm.convert_to_memmap(data: pathlib.Path | pandas.core.frame.DataFrame | tuple[Union[numpy._typing._array_like._Buffer, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], complex, bytes, str, numpy._typing._nested_sequence._NestedSequence[complex | bytes | str]], ...], output_fpath: Path, **kwargs) → None[source]#
gunz_cm.convert_to_memmap(data: DataFrame, output_fpath: Path, **kwargs) → None
gunz_cm.convert_to_memmap(data: tuple[Union[numpy._typing._array_like._Buffer, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], complex, bytes, str, numpy._typing._nested_sequence._NestedSequence[complex | bytes | str]], Union[numpy._typing._array_like._Buffer, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], complex, bytes, str, numpy._typing._nested_sequence._NestedSequence[complex | bytes | str]], Union[numpy._typing._array_like._Buffer, numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], complex, bytes, str, numpy._typing._nested_sequence._NestedSequence[complex | bytes | str]]], output_fpath: Path, output_full_matrix: bool = True, dtype: Optional[Union[type[Any], dtype[Any], _SupportsDType[dtype[Any]], tuple[Any, Any], list[Any], _DTypeDict, str]] = None, shape: tuple[int, int] | None = None, check_output: bool = True, overwrite: bool = False, metadata: dict[str, Any] | None = None, **kwargs) → None
gunz_cm.convert_to_memmap(data: Path, output_fpath: Path, region1: str, bin_size_bp: int, balancing: gunz_cm.consts.Balancing | None, **kwargs) → None

Converts contact matrix data to a NumPy memory-mapped file (memmap).

This is a polymorphic function that dispatches to the appropriate implementation based on the type of the data argument.

datapathlib.Path or pd.DataFrame or tuple

The input data to convert. Can be: - A path to a standard contact matrix file (.hic, .cool, etc.). - A pandas DataFrame in COO format. - A tuple of (rows, cols, values) arrays.

output_fpathpathlib.Path

The base path for the output memmap file.

**kwargs :

Additional arguments specific to the conversion type, such as bin_size_bp, balancing, output_full_matrix, etc.

Examples

gunz_cm.create_pipeline(config: list[dict[str, Any]]) → Pipeline[source]#

Factory function to create a Pipeline from a configuration structure.

configlist[dict[str, Any]]

A list of configuration dictionaries, each specifying a pipeline step. Expected keys are ‘name’ (str), ‘target’ (str), and optionally ‘kwargs’ (dict).

Pipeline

The constructed pipeline.

ValueError

If a step is missing a ‘target’ key.

Examples

gunz_cm.filter_by_raw_counts(matrix: pandas.core.frame.DataFrame | scipy.sparse._coo.coo_matrix | scipy.sparse._csr.csr_matrix | numpy.ndarray, min_val: int | None = None, max_val: int | None = None, raw_counts_colname: str = 'raw_counts') → pandas.core.frame.DataFrame | scipy.sparse._coo.coo_matrix | scipy.sparse._csr.csr_matrix | numpy.ndarray[source]#
gunz_cm.filter_by_raw_counts(matrix: DataFrame, min_val: int | None, max_val: int | None, raw_counts_colname: str) → DataFrame
gunz_cm.filter_by_raw_counts(matrix: coo_matrix, min_val: int | None, max_val: int | None, raw_counts_colname: str) → coo_matrix
gunz_cm.filter_by_raw_counts(matrix: csr_matrix, min_val: int | None, max_val: int | None, raw_counts_colname: str) → csr_matrix
gunz_cm.filter_by_raw_counts(matrix: ndarray, min_val: int | None, max_val: int | None, raw_counts_colname: str) → ndarray

Filter entries of a matrix based on raw interaction counts.

This function uses Pydantic to validate inputs and single dispatch to route to the correct implementation based on the input data type.

Parameters:

  • matrix (pd.DataFrame, sp.coo_matrix, sp.csr_matrix, or np.ndarray) – The input data. For NumPy arrays, this filters by setting values outside the range to 0. For sparse matrices and DataFrames, it removes the entries.

  • min_val (int, optional) – The minimum raw count value to include (inclusive). Defaults to None.

  • max_val (int, optional) – The maximum raw count value to include (inclusive). Defaults to None.

  • raw_counts_colname (str, optional) – The name of the column containing raw counts. This is only used if the input is a pandas DataFrame. Defaults to DataFrameSpecs.RAW_COUNTS.

Returns:

A new data object of the same type as the input, containing only the filtered entries.

Return type:

pd.DataFrame, sp.coo_matrix, sp.csr_matrix, or np.ndarray

Raises:

  • pydantic.ValidationError – If any argument’s type is incorrect.

  • ValueError – If min_val > max_val, or if raw_counts_colname is not found.

  • TypeError – If the target column in a DataFrame is not numeric.

gunz_cm.gen_h3dg_coo(chr_region: str, bin_size_bp: int, balancing: str, input_fpath: str, output_fpath: str, on_conflict: Literal['error', 'overwrite', 'skip'] = 'error') → None[source]#

Generate COO format files for H3DG from a contact matrix file.

Notes

  • This function generates both raw and normalized COO files.

  • The raw counts file is saved with the suffix .raw.

  • The normalized counts file is saved with the suffix specified by the balancing parameter.

Parameters:

  • chr_region (str) – The chromosome region to process.

  • bin_size_bp (int) – The bin size (in base pairs).

  • balancing (str) – The balancing method to use for normalization.

  • input_fpath (str) – The file path to the input contact matrix data.

  • output_fpath (str) – The base file path for the output COO files.

  • on_conflict (ConflictPolicy, optional) – What to do when the output file already exists. One of "error" (raise), "overwrite" (replace), "skip" (return without writing). Defaults to "error".

Return type:

None

Examples

pass

gunz_cm.gen_shneigh_coo(chr_region: str, bin_size_bp: int, balancing: str, input_fpath: str, output_fpath: str, on_conflict: Literal['error', 'overwrite', 'skip'] = 'error')[source]#

Generate a COO format file for SHNeigh.

Notes

This function converts the input data to a COO format file suitable for SHNeigh.

Parameters:

  • chr_region (str) – The chromosome region.

  • bin_size_bp (int) – The bin size (in base pairs).

  • balancing (str) – The balancing method.

  • input_fpath (str) – The path to the input contact matrix.

  • output_fpath (str) – The path to the output COO file.

  • on_conflict (ConflictPolicy, optional) – What to do when output_fpath already exists. One of "error" (raise), "overwrite" (replace), "skip" (return without writing). Defaults to "error".

Return type:

None

gunz_cm.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.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.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.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.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.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.to_coo_matrix(matrix: pandas.core.frame.DataFrame | tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray], is_triu_sym: bool = True, row_ids_colname: str = 'row_ids', col_ids_colname: str = 'col_ids', vals_colname: str = 'counts', shape: tuple[int, int] | None = None) → coo_matrix[source]#
gunz_cm.to_coo_matrix(matrix: DataFrame, is_triu_sym: bool, row_ids_colname: str, col_ids_colname: str, vals_colname: str, shape: tuple[int, int] | None = None) → coo_matrix
gunz_cm.to_coo_matrix(matrix: tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray], is_triu_sym: bool, shape: tuple[int, int] | None = None, **kwargs) → coo_matrix

Convert various data types to a SciPy COO sparse matrix.

Parameters:

  • matrix (pd.DataFrame or tuple) – Input data, which can be: - A pandas DataFrame with coordinate and value columns. - A tuple of (rows, columns, values) NumPy arrays.

  • is_triu_sym (bool, optional) – If True, assumes the matrix is symmetric and stored in upper-triangular format, used for inferring the full matrix shape. Defaults to True.

  • row_ids_colname (str, optional) – Column name for row IDs (for DataFrame input).

  • col_ids_colname (str, optional) – Column name for column IDs (for DataFrame input).

  • vals_colname (str, optional) – Column name for values (for DataFrame input).

  • shape (tuple of ints, optional) – The shape of the matrix. If None, it is inferred from the data.

Returns:

The COO format sparse matrix representation of the data.

Return type:

sp.coo_matrix

gunz_cm.to_dataframe(matrix: coo_matrix, row_ids_colname: str = 'row_ids', col_ids_colname: str = 'col_ids', vals_colname: str = 'counts') → DataFrame[source]#
gunz_cm.to_dataframe(matrix: coo_matrix, row_ids_colname: str, col_ids_colname: str, vals_colname: str) → DataFrame

Convert a sparse matrix to a pandas DataFrame.

Parameters:

  • matrix (sp.coo_matrix) – Input COO format sparse matrix.

  • row_ids_colname (str, optional) – The desired column name for row IDs in the output DataFrame.

  • col_ids_colname (str, optional) – The desired column name for column IDs in the output DataFrame.

  • vals_colname (str, optional) – The desired column name for values in the output DataFrame.

Returns:

A DataFrame with columns for row IDs, column IDs, and values.

Return type:

pd.DataFrame