Skip to content

Index

DaskArrayWrapper dataclass #

DaskArrayWrapper(chunks='auto', meta=None, inline_array=True, naming='array_url')

Bases: BaseArrayWrapper

An array wrapper that wraps a zarr.Array in a dask array using dask.array.from_array. The attributes of this class are a subset of the keyword arguments to dask.array.from_array; specifically, those keyword arguments that make sense when the input to from_array is a zarr.Array.

Attributes:

Name Type Description
chunks str | int | tuple[int, ...] tuple[tuple[int, ...], ...] = "auto"

The chunks for the Dask array. See dask.array.from_array for details.
meta Any = `None`

The array type of each chunk of the Dask array. See dask.array.from_array for details.
inline_array bool = True

Whether slices of this array should be inlined into the Dask task graph. See dask.array.from_array for details.
naming 'auto' | 'array_url'

The naming scheme for the Dask array. If "auto", the default, then Dask will name the array with a non-deterministic hash. If "array_url", then the array will be named according to its URL.

wrap #

wrap(data)

Wrap the input in a dask array.

Source code in src/xarray_ome_ngff/array_wrap.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def wrap(self, data: zarr.Array) -> DaskArray:  # type: ignore
    """
    Wrap the input in a dask array.
    """
    import dask.array as da  # noqa

    if self.naming == "auto":
        name = None
    elif self.naming == "array_url":
        name = f"{get_store_url(data.store)}/{data.path}"

    return da.from_array(
        data,
        chunks=self.chunks,
        inline_array=self.inline_array,
        meta=self.meta,
        name=name,
    )

ZarrArrayWrapper dataclass #

ZarrArrayWrapper()

Bases: BaseArrayWrapper

An array wrapper that passes zarr.Array instances through unchanged.

read_multiscale_group #

read_multiscale_group(group, array_wrapper=ZarrArrayWrapper(), ngff_version='0.4', **kwargs)

Create a dictionary of xarray.DataArray from a Zarr group that implements some version of the OME-NGFF multiscale image specification.

The keys of the dictionary are the paths to the Zarr arrays. The values of the dictionary are xarray.DataArray objects, one per Zarr array described in the OME-NGFF multiscale metadata.

Parameters:

Name Type Description Default
group Group

A handle for the Zarr group that contains the OME-NGFF metadata.

 required
array_wrapper ZarrArrayWrapper | DaskArrayWrapper | ArrayWrapperSpec

