gunz_cm.compressions.zstd_decoder#

Module contents#

Zstd decoder wrapper for GZCM v3 compression.

Uses zlib as fallback since zstandard may not be installed.

Examples

class gunz_cm.compressions.zstd_decoder.ZstdDecoder(tile_size: int = 256, resolution: int = 50000, dtype: ~numpy.dtype = <class 'numpy.uint32'>, use_zstd: bool = True)[source]#

Bases: object

Zstd decoder for contact matrix tiles.

Parameters:

  • tile_size (int, default=256) – Tile size for block processing.

  • resolution (int, default=50000) – Hi-C resolution in bp.

  • dtype (np.dtype, default=np.uint32) – Data type for decoded tiles.

  • use_zstd (bool, default=True) – Use zstd if available, otherwise zlib fallback.

Examples

decode_tile(payload: bytes, shape: tuple[int, int] | None = None) → ndarray[source]#

Decode a single compressed tile.

Parameters:

  • payload (bytes) – Compressed bitstream. When shape is provided (v3 GZCM path), the first 8 bytes encode (rows, cols) as np.int32 and are stripped before decompression. When shape is None the payload is treated as raw compressed bytes (legacy / codec tests).

  • shape (tuple of (int, int), optional) – Actual tile shape (rows, cols). Required for edge tiles where rows != self.tile_size or cols != self.tile_size. If None, falls back to (self.tile_size, self.tile_size) and assumes no 8-byte header is present.

Returns:

Decoded contact matrix tile with the requested shape.

Return type:

np.ndarray

Examples

decode_tiles(payloads: list[bytes], shapes: list[tuple[int, int]] | None = None) → ndarray[source]#

Decode multiple tiles into a 4D array.

Parameters:

  • payloads (list[bytes]) – List of encoded bitstreams.

  • shapes (list of tuple of (int, int), optional) – Per-tile shapes matching payloads. When provided, each payload is assumed to carry the 8-byte header. Defaults to None (legacy: square tiles, no header).

Returns:

4D array of decoded tiles (n_tile_rows, n_tile_cols, tile_rows, tile_cols).

Return type:

np.ndarray

Examples