comdas.codecs.wavelet

Wavelet compression via PyWavelets.

Classes

WaveletCodec([wavelet, mode, keep_fraction, ...])

Wavelet-thresholding codec.

WaveletPayload(original_shape, dtype, ...)

Thresholded wavelet-coefficient representation of an array.
class comdas.codecs.wavelet.WaveletPayload(original_shape, dtype, wavelet, mode, indices, values)

Bases: CompressedPayload

Thresholded wavelet-coefficient representation of an array.

Retained coefficients are stored as (indices, values) pairs.

Variables:

  • wavelet (str) – Name of the PyWavelets wavelet.

  • mode (str) – PyWavelets signal extension mode.

  • indices (numpy.ndarray) – Flat indices of retained coefficients.

  • values (numpy.ndarray) – Values of retained coefficients.

property coeff_shapes: list

Get the coefficient shapes of the decomposition before thresholding.

Return type:

list

property n_coeffs: int

Total number of coefficients in the full decomposition without thresholding.

Return type:

int

property compression_params: dict

The compression parameters used for this payload.

Return type:

dict

class comdas.codecs.wavelet.WaveletCodec(wavelet='db4', mode='symmetric', keep_fraction=None, threshold=None)

Bases: Codec

Wavelet-thresholding codec.

The array is decomposed with a multilevel n-dimensional discrete wavelet transform (pywt.wavedecn()) at the maximum useful level for the array shape, and only the largest-magnitude coefficients are retained.

Coefficients to keep can be chosen either as a fraction keep_fraction in (0, 1] of all coefficients, or as an absolute magnitude threshold where coefficients with |c| > threshold are kept. Exactly one option must be specified, either as a codec-level default or per-call parameter.

Parameters:

  • wavelet (str) – PyWavelets wavelet name. (default: "db4")

  • mode (str) – PyWavelets signal extension mode. (default: "symmetric")

  • keep_fraction (float | None) – Default fraction of coefficients to retain.

  • threshold (float | None) – Default absolute coefficient magnitude threshold.

Raises:

ValueError – If both of keep_fraction and threshold are specified.

encode(array, *, wavelet=None, mode=None, keep_fraction=None, threshold=None, **kwargs)

Compress an array via wavelet coefficient thresholding.

Parameters:

  • array (ndarray) – The dense array to compress.

  • wavelet (str | None) – Overrides self.default_wavelet for this call.

  • mode (str | None) – Overrides self.default_mode for this call.

  • keep_fraction (float | None) – Fraction of coefficients to retain, in (0, 1]. Overrides self.default_keep_fraction for this call.

  • threshold (float | None) – Absolute coefficient magnitude threshold. Overrides self.default_threshold for this call.

  • kwargs – Accepted and ignored for compatibility.

Returns:

The sparse wavelet payload.

Return type:

WaveletPayload

Raises:

ValueError – If both or neither of keep_fraction and threshold are specified, or either is out of range.

decode(payload)

Reconstruct the dense array via the inverse wavelet transform.

Parameters:

payload (WaveletPayload) – A payload previously produced by encode().

Returns:

The reconstructed dense array.

Return type:

ndarray

compressed_size_bytes(payload)

Get payload size.

Parameters:

payload (WaveletPayload) – A payload previously produced by encode().

Returns:

Combined byte size of the stored arrays.

Return type:

int

payload_to_group(payload, group)

Write indices, values, and transform parameters into an open h5py.Group.

Parameters:

  • payload (WaveletPayload) – The payload to serialize.

  • group (h5py.Group) – An open, writable h5py.Group dedicated to this one patch.

Return type:

None

payload_from_group(group, *, original_shape, dtype)

Construct a WaveletPayload from an HDF5 group.

Parameters:

  • group (h5py.Group) – An open, readable h5py.Group previously written by payload_to_group().

  • original_shape (tuple[int, ...]) – The array shape, as read from the container’s own attributes.

  • dtype (dtype) – The array dtype, as read from the container’s own attributes.

Returns:

The reconstructed payload.

Return type:

WaveletPayload