gunz_cm.compressions#

Submodules#

Compression codecs for GZCM v3 contact matrix tiles.

Benchmarks (GM12878 chr1 @ 50kb, tile_size=512, window=1Mb):

(*) cmc_zstd offers the best balance of compression ratio and convert speed.

bsc_cmc: CMC transforms (binarization, diagonal transform) + BSC entropy coding. Same compression as CMC with faster access. Best overall codec for storage-constrained use.

Examples

>>> from gunz_cm.compressions import CmcZstdEncoder, CmcZstdDecoder
>>> encoder = CmcZstdEncoder(tile_size=512)
>>> encoded = encoder.encode_tile(tile_data)
>>> decoder = CmcZstdDecoder(tile_size=512)
>>> decoded = decoder.decode_tile(encoded)
class gunz_cm.compressions.BscCmcDecoder(tile_size: int = 512, resolution: int = 50000, dtype: ~numpy.dtype = <class 'numpy.uint32'>, diag_mode: int = 0)[source]#

Bases: object

BSC + CMC Transforms decoder for contact matrix tiles.

Decodes BSC-compressed data that was encoded with CMC transforms. Reverses BSC entropy coding then CMC’s domain-specific transforms.

Parameters:

  • tile_size (int, default=512) – 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.

Examples

decode_tile(payload: bytes) → ndarray[source]#

Decode a single compressed tile.

Parameters:

payload (bytes) – Compressed bitstream (shape info + encoded data).

Returns:

Decoded contact matrix tile.

Return type:

np.ndarray

Examples

decode_tiles(payloads: list[bytes]) → ndarray[source]#

Decode multiple tiles into a 4D array.

Parameters:

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

Returns:

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

Return type:

np.ndarray

Examples

class gunz_cm.compressions.BscCmcEncoder(tile_size: int = 512, resolution: int = 50000, level: int = 3, diag_mode: int = 0)[source]#

Bases: object

BSC + CMC Transforms encoder for contact matrix tiles.

Applies CMC’s domain-specific transforms (diagonal transform, binarization) before BSC entropy coding. Combines BSC’s speed with CMC’s structured transforms.

Parameters:

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

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

  • level (int, default=3) – BSC compression level (0-9, higher = better compression).

Examples

encode_tile(mat: ndarray) → bytes[source]#

Encode a single contact matrix tile.

Parameters:

mat (np.ndarray) – 2D contact matrix tile (upper triangular).

Returns:

Compressed bitstream (shape info + encoded data).

Return type:

bytes

Examples

encode_tiles(tiles: ndarray) → list[bytes][source]#

Encode multiple tiles.

Parameters:

tiles (np.ndarray) – 4D array of shape (n_tile_rows, n_tile_cols, tile_size, tile_size).

Returns:

List of encoded bitstreams, one per tile.

Return type:

list[bytes]

Examples

get_compression_info() → dict[source]#

Return compression metadata.

Returns:

Compression parameters for header.

Return type:

dict

Examples

class gunz_cm.compressions.BscDecoder(tile_size: int = 512, resolution: int = 50000, dtype: ~numpy.dtype = <class 'numpy.uint32'>)[source]#

Bases: object

BSC decoder for contact matrix tiles.

Uses bsc CLI subprocess for true BSC (Block Sorting Compression) decompression.

Parameters:

  • tile_size (int, default=512) – 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.

Examples

decode_tile(payload: bytes) → ndarray[source]#

Decode a single BSC-compressed tile.

Parameters:

payload (bytes) – BSC-compressed bitstream.

Returns:

Decoded contact matrix tile.

Return type:

np.ndarray

Examples

decode_tiles(payloads: list[bytes]) → ndarray[source]#

Decode multiple tiles into a 4D array.

Parameters:

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

Returns:

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

Return type:

np.ndarray

Examples

class gunz_cm.compressions.BscEncoder(tile_size: int = 512, resolution: int = 50000, level: int = 3)[source]#

Bases: object

BSC encoder for contact matrix tiles.

Uses bsc CLI subprocess for true BSC (Block Sorting Compression).

Parameters:

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

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

  • level (int, default=3) – Compression level (0-9, higher = better compression).

Examples

encode_tile(mat: ndarray) → bytes[source]#

Encode a single contact matrix tile.

Parameters:

mat (np.ndarray) – 2D contact matrix tile.

Returns:

BSC-compressed bitstream.

Return type:

bytes

Examples

encode_tiles(tiles: ndarray) → list[bytes][source]#

Encode multiple tiles.

Parameters:

tiles (np.ndarray) – 4D array of shape (n_tile_rows, n_tile_cols, tile_size, tile_size).

Returns:

List of encoded bitstreams, one per tile.

Return type:

list[bytes]

Examples

get_compression_info() → dict[source]#

Return compression metadata.

Returns:

Compression parameters for header.

Return type:

dict

Examples

class gunz_cm.compressions.CmcDecoder(tile_size: int = 256, resolution: int = 50000, diag_transform: bool = True)[source]#

