gunz_cm.io#

Module contents#

class gunz_cm.io.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.io.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.