Either an object that implements BaseArrayWrapper, or a dict model of such a subclass, which will be resolved to an object implementing BaseArrayWrapper. This object has a wrap method that takes an instance of zarr.Array and returns another array-like object. This enables wrapping Zarr arrays in a lazy array representation like Dask arrays (e.g., via `DaskArrayWrapper), which is necessary when working with large Zarr arrays.

 ZarrArrayWrapper()
**kwargs

Additional keyword arguments that will be passed to the read_group function defined for a specific OME-NGFF version

 {}
Source code in src/xarray_ome_ngff/__init__.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def read_multiscale_group(
    group: zarr.Group,
    array_wrapper: ZarrArrayWrapper
    | DaskArrayWrapper
    | ArrayWrapperSpec = ZarrArrayWrapper(),
    ngff_version: Literal["0.4"] = "0.4",
    **kwargs,
) -> dict[str, DataArray]:
    """
    Create a dictionary of `xarray.DataArray` from a Zarr group that implements some version of the
    OME-NGFF multiscale image specification.

    The keys of the dictionary are the paths to the Zarr arrays. The values of the dictionary are
    `xarray.DataArray` objects, one per Zarr array described in the OME-NGFF multiscale metadata.

    Parameters
    ----------
    group: zarr.Group
        A handle for the Zarr group that contains the OME-NGFF metadata.
    array_wrapper: ZarrArrayWrapper | DaskArrayWrapper | ArrayWrapperSpec, default = ZarrArrayWrapper
        Either an object that implements `BaseArrayWrapper`, or a dict model of such a subclass,
        which will be resolved to an object implementing `BaseArrayWrapper`. This object has a
        `wrap` method that takes an instance of `zarr.Array` and returns another array-like object.
        This enables wrapping Zarr arrays in a lazy array representation like Dask arrays
        (e.g., via `DaskArrayWrapper), which is necessary when working with large Zarr arrays.
    **kwargs: Any
        Additional keyword arguments that will be passed to the `read_group` function defined for a
        specific OME-NGFF version
    """
    if ngff_version not in NGFF_VERSIONS:
        raise ValueError(f"Unsupported NGFF version: {ngff_version}")
    if ngff_version == "0.4":
        return multiscale_v04.read_multiscale_group(
            group, array_wrapper=array_wrapper, **kwargs
        )

read_multiscale_array #

read_multiscale_array(array, array_wrapper=ZarrArrayWrapper(), ngff_version='0.4', **kwargs)

Read a single Zarr array as an xarray.DataArray, using OME-NGFF metadata.

Parameters:

Name Type Description Default
array Array

A Zarr array that is part of a version 0.4 OME-NGFF multiscale image.

 required
array_wrapper ZarrArrayWrapper | DaskArrayWrapper | ArrayWrapperSpec

The array wrapper class to use when converting the Zarr array to an xarray.DataArray.

 ZarrArrayWrapper()

Returns:

Type Description
DataArray
Source code in src/xarray_ome_ngff/__init__.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def read_multiscale_array(
    array: zarr.Array,
    array_wrapper: ZarrArrayWrapper
    | DaskArrayWrapper
    | ArrayWrapperSpec = ZarrArrayWrapper(),
    ngff_version: Literal["0.4"] = "0.4",
    **kwargs,
) -> DataArray:
    """
    Read a single Zarr array as an `xarray.DataArray`, using OME-NGFF
    metadata.

    Parameters
    ----------
    array: zarr.Array
        A Zarr array that is part of a version 0.4 OME-NGFF multiscale image.
    array_wrapper: BaseArrayWrapper | ArrayWrapperSpec, default is ZarrArrayWrapper
        The array wrapper class to use when converting the Zarr array to an `xarray.DataArray`.

    Returns
    -------
    xarray.DataArray
    """
    if ngff_version not in NGFF_VERSIONS:
        raise ValueError(f"Unsupported NGFF version: {ngff_version}")
    if ngff_version == "0.4":
        return multiscale_v04.read_multiscale_array(
            array, array_wrapper=array_wrapper, **kwargs
        )

model_multiscale_group #

model_multiscale_group(*, arrays, transform_precision=None, ngff_version='0.4', chunks='auto', compressor=multiscale_v04.DEFAULT_COMPRESSOR, fill_value=0)

Create a model of an OME-NGFF multiscale group from a dict of xarray.DataArray. The dimensions / coordinates of the arrays will be used to infer OME-NGFF axis metadata, as well as the OME-NGFF coordinate transformation metadata (i.e., scaling and translation).

Parameters:

Name Type Description Default
arrays dict[str, DataArray]

A mapping from strings to xarray.DataArray.

 required
transform_precision int | None

Whether, and how much, to round the transformations estimated from the coordinates. The default (None) results in no rounding; specifying an int x will round transforms to x decimal places using numpy.round(transform, x).

 None
ngff_version Literal['0.4']

The OME-NGFF version to use.

 '0.4'
chunks tuple[int, ...] | tuple[tuple[int, ...]] | Literal['auto']

The chunks for the arrays in the multiscale group. If the string "auto" is provided, each array will have chunks set to the zarr-python default value, which depends on the shape and dtype of the array. If a single sequence of ints is provided, then this defines the chunks for all arrays. If a sequence of sequences of ints is provided, then this defines the chunks for each array.

 'auto'
compressor Codec | None

The compressor to use for the arrays. Default is numcodecs.ZStd.

 DEFAULT_COMPRESSOR
fill_value Any

The fill value for the Zarr arrays.

 0
Source code in src/xarray_ome_ngff/__init__.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def model_multiscale_group(
    *,
    arrays: dict[str, DataArray],
    transform_precision: int | None = None,
    ngff_version: Literal["0.4"] = "0.4",
    chunks: tuple[int, ...] | tuple[tuple[int, ...]] | Literal["auto"] = "auto",
    compressor: Codec | None = multiscale_v04.DEFAULT_COMPRESSOR,
    fill_value: Any = 0,
) -> MultiscaleGroupV04:
    """
    Create a model of an OME-NGFF multiscale group from a dict of `xarray.DataArray`.
    The dimensions / coordinates of the arrays will be used to infer OME-NGFF axis metadata, as well
    as the OME-NGFF coordinate transformation metadata (i.e., scaling and translation).

    Parameters
    ----------
    arrays: dict[str, DataArray]
        A mapping from strings to `xarray.DataArray`.
    transform_precision: int | None, default is None
        Whether, and how much, to round the transformations estimated from the coordinates.
        The default (`None`) results in no rounding; specifying an `int` x will round transforms to
        x decimal places using `numpy.round(transform, x)`.
    ngff_version: Literal["0.4"]
        The OME-NGFF version to use.
    chunks: tuple[int] | tuple[tuple[int, ...]] | Literal["auto"], default = "auto"
        The chunks for the arrays in the multiscale group.
        If the string "auto" is provided, each array will have chunks set to the zarr-python default
        value, which depends on the shape and dtype of the array.
        If a single sequence of ints is provided, then this defines the chunks for all arrays.
        If a sequence of sequences of ints is provided, then this defines the chunks for each array.
    compressor: Codec | None, default = numcodecs.ZStd.
        The compressor to use for the arrays. Default is `numcodecs.ZStd`.
    fill_value: Any
        The fill value for the Zarr arrays.
    """
    if ngff_version not in NGFF_VERSIONS:
        raise ValueError(f"Unsupported NGFF version: {ngff_version}")
    if ngff_version == "0.4":
        return multiscale_v04.model_multiscale_group(
            arrays=arrays,
            transform_precision=transform_precision,
            compressor=compressor,
            chunks=chunks,
            fill_value=fill_value,
        )

create_multiscale_group #

create_multiscale_group(*, store, path, arrays, transform_precision=None, ngff_version='0.4', chunks='auto', compressor=multiscale_v04.DEFAULT_COMPRESSOR, fill_value=0, overwrite=False)

store: zarr.storage.BaseStore The storage backend for the Zarr hierarchy. path: str The path in the storage backend for the multiscale group. arrays: dict[str, DataArray] A mapping from strings to xarray.DataArray. transform_precision: int | None, default is None Whether, and how much, to round the transformations estimated from the coordinates. The default (None) results in no rounding; specifying an int x will round transforms to x decimal places using numpy.round(transform, x). ngff_version: Literal["0.4"] The OME-NGFF version to use. chunks: tuple[int] | tuple[tuple[int, ...]] | Literal["auto"], default = "auto" The chunks for the arrays in the multiscale group. If the string "auto" is provided, each array will have chunks set to the zarr-python default value, which depends on the shape and dtype of the array. If a single sequence of ints is provided, then this defines the chunks for all arrays. If a sequence of sequences of ints is provided, then this defines the chunks for each array. compressor: Codec | None, default = numcodecs.ZStd. The compressor to use for the arrays. Default is numcodecs.ZStd. fill_value: Any The fill value for the Zarr arrays.

Source code in src/xarray_ome_ngff/__init__.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
def create_multiscale_group(
    *,
    store: BaseStore,
    path: str,
    arrays: dict[str, DataArray],
    transform_precision: int | None = None,
    ngff_version: Literal["0.4"] = "0.4",
    chunks: tuple[int, ...] | tuple[tuple[int, ...]] | Literal["auto"] = "auto",
    compressor: Codec | None = multiscale_v04.DEFAULT_COMPRESSOR,
    fill_value: Any = 0,
    overwrite: bool = False,
) -> MultiscaleGroupV04:
    """
    store: zarr.storage.BaseStore
        The storage backend for the Zarr hierarchy.
    path: str
        The path in the storage backend for the multiscale group.
    arrays: dict[str, DataArray]
        A mapping from strings to `xarray.DataArray`.
    transform_precision: int | None, default is None
        Whether, and how much, to round the transformations estimated from the coordinates.
        The default (`None`) results in no rounding; specifying an `int` x will round transforms to
        x decimal places using `numpy.round(transform, x)`.
    ngff_version: Literal["0.4"]
        The OME-NGFF version to use.
    chunks: tuple[int] | tuple[tuple[int, ...]] | Literal["auto"], default = "auto"
        The chunks for the arrays in the multiscale group.
        If the string "auto" is provided, each array will have chunks set to the zarr-python default
        value, which depends on the shape and dtype of the array.
        If a single sequence of ints is provided, then this defines the chunks for all arrays.
        If a sequence of sequences of ints is provided, then this defines the chunks for each array.
    compressor: Codec | None, default = numcodecs.ZStd.
        The compressor to use for the arrays. Default is `numcodecs.ZStd`.
    fill_value: Any
        The fill value for the Zarr arrays.
    """
    if ngff_version not in NGFF_VERSIONS:
        raise ValueError(f"Unsupported NGFF version: {ngff_version}")
    if ngff_version == "0.4":
        return multiscale_v04.create_multiscale_group(
            store=store,
            path=path,
            arrays=arrays,
            transform_precision=transform_precision,
            compressor=compressor,
            chunks=chunks,
            fill_value=fill_value,
            overwrite=overwrite,
        )