Skip to content

abczarr.metadata.v2.filters

Classes

Filter 

Filter(id: str | bytes = '', *, extra_items: Iterable[tuple[str | bytes, Any]] | Mapping[str | bytes, Any] = FrozenDict({}))

Bases: Metadata

A Filter names a numcodecs codec through id and carries that codec's own parameters.

A filter runs before the compressor, in the order the filters are listed. Each filter transforms an array's data on encode and reverses that transform on decode.

Attributes

id instance-attribute 
id: str

The numcodecs id of the filter, such as "delta" or "quantize".

Methods:

to_version 
to_version(version: ZarrVersion) -> Self

Convert this filter to another Zarr version.

Parameters:

Name Type Description Default
version ZarrVersion

The target Zarr format version: 2 or 3. Zarr v1 has no filter concept.

 required

Returns:

Type Description
Filter

This object unchanged for version 2, or the equivalent v3 codec for version 3.

Raises:

Type Description
ValueError

If version is not 2 or 3.

BitroundFilter 

BitroundFilter(id: Literal['bitround'] = 'bitround', keepbits: Integral | integer | bool = 1)

Bases: FilterImpl

Rounds a float's mantissa to keepbits bits, zeroing the rest.

The rounding is lossy and improves the compressibility of floating-point data by discarding low-order precision the data does not need.

Attributes

id instance-attribute 
id: Literal['bitround']

Always "bitround".

keepbits class-attribute instance-attribute 
keepbits: int = 1

The number of mantissa bits kept. The rest are zeroed.

Methods:

to_version 
to_version(version: ZarrVersion) -> Self

Convert this filter to another Zarr version.

Parameters:

Name Type Description Default
version ZarrVersion

The target Zarr format version: 2 or 3.

 required

Returns:

Type Description
Filter

This object unchanged for version 2, or the equivalent v3 bitround codec for version 3.

Raises:

Type Description
ValueError

If version is not 2 or 3.

PackBitsFilter 

PackBitsFilter(id: Literal['packbits'] = 'packbits')

Bases: FilterImpl

Packs a boolean array down to one bit per element for storage.

Attributes

id instance-attribute 
id: Literal['packbits']

Always "packbits".

Methods:

to_version 
to_version(version: ZarrVersion) -> Self

Convert this filter to another Zarr version.

Parameters:

Name Type Description Default
version ZarrVersion

The target Zarr format version: 2 or 3.

 required

Returns:

Type Description
Filter

This object unchanged for version 2, or the equivalent v3 packbits codec for version 3.

Raises:

Type Description
ValueError

If version is not 2 or 3.

ScaleOffsetFilter 

ScaleOffsetFilter(id: Literal['fixedscaleoffset'] = 'fixedscaleoffset', offset: Real | floating | bool = 0.0, scale: Real | floating | bool = 0.0, dtype: Any, astype: None = None)

Bases: FilterImpl

Quantizes values as (value - offset) * scale and stores the result as astype.

On decode, the scale and offset are reversed to recover an approximation of the original value. The transform is lossy and useful for storing a bounded floating-point range in fewer bits.

Attributes

id instance-attribute 
id: Literal['fixedscaleoffset']

Always "fixedscaleoffset".

offset instance-attribute 
offset: float

The value subtracted before scaling.

scale instance-attribute 
scale: float

The factor the offset value is multiplied by.

dtype instance-attribute 
dtype: dtype

The array's dtype before encoding.

astype instance-attribute 
astype: dtype | None

The dtype the scaled value is stored as. None means the array's own dtype is used.

Methods:

to_version 
to_version(version: ZarrVersion) -> Self

Convert this filter to another Zarr version.

Parameters:

Name Type Description Default
version ZarrVersion

The target Zarr format version: 2 or 3.

 required

Returns:

Type Description
Filter

This object unchanged for version 2, or the equivalent v3 scale-offset codec for version 3.

Raises:

Type Description
ValueError

