gunz_cm.compressions.bsc_decoder#

Module contents#

BSC Decoder wrapper for GZCM v3 compression.

Uses BSC CLI subprocess with LD_LIBRARY_PATH for libomp.

Examples

class gunz_cm.compressions.bsc_decoder.BscDecoder(tile_size: int = 512, resolution: int = 50000, dtype: ~numpy.dtype = <class 'numpy.uint32'>, bsc_bin: str | pathlib.Path | None = None, ld_library_path: str | pathlib.Path | None = None)[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.

  • bsc_bin (str or pathlib.Path, optional) – Explicit path to the bsc binary. If None, resolved via GUNZ_CM_BSC_BIN env var or system PATH.

  • ld_library_path (str or pathlib.Path, optional) – Explicit LD_LIBRARY_PATH for the bsc subprocess. If None, resolved via GUNZ_CM_BSC_LD_LIBRARY_PATH env var.

Examples

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

Decode a single BSC-compressed tile.

Parameters:

  • payload (bytes) – BSC-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