Bases: object

CMC 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.

  • diag_transform (bool, default=True) – Reverse diagonal transform after decoding.

Examples

decode_tile(payload: bytes) → ndarray[source]#

Decode a single CMC-encoded tile.

Parameters:

payload (bytes) – CMC-encoded bitstream.

Returns:

Decoded contact matrix tile.

Return type:

np.ndarray

Examples

decode_tiles(payloads: list[bytes]) → ndarray[source]#

Decode multiple tiles into a 4D array.

Parameters:

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

Returns:

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

Return type:

np.ndarray

Examples

class gunz_cm.compressions.CmcEncoder(tile_size: int = 256, resolution: int = 50000, diag_transform: bool = True)[source]#

Bases: object

CMC encoder for contact matrix tiles.

Parameters:

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

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

  • diag_transform (bool, default=True) – Apply diagonal transform before encoding.

Examples

encode_tile(mat: ndarray) → bytes[source]#

Encode a single contact matrix tile.

Parameters:

mat (np.ndarray) – 2D contact matrix tile (upper triangular).

Returns:

CMC-encoded bitstream.

Return type:

bytes

Examples

encode_tiles(tiles: ndarray) → list[bytes][source]#

Encode multiple tiles.

Parameters:

tiles (np.ndarray) – 4D array of shape (n_tile_rows, n_tile_cols, tile_size, tile_size).

Returns:

List of encoded bitstreams, one per tile.

Return type:

list[bytes]

Examples

get_compression_info() → dict[source]#

Return compression metadata.

Returns:

Compression parameters for header.

Return type:

dict

Examples

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

Bases: object

CMC Transforms + Zstd decoder for contact matrix tiles.

Uses Zstd decompression then reverses CMC’s domain-specific transforms.

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.

Examples

decode_tile(payload: bytes) → ndarray[source]#

Decode a single compressed tile.

Parameters:

payload (bytes) – Compressed bitstream (shape info + encoded data).

Returns:

Decoded contact matrix tile.

Return type:

np.ndarray

Examples

decode_tiles(payloads: list[bytes]) → ndarray[source]#

Decode multiple tiles into a 4D array.

Parameters:

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

Returns:

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

Return type:

np.ndarray

Examples

class gunz_cm.compressions.CmcZstdEncoder(tile_size: int = 256, resolution: int = 50000, level: int = 3)[source]#

Bases: object

CMC Transforms + Zstd encoder for contact matrix tiles.

Uses CMC’s domain-specific transforms (diagonal transform, binarization) with Zstd entropy coding for better compression and faster decode.

Parameters:

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

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

  • level (int, default=3) – Compression level (1-22 for zstd, 1-9 for zlib fallback).

Examples

encode_tile(mat: ndarray) → bytes[source]#

Encode a single contact matrix tile.

Parameters:

mat (np.ndarray) – 2D contact matrix tile (upper triangular).

Returns:

Compressed bitstream (shape info + encoded data).

Return type:

bytes

Examples

encode_tiles(tiles: ndarray) → list[bytes][source]#

Encode multiple tiles.

Parameters:

tiles (np.ndarray) – 4D array of shape (n_tile_rows, n_tile_cols, tile_size, tile_size).

Returns:

List of encoded bitstreams, one per tile.

Return type:

list[bytes]

Examples

get_compression_info() → dict[source]#

Return compression metadata.

Returns:

Compression parameters for header.

Return type:

dict

Examples

class gunz_cm.compressions.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) → ndarray[source]#

Decode a single compressed tile.

Parameters:

payload (bytes) – Compressed bitstream.

Returns:

Decoded contact matrix tile.

Return type:

np.ndarray

Examples

decode_tiles(payloads: list[bytes]) → ndarray[source]#

Decode multiple tiles into a 4D array.

Parameters:

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

Returns:

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

Return type:

np.ndarray

Examples

class gunz_cm.compressions.ZstdEncoder(tile_size: int = 256, resolution: int = 50000, level: int = 3, use_zstd: bool = True)[source]#

Bases: object

Zstd encoder for contact matrix tiles.

Parameters:

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

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

  • level (int, default=3) – Compression level (1-22 for zstd, 1-9 for zlib fallback).

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

Examples

encode_tile(mat: ndarray) → bytes[source]#

Encode a single contact matrix tile.

Parameters:

mat (np.ndarray) – 2D contact matrix tile.

Returns:

Compressed bitstream.

Return type:

bytes

Examples

encode_tiles(tiles: ndarray) → list[bytes][source]#

Encode multiple tiles.

Parameters:

tiles (np.ndarray) – 4D array of shape (n_tile_rows, n_tile_cols, tile_size, tile_size).

Returns:

List of encoded bitstreams, one per tile.

Return type:

list[bytes]

Examples

get_compression_info() → dict[source]#

Return compression metadata.

Returns:

Compression parameters for header.

Return type:

dict

Examples