If version is not 2 or 3.

AsTypeFilter 

AsTypeFilter(id: Literal['astype'] = 'astype', encode_dtype: Any, decode_dtype: None = None)

Bases: FilterImpl

Casts an array to encode_dtype for storage, and back on decode.

Attributes

id instance-attribute 
id: Literal['astype']

Always "astype".

encode_dtype instance-attribute 
encode_dtype: dtype

The dtype the array is cast to for storage.

decode_dtype instance-attribute 
decode_dtype: dtype | None

The dtype values are cast back to on read. None means the array's own dtype is used.

Methods:

to_version 
to_version(version: ZarrVersion) -> Self

Convert this filter to another Zarr version.

Parameters:

Name Type Description Default
version ZarrVersion

The target Zarr format version: 2 or 3.

 required

Returns:

Type Description
Filter

This object unchanged for version 2, or the equivalent v3 cast-value codec for version 3.

Raises:

Type Description
ValueError

If version is not 2 or 3.

CategorizeFilter 

CategorizeFilter(id: Literal['categorize'] = 'categorize', labels: Iterable[str | bytes] = (), dtype: Any, astype: None = None)

Bases: FilterImpl

Encodes each value in labels as its index, and back on decode.

Turns a categorical array into a compact integer array of category indices.

Attributes

id instance-attribute 
id: Literal['categorize']

Always "categorize".

labels instance-attribute 
labels: tuple[str, ...]

The category labels, in the order their index encodes them.

dtype instance-attribute 
dtype: dtype

The array's dtype before encoding.

astype instance-attribute 
astype: dtype | None

The dtype the encoded index is stored as. None means the array's own dtype is used.

Methods:

to_version 
to_version(version: ZarrVersion) -> Self

Convert this filter to another Zarr version.

Parameters:

Name Type Description Default
version ZarrVersion

The target Zarr format version: 2 or 3.

 required

Returns:

Type Description
Filter

This object unchanged for version 2, or the equivalent v3 cast-value codec for version 3.

Raises:

Type Description
ValueError

If version is not 2 or 3.

DeltaFilter 

DeltaFilter(id: Literal['delta'] = 'delta', dtype: Any, astype: None = None)

Bases: FilterImpl

Stores each value as its difference from the previous one.

Improves compressibility of arrays whose values change gradually along the last axis, such as a monotonic coordinate.

Attributes

id instance-attribute 
id: Literal['delta']

Always "delta".

dtype instance-attribute 
dtype: dtype

The array's dtype before encoding.

astype instance-attribute 
astype: dtype | None

The dtype the encoded differences are stored as. None means the array's own dtype is used.

Methods:

QuantizeFilter 

QuantizeFilter(id: Literal['quantize'] = 'quantize', digits: Integral | integer | bool = 0, dtype: Any, astype: None = None)

Bases: FilterImpl

Rounds floating-point values to digits decimal digits.

The rounding is lossy and improves compressibility by discarding precision the data does not need.

Attributes

id instance-attribute 
id: Literal['quantize']

Always "quantize".

digits instance-attribute 
digits: int

The number of decimal digits values are rounded to.

dtype instance-attribute 
dtype: dtype

The array's dtype before encoding.

astype instance-attribute 
astype: dtype | None

The dtype the rounded value is stored as. None means the array's own dtype is used.

Methods:

Shuffle 

Shuffle(id: Literal['shuffle'] = 'shuffle', elementsize: Integral | integer | bool | None = None)

Bases: FilterImpl

Reorders each element's bytes to group same-significance bytes together.

Groups the Nth byte of every element, each elementsize bytes wide, so that similar bytes sit next to each other. A downstream compressor typically compresses this layout better than the original interleaving.

Attributes

id instance-attribute 
id: Literal['shuffle']

Always "shuffle".

elementsize instance-attribute 
elementsize: int | None

The size, in bytes, of one array element. None lets the filter infer the size from the array's dtype.

Methods: