zarr#

Submodules#

Attributes#

config

Classes#

`Array`	Instantiate an array from an initialized store.
`AsyncArray`	An asynchronous array class representing a chunked array stored in a Zarr store.
`AsyncGroup`	Asynchronous Group object.
`Group`

Functions#

`array`(→ zarr.core.array.Array)	Create an array filled with data.
`consolidate_metadata`(→ zarr.core.group.Group)	Consolidate the metadata of all nodes in a hierarchy.
`copy`(→ tuple[int, int, int])
`copy_all`(→ tuple[int, int, int])
`copy_store`(→ tuple[int, int, int])
`create`(→ zarr.core.array.Array)	Create an array.
`create_array`(→ zarr.core.array.Array)	Create an array.
`create_group`(→ zarr.core.group.Group)	Create a group.
`empty`(→ zarr.core.array.Array)	Create an empty array.
`empty_like`(→ zarr.core.array.Array)	Create an empty array like another array.
`full`(→ zarr.core.array.Array)	Create an array with a default fill value.
`full_like`(→ zarr.core.array.Array)	Create a filled array like another array.
`group`(→ zarr.core.group.Group)	Create a group.
`load`(→ zarr.core.buffer.NDArrayLike \| dict[str, ...)	Load data from an array or group into memory.
`ones`(→ zarr.core.array.Array)	Create an array with a fill value of one.
`ones_like`(→ zarr.core.array.Array)	Create an array of ones like another array.
`open`(→ zarr.core.array.Array \| zarr.core.group.Group)	Open a group or array using file-mode-like semantics.
`open_array`(→ zarr.core.array.Array)	Open an array using file-mode-like semantics.
`open_consolidated`(→ zarr.core.group.Group)	Alias for `open_group()` with `use_consolidated=True`.
`open_group`(→ zarr.core.group.Group)	Open a group using file-mode-like semantics.
`open_like`(→ zarr.core.array.Array)	Open a persistent array like another array.
`save`(→ None)	Save an array or group of arrays to the local file system.
`save_array`(→ None)	Save a NumPy array to the local file system.
`save_group`(→ None)	Save several NumPy arrays to the local file system.
`tree`(→ Any)	Provide a rich display of the hierarchy.
`zeros`(→ zarr.core.array.Array)	Create an array with a fill value of zero.
`zeros_like`(→ zarr.core.array.Array)	Create an array of zeros like another array.

Package Contents#

class zarr.Array[source]#

Instantiate an array from an initialized store.

append( data: numpy.typing.ArrayLike, axis: int = 0, ) → zarr.core.common.ChunkCoords[source]#

Append data to axis.

Parameters:

dataarray-like: Data to be appended.
axisint: Axis along which to append.

Returns:

new_shapetuple

Notes

The size of all dimensions other than axis must match between this array and data.

Examples

>>> import numpy as np
>>> import zarr
>>> a = np.arange(10000000, dtype='i4').reshape(10000, 1000)
>>> z = zarr.array(a, chunks=(1000, 100))
>>> z.shape
(10000, 1000)
>>> z.append(a)
(20000, 1000)
>>> z.append(np.vstack([a, a]), axis=1)
(20000, 2000)
>>> z.shape
(20000, 2000)

classmethod create( store: zarr.storage.StoreLike, *, shape: zarr.core.common.ChunkCoords, dtype: numpy.typing.DTypeLike, zarr_format: zarr.core.common.ZarrFormat = 3, fill_value: Any | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_shape: zarr.core.common.ChunkCoords | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncoding | tuple[Literal['default'], Literal['.', '/']] | tuple[Literal['v2'], Literal['.', '/']] | None = None, codecs: collections.abc.Iterable[zarr.abc.codec.Codec | dict[str, zarr.core.common.JSON]] | None = None, dimension_names: collections.abc.Iterable[str] | None = None, chunks: zarr.core.common.ChunkCoords | None = None, dimension_separator: Literal['.', '/'] | None = None, order: zarr.core.common.MemoryOrder | None = None, filters: list[dict[str, zarr.core.common.JSON]] | None = None, compressor: dict[str, zarr.core.common.JSON] | None = None, overwrite: bool = False, config: zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | None = None, ) → Array[source]#

Creates a new Array instance from an initialized store.

Deprecated since version 3.0.0: Deprecated in favor of zarr.create_array().

Parameters:

storeStoreLike

The array store that has already been initialized.

shapeChunkCoords

The shape of the array.

dtypenpt.DTypeLike

The data type of the array.

chunk_shapeChunkCoords, optional

The shape of the Array’s chunks. Zarr format 3 only. Zarr format 2 arrays should use chunks instead. If not specified, default are guessed based on the shape and dtype.

chunk_key_encodingChunkKeyEncoding, optional

A specification of how the chunk keys are represented in storage. Zarr format 3 only. Zarr format 2 arrays should use dimension_separator instead. Default is ("default", "/").

codecsSequence of Codecs or dicts, optional

An iterable of Codec or dict serializations of Codecs. The elements of this collection specify the transformation from array values to stored bytes. Zarr format 3 only. Zarr format 2 arrays should use filters and compressor instead.

If no codecs are provided, default codecs will be used:

For numeric arrays, the default is BytesCodec and ZstdCodec.
For Unicode strings, the default is VLenUTF8Codec and ZstdCodec.
For bytes or objects, the default is VLenBytesCodec and ZstdCodec.

These defaults can be changed by modifying the value of array.v3_default_filters, array.v3_default_serializer and array.v3_default_compressors in zarr.core.config.

dimension_namesIterable[str], optional

The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter.

chunksChunkCoords, optional

The shape of the array’s chunks. Zarr format 2 only. Zarr format 3 arrays should use chunk_shape instead. If not specified, default are guessed based on the shape and dtype.

dimension_separatorLiteral[“.”, “/”], optional

The dimension separator (default is “.”). Zarr format 2 only. Zarr format 3 arrays should use chunk_key_encoding instead.

orderLiteral[“C”, “F”], optional

The memory of the array (default is “C”). If zarr_format is 2, this parameter sets the memory order of the array. If zarr_format` is 3, then this parameter is deprecated, because memory order is a runtime parameter for Zarr 3 arrays. The recommended way to specify the memory order for Zarr 3 arrays is via the config parameter, e.g. {'order': 'C'}.

filterslist[dict[str, JSON]], optional

Sequence of filters to use to encode chunk data prior to compression. Zarr format 2 only. Zarr format 3 arrays should use codecs instead. If no filters are provided, a default set of filters will be used. These defaults can be changed by modifying the value of array.v2_default_filters in zarr.core.config.

compressordict[str, JSON], optional

Primary compressor to compress chunk data. Zarr format 2 only. Zarr format 3 arrays should use codecs instead.

If no compressor is provided, a default compressor will be used:

For numeric arrays, the default is ZstdCodec.
For Unicode strings, the default is VLenUTF8Codec.
For bytes or objects, the default is VLenBytesCodec.

These defaults can be changed by modifying the value of array.v2_default_compressor in zarr.core.config.

overwritebool, optional

Whether to raise an error if the store already exists (default is False).

Returns:

Array: Array created from the store.

classmethod from_dict( store_path: zarr.storage._common.StorePath, data: dict[str, zarr.core.common.JSON], ) → Array[source]#

Create a Zarr array from a dictionary.

Parameters:

store_pathStorePath: The path within the store where the array should be created.
datadict: A dictionary representing the array data. This dictionary should include necessary metadata for the array, such as shape, dtype, fill value, and attributes.

Returns:

Array: The created Zarr array.

Raises:

ValueError: If the dictionary data is invalid or missing required fields for array creation.

get_basic_selection( selection: zarr.core.indexing.BasicSelection = Ellipsis, *, out: zarr.core.buffer.NDBuffer | None = None, prototype: zarr.core.buffer.BufferPrototype | None = None, fields: zarr.core.indexing.Fields | None = None, ) → zarr.core.buffer.NDArrayLike[source]#

Retrieve data for an item or region of the array.

Parameters:

selectiontuple: A tuple specifying the requested item or region for each dimension of the array. May be any combination of int and/or slice or ellipsis for multidimensional arrays.
outNDBuffer, optional: If given, load the selected data directly into this buffer.
prototypeBufferPrototype, optional: The prototype of the buffer to use for the output data. If not provided, the default buffer prototype is used.
fieldsstr or sequence of str, optional: For arrays with a structured dtype, one or more fields can be specified to extract data for.

Returns:

NDArrayLike: An array-like containing the data for the requested region.

See also

set_basic_selection, get_mask_selection, set_mask_selection
get_coordinate_selection, set_coordinate_selection, get_orthogonal_selection
set_orthogonal_selection, get_block_selection, set_block_selection
vindex, oindex, blocks, __getitem__, __setitem__

Notes

Slices with step > 1 are supported, but slices with negative step are not.

For arrays with a structured dtype, see Zarr format 2 for examples of how to use the fields parameter.

This method provides the implementation for accessing data via the square bracket notation (__getitem__). See __getitem__() for examples using the alternative notation.

Examples

Setup a 1-dimensional array:

>>> import zarr
>>> import numpy as np
>>> data = np.arange(100, dtype="uint16")
>>> z = zarr.create_array(
>>>        StorePath(MemoryStore(mode="w")),
>>>        shape=data.shape,
>>>        chunks=(3,),
>>>        dtype=data.dtype,
>>>        )
>>> z[:] = data

Retrieve a single item:

>>> z.get_basic_selection(5)
5

Retrieve a region via slicing:

>>> z.get_basic_selection(slice(5))
array([0, 1, 2, 3, 4])
>>> z.get_basic_selection(slice(-5, None))
array([95, 96, 97, 98, 99])
>>> z.get_basic_selection(slice(5, 10))
array([5, 6, 7, 8, 9])
>>> z.get_basic_selection(slice(5, 10, 2))
array([5, 7, 9])
>>> z.get_basic_selection(slice(None, None, 2))
array([  0,  2,  4, ..., 94, 96, 98])

Setup a 3-dimensional array:

>>> data = np.arange(1000).reshape(10, 10, 10)
>>> z = zarr.create_array(
>>>        StorePath(MemoryStore(mode="w")),
>>>        shape=data.shape,
>>>        chunks=(5, 5, 5),
>>>        dtype=data.dtype,
>>>        )
>>> z[:] = data

Retrieve an item:

>>> z.get_basic_selection((1, 2, 3))
123

Retrieve a region via slicing and Ellipsis:

>>> z.get_basic_selection((slice(1, 3), slice(1, 3), 0))
array([[110, 120],
       [210, 220]])
>>> z.get_basic_selection(0, (slice(1, 3), slice(None)))
array([[10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
       [20, 21, 22, 23, 24, 25, 26, 27, 28, 29]])
>>> z.get_basic_selection((..., 5))
array([[  2  12  22  32  42  52  62  72  82  92]
       [102 112 122 132 142 152 162 172 182 192]
       ...
       [802 812 822 832 842 852 862 872 882 892]
       [902 912 922 932 942 952 962 972 982 992]]

get_block_selection( selection: zarr.core.indexing.BasicSelection, *, out: zarr.core.buffer.NDBuffer | None = None, fields: zarr.core.indexing.Fields | None = None, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → zarr.core.buffer.NDArrayLike[source]#

Retrieve a selection of individual items, by providing the indices (coordinates) for each selected item.

Parameters:

selectionint or slice or tuple of int or slice: An integer (coordinate) or slice for each dimension of the array.
outNDBuffer, optional: If given, load the selected data directly into this buffer.
fieldsstr or sequence of str, optional: For arrays with a structured dtype, one or more fields can be specified to extract data for.
prototypeBufferPrototype, optional: The prototype of the buffer to use for the output data. If not provided, the default buffer prototype is used.

Returns:

NDArrayLike: An array-like containing the data for the requested block selection.

See also

get_basic_selection, set_basic_selection, get_mask_selection, set_mask_selection
get_orthogonal_selection, set_orthogonal_selection, get_coordinate_selection
set_coordinate_selection, set_block_selection
vindex, oindex, blocks, __getitem__, __setitem__

Notes

Block indexing is a convenience indexing method to work on individual chunks with chunk index slicing. It has the same concept as Dask’s Array.blocks indexing.

Slices are supported. However, only with a step size of one.

Block index arrays may be multidimensional to index multidimensional arrays. For example:

>>> z.blocks[0, 1:3]
array([[ 3,  4,  5,  6,  7,  8],
       [13, 14, 15, 16, 17, 18],
       [23, 24, 25, 26, 27, 28]])

Examples

Setup a 2-dimensional array:

>>> import zarr
>>> import numpy as np
>>> data = np.arange(0, 100, dtype="uint16").reshape((10, 10))
>>> z = zarr.create_array(
>>>        StorePath(MemoryStore(mode="w")),
>>>        shape=data.shape,
>>>        chunks=(3, 3),
>>>        dtype=data.dtype,
>>>        )
>>> z[:] = data

Retrieve items by specifying their block coordinates:

>>> z.get_block_selection((1, slice(None)))
array([[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, 59]])

Which is equivalent to:

>>> z[3:6, :]
array([[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, 59]])

For convenience, the block selection functionality is also available via the blocks property, e.g.:

>>> z.blocks[1]
array([[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, 59]])

get_coordinate_selection( selection: zarr.core.indexing.CoordinateSelection, *, out: zarr.core.buffer.NDBuffer | None = None, fields: zarr.core.indexing.Fields | None = None, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → zarr.core.buffer.NDArrayLike[source]#

Retrieve a selection of individual items, by providing the indices (coordinates) for each selected item.

Parameters:

selectiontuple: An integer (coordinate) array for each dimension of the array.
outNDBuffer, optional: If given, load the selected data directly into this buffer.
fieldsstr or sequence of str, optional: For arrays with a structured dtype, one or more fields can be specified to extract data for.
prototypeBufferPrototype, optional: The prototype of the buffer to use for the output data. If not provided, the default buffer prototype is used.

Returns:

NDArrayLike: An array-like containing the data for the requested coordinate selection.

See also

get_basic_selection, set_basic_selection, get_mask_selection, set_mask_selection
get_orthogonal_selection, set_orthogonal_selection, set_coordinate_selection
get_block_selection, set_block_selection
vindex, oindex, blocks, __getitem__, __setitem__

Notes

Coordinate indexing is also known as point selection, and is a form of vectorized or inner indexing.

Slices are not supported. Coordinate arrays must be provided for all dimensions of the array.

Coordinate arrays may be multidimensional, in which case the output array will also be multidimensional. Coordinate arrays are broadcast against each other before being applied. The shape of the output will be the same as the shape of each coordinate array after broadcasting.

Examples

Setup a 2-dimensional array:

>>> import zarr
>>> import numpy as np
>>> data = np.arange(0, 100, dtype="uint16").reshape((10, 10))
>>> z = zarr.create_array(
>>>        StorePath(MemoryStore(mode="w")),
>>>        shape=data.shape,
>>>        chunks=(3, 3),
>>>        dtype=data.dtype,
>>>        )
>>> z[:] = data

Retrieve items by specifying their coordinates:

>>> z.get_coordinate_selection(([1, 4], [1, 4]))
array([11, 44])

For convenience, the coordinate selection functionality is also available via the vindex property, e.g.:

>>> z.vindex[[1, 4], [1, 4]]
array([11, 44])

get_mask_selection( mask: zarr.core.indexing.MaskSelection, *, out: zarr.core.buffer.NDBuffer | None = None, fields: zarr.core.indexing.Fields | None = None, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → zarr.core.buffer.NDArrayLike[source]#

Retrieve a selection of individual items, by providing a Boolean array of the same shape as the array against which the selection is being made, where True values indicate a selected item.

Parameters:

maskndarray, bool: A Boolean array of the same shape as the array against which the selection is being made.
outNDBuffer, optional: If given, load the selected data directly into this buffer.
fieldsstr or sequence of str, optional: For arrays with a structured dtype, one or more fields can be specified to extract data for.
prototypeBufferPrototype, optional: The prototype of the buffer to use for the output data. If not provided, the default buffer prototype is used.

Returns:

NDArrayLike: An array-like containing the data for the requested selection.

See also

get_basic_selection, set_basic_selection, set_mask_selection
get_orthogonal_selection, set_orthogonal_selection, get_coordinate_selection
set_coordinate_selection, get_block_selection, set_block_selection
vindex, oindex, blocks, __getitem__, __setitem__

Notes

Mask indexing is a form of vectorized or inner indexing, and is equivalent to coordinate indexing. Internally the mask array is converted to coordinate arrays by calling np.nonzero.

Examples

Setup a 2-dimensional array:

>>> import zarr
>>> import numpy as np
>>> data = np.arange(100).reshape(10, 10)
>>> z = zarr.create_array(
>>>        StorePath(MemoryStore(mode="w")),
>>>        shape=data.shape,
>>>        chunks=data.shape,
>>>        dtype=data.dtype,
>>>        )
>>> z[:] = data

Retrieve items by specifying a mask:

>>> sel = np.zeros_like(z, dtype=bool)
>>> sel[1, 1] = True
>>> sel[4, 4] = True
>>> z.get_mask_selection(sel)
array([11, 44])

For convenience, the mask selection functionality is also available via the vindex property, e.g.:

>>> z.vindex[sel]
array([11, 44])

get_orthogonal_selection( selection: zarr.core.indexing.OrthogonalSelection, *, out: zarr.core.buffer.NDBuffer | None = None, fields: zarr.core.indexing.Fields | None = None, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → zarr.core.buffer.NDArrayLike[source]#

Retrieve data by making a selection for each dimension of the array. For example, if an array has 2 dimensions, allows selecting specific rows and/or columns. The selection for each dimension can be either an integer (indexing a single item), a slice, an array of integers, or a Boolean array where True values indicate a selection.

Parameters:

selectiontuple: A selection for each dimension of the array. May be any combination of int, slice, integer array or Boolean array.
outNDBuffer, optional: If given, load the selected data directly into this buffer.
fieldsstr or sequence of str, optional: For arrays with a structured dtype, one or more fields can be specified to extract data for.
prototypeBufferPrototype, optional: The prototype of the buffer to use for the output data. If not provided, the default buffer prototype is used.

Returns:

NDArrayLike: An array-like containing the data for the requested selection.

See also

get_basic_selection, set_basic_selection, get_mask_selection, set_mask_selection
get_coordinate_selection, set_coordinate_selection, set_orthogonal_selection
get_block_selection, set_block_selection
vindex, oindex, blocks, __getitem__, __setitem__

Notes

Orthogonal indexing is also known as outer indexing.

Slices with step > 1 are supported, but slices with negative step are not.

Examples

Setup a 2-dimensional array:

>>> import zarr
>>> import numpy as np
>>> data = np.arange(100).reshape(10, 10)
>>> z = zarr.create_array(
>>>        StorePath(MemoryStore(mode="w")),
>>>        shape=data.shape,
>>>        chunks=data.shape,
>>>        dtype=data.dtype,
>>>        )
>>> z[:] = data

Retrieve rows and columns via any combination of int, slice, integer array and/or Boolean array:

>>> z.get_orthogonal_selection(([1, 4], slice(None)))
array([[10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
       [40, 41, 42, 43, 44, 45, 46, 47, 48, 49]])
>>> z.get_orthogonal_selection((slice(None), [1, 4]))
array([[ 1,  4],
       [11, 14],
       [21, 24],
       [31, 34],
       [41, 44],
       [51, 54],
       [61, 64],
       [71, 74],
       [81, 84],
       [91, 94]])
>>> z.get_orthogonal_selection(([1, 4], [1, 4]))
array([[11, 14],
       [41, 44]])
>>> sel = np.zeros(z.shape[0], dtype=bool)
>>> sel[1] = True
>>> sel[4] = True
>>> z.get_orthogonal_selection((sel, sel))
array([[11, 14],
       [41, 44]])

For convenience, the orthogonal selection functionality is also available via the oindex property, e.g.:

>>> z.oindex[[1, 4], :]
array([[10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
       [40, 41, 42, 43, 44, 45, 46, 47, 48, 49]])
>>> z.oindex[:, [1, 4]]
array([[ 1,  4],
       [11, 14],
       [21, 24],
       [31, 34],
       [41, 44],
       [51, 54],
       [61, 64],
       [71, 74],
       [81, 84],
       [91, 94]])
>>> z.oindex[[1, 4], [1, 4]]
array([[11, 14],
       [41, 44]])
>>> sel = np.zeros(z.shape[0], dtype=bool)
>>> sel[1] = True
>>> sel[4] = True
>>> z.oindex[sel, sel]
array([[11, 14],
       [41, 44]])

info_complete() → Any[source]#

Returns all the information about an array, including information from the Store.

In addition to the statically known information like name and zarr_format, this includes additional information like the size of the array in bytes and the number of chunks written.

Note that this method will need to read metadata from the store.

Returns:

ArrayInfo

See also

Array.info: The statically known subset of metadata about an array.

nbytes_stored() → int[source]#

Determine the size, in bytes, of the array actually written to the store.

Returns:

sizeint

classmethod open(store: zarr.storage.StoreLike) → Array[source]#

Opens an existing Array from a store.

Parameters:

storeStore: Store containing the Array.

Returns:

Array: Array opened from the store.

resize(new_shape: zarr.core.common.ShapeLike) → None[source]#

Change the shape of the array by growing or shrinking one or more dimensions.

Parameters:

new_shapetuple: New shape of the array.

Notes

If one or more dimensions are shrunk, any chunks falling outside the new array shape will be deleted from the underlying store. However, it is noteworthy that the chunks partially falling inside the new array (i.e. boundary chunks) will remain intact, and therefore, the data falling outside the new array but inside the boundary chunks would be restored by a subsequent resize operation that grows the array size.

Examples

>>> import zarr
>>> z = zarr.zeros(shape=(10000, 10000),
>>>                chunk_shape=(1000, 1000),
>>>                dtype="i4",)
>>> z.shape
(10000, 10000)
>>> z = z.resize(20000, 1000)
>>> z.shape
(20000, 1000)
>>> z2 = z.resize(50, 50)
>>> z.shape
(20000, 1000)
>>> z2.shape
(50, 50)

set_basic_selection( selection: zarr.core.indexing.BasicSelection, value: numpy.typing.ArrayLike, *, fields: zarr.core.indexing.Fields | None = None, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → None[source]#

Modify data for an item or region of the array.

Parameters:

selectiontuple: A tuple specifying the requested item or region for each dimension of the array. May be any combination of int and/or slice or ellipsis for multidimensional arrays.
valuenpt.ArrayLike: An array-like containing values to be stored into the array.
fieldsstr or sequence of str, optional: For arrays with a structured dtype, one or more fields can be specified to set data for.
prototypeBufferPrototype, optional: The prototype of the buffer used for setting the data. If not provided, the default buffer prototype is used.

See also

get_basic_selection, get_mask_selection, set_mask_selection
get_coordinate_selection, set_coordinate_selection, get_orthogonal_selection
set_orthogonal_selection, get_block_selection, set_block_selection
vindex, oindex, blocks, __getitem__, __setitem__

Notes

For arrays with a structured dtype, see Zarr format 2 for examples of how to use the fields parameter.

This method provides the underlying implementation for modifying data via square bracket notation, see __setitem__() for equivalent examples using the alternative notation.

Examples

Setup a 1-dimensional array:

>>> import zarr
>>> z = zarr.zeros(
>>>        shape=(100,),
>>>        store=StorePath(MemoryStore(mode="w")),
>>>        chunk_shape=(100,),
>>>        dtype="i4",
>>>       )

Set all array elements to the same scalar value:

>>> z.set_basic_selection(..., 42)
>>> z[...]
array([42, 42, 42, ..., 42, 42, 42])

Set a portion of the array:

>>> z.set_basic_selection(slice(10), np.arange(10))
>>> z.set_basic_selection(slice(-10, None), np.arange(10)[::-1])
>>> z[...]
array([ 0, 1, 2, ..., 2, 1, 0])

Setup a 2-dimensional array:

>>> z = zarr.zeros(
>>>        shape=(5, 5),
>>>        store=StorePath(MemoryStore(mode="w")),
>>>        chunk_shape=(5, 5),
>>>        dtype="i4",
>>>       )

Set all array elements to the same scalar value:

>>> z.set_basic_selection(..., 42)

Set a portion of the array:

>>> z.set_basic_selection((0, slice(None)), np.arange(z.shape[1]))
>>> z.set_basic_selection((slice(None), 0), np.arange(z.shape[0]))
>>> z[...]
array([[ 0,  1,  2,  3,  4],
       [ 1, 42, 42, 42, 42],
       [ 2, 42, 42, 42, 42],
       [ 3, 42, 42, 42, 42],
       [ 4, 42, 42, 42, 42]])

set_block_selection( selection: zarr.core.indexing.BasicSelection, value: numpy.typing.ArrayLike, *, fields: zarr.core.indexing.Fields | None = None, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → None[source]#

Modify a selection of individual blocks, by providing the chunk indices (coordinates) for each block to be modified.

Parameters:

selectiontuple: An integer (coordinate) or slice for each dimension of the array.
valuenpt.ArrayLike: An array-like containing the data to be stored in the block selection.
fieldsstr or sequence of str, optional: For arrays with a structured dtype, one or more fields can be specified to set data for.
prototypeBufferPrototype, optional: The prototype of the buffer used for setting the data. If not provided, the default buffer prototype is used.

See also

get_basic_selection, set_basic_selection, get_mask_selection, set_mask_selection
get_orthogonal_selection, set_orthogonal_selection, get_coordinate_selection
get_block_selection, set_block_selection
vindex, oindex, blocks, __getitem__, __setitem__

Notes

Block indexing is a convenience indexing method to work on individual chunks with chunk index slicing. It has the same concept as Dask’s Array.blocks indexing.

Slices are supported. However, only with a step size of one.

Examples

Set up a 2-dimensional array:

>>> import zarr
>>> z = zarr.zeros(
>>>        shape=(6, 6),
>>>        store=StorePath(MemoryStore(mode="w")),
>>>        chunk_shape=(2, 2),
>>>        dtype="i4",
>>>       )

Set data for a selection of items:

>>> z.set_block_selection((1, 0), 1)
>>> z[...]
array([[0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [1, 1, 0, 0, 0, 0],
       [1, 1, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0]])

For convenience, this functionality is also available via the blocks property. E.g.:

>>> z.blocks[2, 1] = 4
>>> z[...]
array([[0, 0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0, 0],
       [1, 1, 0, 0, 0, 0],
       [1, 1, 0, 0, 0, 0],
       [0, 0, 4, 4, 0, 0],
       [0, 0, 4, 4, 0, 0]])

>>> z.blocks[:, 2] = 7
>>> z[...]
array([[0, 0, 0, 0, 7, 7],
       [0, 0, 0, 0, 7, 7],
       [1, 1, 0, 0, 7, 7],
       [1, 1, 0, 0, 7, 7],
       [0, 0, 4, 4, 7, 7],
       [0, 0, 4, 4, 7, 7]])

set_coordinate_selection( selection: zarr.core.indexing.CoordinateSelection, value: numpy.typing.ArrayLike, *, fields: zarr.core.indexing.Fields | None = None, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → None[source]#

Modify a selection of individual items, by providing the indices (coordinates) for each item to be modified.

Parameters:

selectiontuple: An integer (coordinate) array for each dimension of the array.
valuenpt.ArrayLike: An array-like containing values to be stored into the array.
fieldsstr or sequence of str, optional: For arrays with a structured dtype, one or more fields can be specified to set data for.

See also

get_basic_selection, set_basic_selection, get_mask_selection, set_mask_selection
get_orthogonal_selection, set_orthogonal_selection, get_coordinate_selection
get_block_selection, set_block_selection
vindex, oindex, blocks, __getitem__, __setitem__

Notes

Coordinate indexing is also known as point selection, and is a form of vectorized or inner indexing.

Slices are not supported. Coordinate arrays must be provided for all dimensions of the array.

Examples

Setup a 2-dimensional array:

>>> import zarr
>>> z = zarr.zeros(
>>>        shape=(5, 5),
>>>        store=StorePath(MemoryStore(mode="w")),
>>>        chunk_shape=(5, 5),
>>>        dtype="i4",
>>>       )

Set data for a selection of items:

>>> z.set_coordinate_selection(([1, 4], [1, 4]), 1)
>>> z[...]
array([[0, 0, 0, 0, 0],
       [0, 1, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 1]])

For convenience, this functionality is also available via the vindex property. E.g.:

>>> z.vindex[[1, 4], [1, 4]] = 2
>>> z[...]
array([[0, 0, 0, 0, 0],
       [0, 2, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 2]])

set_mask_selection( mask: zarr.core.indexing.MaskSelection, value: numpy.typing.ArrayLike, *, fields: zarr.core.indexing.Fields | None = None, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → None[source]#

Modify a selection of individual items, by providing a Boolean array of the same shape as the array against which the selection is being made, where True values indicate a selected item.

Parameters:

maskndarray, bool: A Boolean array of the same shape as the array against which the selection is being made.
valuenpt.ArrayLike: An array-like containing values to be stored into the array.
fieldsstr or sequence of str, optional: For arrays with a structured dtype, one or more fields can be specified to set data for.

See also

get_basic_selection, set_basic_selection, get_mask_selection
get_orthogonal_selection, set_orthogonal_selection, get_coordinate_selection
set_coordinate_selection, get_block_selection, set_block_selection
vindex, oindex, blocks, __getitem__, __setitem__

Notes

Mask indexing is a form of vectorized or inner indexing, and is equivalent to coordinate indexing. Internally the mask array is converted to coordinate arrays by calling np.nonzero.

Examples

Setup a 2-dimensional array:

>>> import zarr
>>> z = zarr.zeros(
>>>        shape=(5, 5),
>>>        store=StorePath(MemoryStore(mode="w")),
>>>        chunk_shape=(5, 5),
>>>        dtype="i4",
>>>       )

Set data for a selection of items:

>>> sel = np.zeros_like(z, dtype=bool)
>>> sel[1, 1] = True
>>> sel[4, 4] = True
>>> z.set_mask_selection(sel, 1)
>>> z[...]
array([[0, 0, 0, 0, 0],
       [0, 1, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 1]])

For convenience, this functionality is also available via the vindex property. E.g.:

>>> z.vindex[sel] = 2
>>> z[...]
array([[0, 0, 0, 0, 0],
       [0, 2, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 2]])

set_orthogonal_selection( selection: zarr.core.indexing.OrthogonalSelection, value: numpy.typing.ArrayLike, *, fields: zarr.core.indexing.Fields | None = None, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → None[source]#

Modify data via a selection for each dimension of the array.

Parameters:

selectiontuple: A selection for each dimension of the array. May be any combination of int, slice, integer array or Boolean array.
valuenpt.ArrayLike: An array-like array containing the data to be stored in the array.
fieldsstr or sequence of str, optional: For arrays with a structured dtype, one or more fields can be specified to set data for.
prototypeBufferPrototype, optional: The prototype of the buffer used for setting the data. If not provided, the default buffer prototype is used.

See also

get_basic_selection, set_basic_selection, get_mask_selection, set_mask_selection
get_coordinate_selection, set_coordinate_selection, get_orthogonal_selection
get_block_selection, set_block_selection
vindex, oindex, blocks, __getitem__, __setitem__

Notes

Orthogonal indexing is also known as outer indexing.

Slices with step > 1 are supported, but slices with negative step are not.

Examples

Setup a 2-dimensional array:

>>> import zarr
>>> z = zarr.zeros(
>>>        shape=(5, 5),
>>>        store=StorePath(MemoryStore(mode="w")),
>>>        chunk_shape=(5, 5),
>>>        dtype="i4",
>>>       )

Set data for a selection of rows:

>>> z.set_orthogonal_selection(([1, 4], slice(None)), 1)
>>> z[...]
array([[0, 0, 0, 0, 0],
       [1, 1, 1, 1, 1],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [1, 1, 1, 1, 1]])

Set data for a selection of columns:

>>> z.set_orthogonal_selection((slice(None), [1, 4]), 2)
>>> z[...]
array([[0, 2, 0, 0, 2],
       [1, 2, 1, 1, 2],
       [0, 2, 0, 0, 2],
       [0, 2, 0, 0, 2],
       [1, 2, 1, 1, 2]])

Set data for a selection of rows and columns:

>>> z.set_orthogonal_selection(([1, 4], [1, 4]), 3)
>>> z[...]
array([[0, 2, 0, 0, 2],
       [1, 3, 1, 1, 3],
       [0, 2, 0, 0, 2],
       [0, 2, 0, 0, 2],
       [1, 3, 1, 1, 3]])

Set data from a 2D array:

>>> values = np.arange(10).reshape(2, 5)
>>> z.set_orthogonal_selection(([0, 3], ...), values)
>>> z[...]
array([[0, 1, 2, 3, 4],
       [1, 3, 1, 1, 3],
       [0, 2, 0, 0, 2],
       [5, 6, 7, 8, 9],
       [1, 3, 1, 1, 3]])

For convenience, this functionality is also available via the oindex property. E.g.:

>>> z.oindex[[1, 4], [1, 4]] = 4
>>> z[...]
array([[0, 1, 2, 3, 4],
       [1, 4, 1, 1, 4],
       [0, 2, 0, 0, 2],
       [5, 6, 7, 8, 9],
       [1, 4, 1, 1, 4]])

update_attributes(new_attributes: dict[str, zarr.core.common.JSON]) → Array[source]#

Update the array’s attributes.

Parameters:

new_attributesdict: A dictionary of new attributes to update or add to the array. The keys represent attribute names, and the values must be JSON-compatible.

Returns:

Array: The array with the updated attributes.

Raises:

ValueError: If the attributes are invalid or incompatible with the array’s metadata.

Notes

The updated attributes will be merged with existing attributes, and any conflicts will be overwritten by the new values.

property attrs: zarr.core.attributes.Attributes#

Returns a MutableMapping containing user-defined attributes.

Returns:

attrsMutableMapping: A MutableMapping object containing user-defined attributes.

Notes

Note that attribute values must be JSON serializable.

property basename: str#: Final component of name.

property blocks: zarr.core.indexing.BlockIndex#: Shortcut for blocked chunked indexing, see get_block_selection() and set_block_selection() for documentation and examples.

property cdata_shape: zarr.core.common.ChunkCoords#: The shape of the chunk grid for this array.

property chunks: zarr.core.common.ChunkCoords#

Returns a tuple of integers describing the length of each dimension of a chunk of the array. If sharding is used the inner chunk shape is returned.

Only defined for arrays using using RegularChunkGrid. If array doesn’t use RegularChunkGrid, NotImplementedError is raised.

Returns:

tuple: A tuple of integers representing the length of each dimension of a chunk.

property compressor: numcodecs.abc.Codec | None#: Compressor that is applied to each chunk of the array.

Deprecated since version 3.0.0: array.compressor is deprecated and will be removed in a future release. Use array.compressors instead.

property compressors: tuple[numcodecs.abc.Codec, Ellipsis] | tuple[zarr.abc.codec.BytesBytesCodec, Ellipsis]#: Compressors that are applied to each chunk of the array. Compressors are applied in order, and after any filters are applied (if any are specified) and the data is serialized into bytes.

property dtype: numpy.dtype[Any]#

Returns the NumPy data type.

Returns:

np.dtype: The NumPy data type.

property fill_value: Any#

property filters: tuple[numcodecs.abc.Codec, Ellipsis] | tuple[zarr.abc.codec.ArrayArrayCodec, Ellipsis]#: Filters that are applied to each chunk of the array, in order, before serializing that chunk to bytes.

property info: Any#

Return the statically known information for an array.

Returns:

ArrayInfo

See also

Array.info_complete: All information about a group, including dynamic information like the number of bytes and chunks written.

Examples

>>> arr = zarr.create(shape=(10,), chunks=(2,), dtype="float32")
>>> arr.info
Type               : Array
Zarr format        : 3
Data type          : DataType.float32
Shape              : (10,)
Chunk shape        : (2,)
Order              : C
Read-only          : False
Store type         : MemoryStore
Codecs             : [BytesCodec(endian=<Endian.little: 'little'>)]
No. bytes          : 40

property metadata: zarr.core.metadata.ArrayMetadata#

property name: str#: Array name following h5py convention.

property nbytes: int#

The total number of bytes that can be stored in the chunks of this array.

Notes

This value is calculated by multiplying the number of elements in the array and the size of each element, the latter of which is determined by the dtype of the array. For this reason, nbytes will likely be inaccurate for arrays with variable-length dtypes. It is not possible to determine the size of an array with variable-length elements from the shape and dtype alone.

property nchunks: int#: The number of chunks in the stored representation of this array.

property nchunks_initialized: int#

Calculate the number of chunks that have been initialized, i.e. the number of chunks that have been persisted to the storage backend.

Returns:

nchunks_initializedint: The number of chunks that have been initialized.

Notes

On Array this is a (synchronous) property, unlike asynchronous function AsyncArray.nchunks_initialized().

Examples

>>> arr = await zarr.create(shape=(10,), chunks=(2,))
>>> arr.nchunks_initialized
0
>>> arr[:5] = 1
>>> arr.nchunks_initialized
3

property ndim: int#

Returns the number of dimensions in the array.

Returns:

int: The number of dimensions in the array.

property oindex: zarr.core.indexing.OIndex#: Shortcut for orthogonal (outer) indexing, see get_orthogonal_selection() and set_orthogonal_selection() for documentation and examples.

property order: zarr.core.common.MemoryOrder#

property path: str#: Storage path.

property read_only: bool#

property serializer: None | zarr.abc.codec.ArrayBytesCodec#: Array-to-bytes codec to use for serializing the chunks into bytes.

property shape: zarr.core.common.ChunkCoords#

Returns the shape of the array.

Returns:

ChunkCoords: The shape of the array.

property shards: zarr.core.common.ChunkCoords | None#

Returns a tuple of integers describing the length of each dimension of a shard of the array. Returns None if sharding is not used.

Only defined for arrays using using RegularChunkGrid. If array doesn’t use RegularChunkGrid, NotImplementedError is raised.

Returns:

tuple | None: A tuple of integers representing the length of each dimension of a shard or None if sharding is not used.

property size: int#

Returns the total number of elements in the array.

Returns:

int: Total number of elements in the array.

property store: zarr.abc.store.Store#

property store_path: zarr.storage._common.StorePath#

property vindex: zarr.core.indexing.VIndex#: Shortcut for vectorized (inner) indexing, see get_coordinate_selection(), set_coordinate_selection(), get_mask_selection() and set_mask_selection() for documentation and examples.

class zarr.AsyncArray( metadata: zarr.core.metadata.ArrayV2Metadata | zarr.core.metadata.ArrayV2MetadataDict, store_path: zarr.storage._common.StorePath, config: zarr.core.array_spec.ArrayConfig | None = None, )[source]#

class zarr.AsyncArray( metadata: zarr.core.metadata.ArrayV3Metadata | zarr.core.metadata.ArrayV3MetadataDict, store_path: zarr.storage._common.StorePath, config: zarr.core.array_spec.ArrayConfig | None = None, )

Bases: Generic[zarr.core.metadata.T_ArrayMetadata]

An asynchronous array class representing a chunked array stored in a Zarr store.

Parameters:

metadataArrayMetadata: The metadata of the array.
store_pathStorePath: The path to the Zarr store.
configArrayConfig, optional: The runtime configuration of the array, by default None.

Attributes:

metadataArrayMetadata: The metadata of the array.
store_pathStorePath: The path to the Zarr store.
codec_pipelineCodecPipeline: The codec pipeline used for encoding and decoding chunks.
_configArrayConfig: The runtime configuration of the array.

async append( data: numpy.typing.ArrayLike, axis: int = 0, ) → zarr.core.common.ChunkCoords[source]#

Append data to axis.

Parameters:

dataarray-like: Data to be appended.
axisint: Axis along which to append.

Returns:

new_shapetuple

Notes

The size of all dimensions other than axis must match between this array and data.

classmethod create( store: zarr.storage.StoreLike, *, shape: zarr.core.common.ShapeLike, dtype: numpy.typing.DTypeLike, zarr_format: Literal[2], fill_value: Any | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, chunks: zarr.core.common.ShapeLike | None = None, dimension_separator: Literal['.', '/'] | None = None, order: zarr.core.common.MemoryOrder | None = None, filters: list[dict[str, zarr.core.common.JSON]] | None = None, compressor: dict[str, zarr.core.common.JSON] | None = None, overwrite: bool = False, data: numpy.typing.ArrayLike | None = None, config: zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | None = None, ) → AsyncArray[zarr.core.metadata.ArrayV2Metadata][source]#

classmethod create( store: zarr.storage.StoreLike, *, shape: zarr.core.common.ShapeLike, dtype: numpy.typing.DTypeLike, zarr_format: Literal[3], fill_value: Any | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_shape: zarr.core.common.ShapeLike | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncoding | tuple[Literal['default'], Literal['.', '/']] | tuple[Literal['v2'], Literal['.', '/']] | None = None, codecs: collections.abc.Iterable[zarr.abc.codec.Codec | dict[str, zarr.core.common.JSON]] | None = None, dimension_names: collections.abc.Iterable[str] | None = None, overwrite: bool = False, data: numpy.typing.ArrayLike | None = None, config: zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | None = None, ) → AsyncArray[zarr.core.metadata.ArrayV3Metadata]

classmethod create( store: zarr.storage.StoreLike, *, shape: zarr.core.common.ShapeLike, dtype: numpy.typing.DTypeLike, zarr_format: Literal[3] = 3, fill_value: Any | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_shape: zarr.core.common.ShapeLike | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncoding | tuple[Literal['default'], Literal['.', '/']] | tuple[Literal['v2'], Literal['.', '/']] | None = None, codecs: collections.abc.Iterable[zarr.abc.codec.Codec | dict[str, zarr.core.common.JSON]] | None = None, dimension_names: collections.abc.Iterable[str] | None = None, overwrite: bool = False, data: numpy.typing.ArrayLike | None = None, config: zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | None = None, ) → AsyncArray[zarr.core.metadata.ArrayV3Metadata]

classmethod create( store: zarr.storage.StoreLike, *, shape: zarr.core.common.ShapeLike, dtype: numpy.typing.DTypeLike, zarr_format: zarr.core.common.ZarrFormat, fill_value: Any | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_shape: zarr.core.common.ShapeLike | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncoding | tuple[Literal['default'], Literal['.', '/']] | tuple[Literal['v2'], Literal['.', '/']] | None = None, codecs: collections.abc.Iterable[zarr.abc.codec.Codec | dict[str, zarr.core.common.JSON]] | None = None, dimension_names: collections.abc.Iterable[str] | None = None, chunks: zarr.core.common.ShapeLike | None = None, dimension_separator: Literal['.', '/'] | None = None, order: zarr.core.common.MemoryOrder | None = None, filters: list[dict[str, zarr.core.common.JSON]] | None = None, compressor: dict[str, zarr.core.common.JSON] | None = None, overwrite: bool = False, data: numpy.typing.ArrayLike | None = None, config: zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | None = None, ) → AsyncArray[zarr.core.metadata.ArrayV3Metadata] | AsyncArray[zarr.core.metadata.ArrayV2Metadata]

Async:

Method to create a new asynchronous array instance.

Deprecated since version 3.0.0: Deprecated in favor of zarr.api.asynchronous.create_array().

Parameters:

storeStoreLike

The store where the array will be created.

shapeShapeLike

The shape of the array.

dtypenpt.DTypeLike

The data type of the array.

zarr_formatZarrFormat, optional

The Zarr format version (default is 3).

fill_valueAny, optional

The fill value of the array (default is None).

attributesdict[str, JSON], optional

The attributes of the array (default is None).

chunk_shapeChunkCoords, optional

The shape of the array’s chunks Zarr format 3 only. Zarr format 2 arrays should use chunks instead. If not specified, default are guessed based on the shape and dtype.

chunk_key_encodingChunkKeyEncoding, optional

A specification of how the chunk keys are represented in storage. Zarr format 3 only. Zarr format 2 arrays should use dimension_separator instead. Default is ("default", "/").

codecsSequence of Codecs or dicts, optional

An iterable of Codec or dict serializations of Codecs. The elements of this collection specify the transformation from array values to stored bytes. Zarr format 3 only. Zarr format 2 arrays should use filters and compressor instead.

If no codecs are provided, default codecs will be used:

For numeric arrays, the default is BytesCodec and ZstdCodec.
For Unicode strings, the default is VLenUTF8Codec and ZstdCodec.
For bytes or objects, the default is VLenBytesCodec and ZstdCodec.

These defaults can be changed by modifying the value of array.v3_default_filters, array.v3_default_serializer and array.v3_default_compressors in zarr.core.config.

dimension_namesIterable[str], optional

The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter.

chunksShapeLike, optional

The shape of the array’s chunks. Zarr format 2 only. Zarr format 3 arrays should use chunk_shape instead. If not specified, default are guessed based on the shape and dtype.

dimension_separatorLiteral[“.”, “/”], optional

The dimension separator (default is “.”). Zarr format 2 only. Zarr format 3 arrays should use chunk_key_encoding instead.

orderLiteral[“C”, “F”], optional

The memory of the array (default is “C”). If zarr_format is 2, this parameter sets the memory order of the array. If zarr_format` is 3, then this parameter is deprecated, because memory order is a runtime parameter for Zarr 3 arrays. The recommended way to specify the memory order for Zarr 3 arrays is via the config parameter, e.g. {'config': 'C'}.

filterslist[dict[str, JSON]], optional

Sequence of filters to use to encode chunk data prior to compression. Zarr format 2 only. Zarr format 3 arrays should use codecs instead. If no filters are provided, a default set of filters will be used. These defaults can be changed by modifying the value of array.v2_default_filters in zarr.core.config.

compressordict[str, JSON], optional

The compressor used to compress the data (default is None). Zarr format 2 only. Zarr format 3 arrays should use codecs instead.

If no compressor is provided, a default compressor will be used:

For numeric arrays, the default is ZstdCodec.
For Unicode strings, the default is VLenUTF8Codec.
For bytes or objects, the default is VLenBytesCodec.

These defaults can be changed by modifying the value of array.v2_default_compressor in zarr.core.config.

overwritebool, optional

Whether to raise an error if the store already exists (default is False).

datanpt.ArrayLike, optional

The data to be inserted into the array (default is None).

configArrayConfig or ArrayConfigLike, optional

Runtime configuration for the array.

Returns:

AsyncArray: The created asynchronous array instance.

classmethod from_dict( store_path: zarr.storage._common.StorePath, data: dict[str, zarr.core.common.JSON], ) → AsyncArray[zarr.core.metadata.ArrayV3Metadata] | AsyncArray[zarr.core.metadata.ArrayV2Metadata][source]#

Create a Zarr array from a dictionary, with support for both Zarr format 2 and 3 metadata.

Parameters:

store_pathStorePath: The path within the store where the array should be created.
datadict: A dictionary representing the array data. This dictionary should include necessary metadata for the array, such as shape, dtype, and other attributes. The format of the metadata will determine whether a Zarr format 2 or 3 array is created.

Returns:

AsyncArray[ArrayV3Metadata] or AsyncArray[ArrayV2Metadata]: The created Zarr array, either using Zarr format 2 or 3 metadata based on the provided data.

Raises:

ValueError: If the dictionary data is invalid or incompatible with either Zarr format 2 or 3 array creation.

async getitem( selection: zarr.core.indexing.BasicSelection, *, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → zarr.core.buffer.NDArrayLike[source]#

Asynchronous function that retrieves a subset of the array’s data based on the provided selection.

Parameters:

selectionBasicSelection: A selection object specifying the subset of data to retrieve.
prototypeBufferPrototype, optional: A buffer prototype to use for the retrieved data (default is None).

Returns:

NDArrayLike: The retrieved subset of the array’s data.

Examples

>>> import zarr
>>>  store = zarr.storage.MemoryStore(mode='w')
>>>  async_arr = await zarr.api.asynchronous.create_array(
...      store=store,
...      shape=(100,100),
...      chunks=(10,10),
...      dtype='i4',
...      fill_value=0)
<AsyncArray memory://... shape=(100, 100) dtype=int32>
>>> await async_arr.getitem((0,1)) 
array(0, dtype=int32)

async info_complete() → Any[source]#

Return all the information for an array, including dynamic information like a storage size.

In addition to the static information, this provides

The count of chunks initialized
The sum of the bytes written

Returns:

ArrayInfo

See also

AsyncArray.info: A property giving just the statically known information about an array.

async nbytes_stored() → int[source]#

async nchunks_initialized() → int[source]#

Calculate the number of chunks that have been initialized, i.e. the number of chunks that have been persisted to the storage backend.

Returns:

nchunks_initializedint: The number of chunks that have been initialized.

Notes

On AsyncArray this is an asynchronous method, unlike the (synchronous) property Array.nchunks_initialized.

Examples

>>> arr = await zarr.api.asynchronous.create(shape=(10,), chunks=(2,))
>>> await arr.nchunks_initialized()
0
>>> await arr.setitem(slice(5), 1)
>>> await arr.nchunks_initialized()
3

classmethod open( store: zarr.storage.StoreLike, zarr_format: zarr.core.common.ZarrFormat | None = 3, ) → AsyncArray[zarr.core.metadata.ArrayV3Metadata] | AsyncArray[zarr.core.metadata.ArrayV2Metadata][source]#

Async:

Async method to open an existing Zarr array from a given store.

Parameters:

storeStoreLike: The store containing the Zarr array.
zarr_formatZarrFormat | None, optional: The Zarr format version (default is 3).

Returns:

AsyncArray: The opened Zarr array.

Examples

>>> import zarr
>>>  store = zarr.storage.MemoryStore(mode='w')
>>>  async_arr = await AsyncArray.open(store) 
<AsyncArray memory://... shape=(100, 100) dtype=int32>

async resize( new_shape: zarr.core.common.ShapeLike, delete_outside_chunks: bool = True, ) → None[source]#

Asynchronously resize the array to a new shape.

Parameters:

new_shapeChunkCoords: The desired new shape of the array.
delete_outside_chunksbool, optional: If True (default), chunks that fall outside the new shape will be deleted. If False, the data in those chunks will be preserved.

Returns:

AsyncArray: The resized array.

Raises:

ValueError: If the new shape is incompatible with the current array’s chunking configuration.

Notes

This method is asynchronous and should be awaited.

async setitem( selection: zarr.core.indexing.BasicSelection, value: numpy.typing.ArrayLike, prototype: zarr.core.buffer.BufferPrototype | None = None, ) → None[source]#

Asynchronously set values in the array using basic indexing.

Parameters:

selectionBasicSelection: The selection defining the region of the array to set.
valuenumpy.typing.ArrayLike: The values to be written into the selected region of the array.
prototypeBufferPrototype or None, optional: A prototype buffer that defines the structure and properties of the array chunks being modified. If None, the default buffer prototype is used. Default is None.

Returns:

None: This method does not return any value.

Raises:

IndexError: If the selection is out of bounds for the array.
ValueError: If the values are not compatible with the array’s dtype or shape.

Notes

This method is asynchronous and should be awaited.
Supports basic indexing, where the selection is contiguous and does not involve advanced indexing.

async update_attributes(new_attributes: dict[str, zarr.core.common.JSON]) → Self[source]#

Asynchronously update the array’s attributes.

Parameters:

new_attributesdict of str to JSON: A dictionary of new attributes to update or add to the array. The keys represent attribute names, and the values must be JSON-compatible.

Returns:

AsyncArray: The array with the updated attributes.

Raises:

ValueError: If the attributes are invalid or incompatible with the array’s metadata.

Notes

This method is asynchronous and should be awaited.
The updated attributes will be merged with existing attributes, and any conflicts will be overwritten by the new values.

property attrs: dict[str, zarr.core.common.JSON]#

Returns the attributes of the array.

Returns:

dict: Attributes of the array

property basename: str#

Final component of name.

Returns:

str: The basename or final component of the array name.

property cdata_shape: zarr.core.common.ChunkCoords#

The shape of the chunk grid for this array.

Returns:

Tuple[int]: The shape of the chunk grid for this array.

property chunks: zarr.core.common.ChunkCoords#

Returns the chunk shape of the Array. If sharding is used the inner chunk shape is returned.

Only defined for arrays using using RegularChunkGrid. If array doesn’t use RegularChunkGrid, NotImplementedError is raised.

Returns:

ChunkCoords:: The chunk shape of the Array.

codec_pipeline: zarr.abc.codec.CodecPipeline#

property compressor: numcodecs.abc.Codec | None#: Compressor that is applied to each chunk of the array.

Deprecated since version 3.0.0: array.compressor is deprecated and will be removed in a future release. Use array.compressors instead.

property compressors: tuple[numcodecs.abc.Codec, Ellipsis] | tuple[zarr.abc.codec.BytesBytesCodec, Ellipsis]#: Compressors that are applied to each chunk of the array. Compressors are applied in order, and after any filters are applied (if any are specified) and the data is serialized into bytes.

property dtype: numpy.dtype[Any]#

Returns the data type of the array.

Returns:

np.dtype: Data type of the array

property filters: tuple[numcodecs.abc.Codec, Ellipsis] | tuple[zarr.abc.codec.ArrayArrayCodec, Ellipsis]#: Filters that are applied to each chunk of the array, in order, before serializing that chunk to bytes.

property info: Any#

Return the statically known information for an array.

Returns:

ArrayInfo

See also

AsyncArray.info_complete: All information about a group, including dynamic information like the number of bytes and chunks written.

Examples

>>> arr = await zarr.api.asynchronous.create(
...     path="array", shape=(3, 4, 5), chunks=(2, 2, 2))
... )
>>> arr.info
Type               : Array
Zarr format        : 3
Data type          : DataType.float64
Shape              : (3, 4, 5)
Chunk shape        : (2, 2, 2)
Order              : C
Read-only          : False
Store type         : MemoryStore
Codecs             : [{'endian': <Endian.little: 'little'>}]
No. bytes          : 480

metadata: zarr.core.metadata.T_ArrayMetadata#

property name: str#

Array name following h5py convention.

Returns:

str: The name of the array.

property nbytes: int#

The total number of bytes that can be stored in the chunks of this array.

Notes

This value is calculated by multiplying the number of elements in the array and the size of each element, the latter of which is determined by the dtype of the array. For this reason, nbytes will likely be inaccurate for arrays with variable-length dtypes. It is not possible to determine the size of an array with variable-length elements from the shape and dtype alone.

property nchunks: int#

The number of chunks in the stored representation of this array.

Returns:

int: The total number of chunks in the array.

property ndim: int#

Returns the number of dimensions in the Array.

Returns:

int: The number of dimensions in the Array.

property order: zarr.core.common.MemoryOrder#

Returns the memory order of the array.

Returns:

bool: Memory order of the array

property path: str#

Storage path.

Returns:

str: The path to the array in the Zarr store.

property read_only: bool#

Returns True if the array is read-only.

Returns:

bool: True if the array is read-only

property serializer: zarr.abc.codec.ArrayBytesCodec | None#: Array-to-bytes codec to use for serializing the chunks into bytes.

property shape: zarr.core.common.ChunkCoords#

Returns the shape of the Array.

Returns:

tuple: The shape of the Array.

property shards: zarr.core.common.ChunkCoords | None#

Returns the shard shape of the Array. Returns None if sharding is not used.

Only defined for arrays using using RegularChunkGrid. If array doesn’t use RegularChunkGrid, NotImplementedError is raised.

Returns:

ChunkCoords:: The shard shape of the Array.

property size: int#

Returns the total number of elements in the array

Returns:

int: Total number of elements in the array

property store: zarr.abc.store.Store#

store_path: zarr.storage._common.StorePath#

class zarr.AsyncGroup[source]#

Asynchronous Group object.

async array_keys() → collections.abc.AsyncGenerator[str, None][source]#: Iterate over array names.

async array_values() → collections.abc.AsyncGenerator[zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata], None][source]#: Iterate over array values.

async arrays() → collections.abc.AsyncGenerator[tuple[str, zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata]], None][source]#: Iterate over arrays.

async contains(member: str) → bool[source]#

Check if a member exists in the group.

Parameters:

memberstr: Member name.

Returns:

bool

async create_array( name: str, *, shape: zarr.core.common.ShapeLike, dtype: numpy.typing.DTypeLike, chunks: zarr.core.common.ChunkCoords | Literal['auto'] = 'auto', shards: zarr.core.array.ShardsLike | None = None, filters: zarr.core.array.FiltersLike = 'auto', compressors: zarr.core.array.CompressorsLike = 'auto', compressor: zarr.core.array.CompressorLike = 'auto', serializer: zarr.core.array.SerializerLike = 'auto', fill_value: Any | None = 0, order: zarr.core.common.MemoryOrder | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncoding | zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | None = None, dimension_names: collections.abc.Iterable[str] | None = None, storage_options: dict[str, Any] | None = None, overwrite: bool = False, config: zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | None = None, ) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Create an array within this group.

This method lightly wraps zarr.core.array.create_array().

Parameters:

namestr

The name of the array relative to the group. If path is None, the array will be located at the root of the store.

shapeChunkCoords

Shape of the array.

dtypenpt.DTypeLike

Data type of the array.

chunksChunkCoords, optional

Chunk shape of the array. If not specified, default are guessed based on the shape and dtype.

shardsChunkCoords, optional

Shard shape of the array. The default value of None results in no sharding at all.

filtersIterable[Codec], optional

Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes.

For Zarr format 3, a “filter” is a codec that takes an array and returns an array, and these values must be instances of ArrayArrayCodec, or dict representations of ArrayArrayCodec. If no filters are provided, a default set of filters will be used. These defaults can be changed by modifying the value of array.v3_default_filters in zarr.core.config. Use None to omit default filters.

For Zarr format 2, a “filter” can be any numcodecs codec; you should ensure that the the order if your filters is consistent with the behavior of each filter. If no filters are provided, a default set of filters will be used. These defaults can be changed by modifying the value of array.v2_default_filters in zarr.core.config. Use None to omit default filters.

compressorsIterable[Codec], optional

List of compressors to apply to the array. Compressors are applied in order, and after any filters are applied (if any are specified) and the data is serialized into bytes.

For Zarr format 3, a “compressor” is a codec that takes a bytestream, and returns another bytestream. Multiple compressors my be provided for Zarr format 3. If no compressors are provided, a default set of compressors will be used. These defaults can be changed by modifying the value of array.v3_default_compressors in zarr.core.config. Use None to omit default compressors.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single compressor may be provided for Zarr format 2. If no compressor is provided, a default compressor will be used. in zarr.core.config. Use None to omit the default compressor.

compressorCodec, optional

Deprecated in favor of compressors.

serializerdict[str, JSON] | ArrayBytesCodec, optional

Array-to-bytes codec to use for encoding the array data. Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion. If no serializer is provided, a default serializer will be used. These defaults can be changed by modifying the value of array.v3_default_serializer in zarr.core.config.

fill_valueAny, optional

Fill value for the array.

order{“C”, “F”}, optional

The memory of the array (default is “C”). For Zarr format 2, this parameter sets the memory order of the array. For Zarr format 3, this parameter is deprecated, because memory order is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory order for Zarr format 3 arrays is via the config parameter, e.g. {'config': 'C'}. If no order is provided, a default order will be used. This default can be changed by modifying the value of array.order in zarr.core.config.

attributesdict, optional

Attributes for the array.

chunk_key_encodingChunkKeyEncoding, optional

A specification of how the chunk keys are represented in storage. For Zarr format 3, the default is {"name": "default", "separator": "/"}}. For Zarr format 2, the default is {"name": "v2", "separator": "."}}.

dimension_namesIterable[str], optional

The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter.

storage_optionsdict, optional

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.

overwritebool, default False

Whether to overwrite an array with the same name in the store, if one exists.

configArrayConfig or ArrayConfigLike, optional

Runtime configuration for the array.

Returns:

AsyncArray

async create_dataset(

name: str,

*,

shape: zarr.core.common.ShapeLike,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Create an array.

Deprecated since version 3.0.0: The h5py compatibility methods will be removed in 3.1.0. Use AsyncGroup.create_array instead.

Arrays are known as “datasets” in HDF5 terminology. For compatibility with h5py, Zarr groups also implement the zarr.AsyncGroup.require_dataset() method.

Parameters:

namestr: Array name.
**kwargsdict: Additional arguments passed to zarr.AsyncGroup.create_array().

Returns:

aAsyncArray

async create_group( name: str, *, overwrite: bool = False, attributes: dict[str, Any] | None = None, ) → AsyncGroup[source]#

Create a sub-group.

Parameters:

namestr: Group name.
overwritebool, optional: If True, do not raise an error if the group already exists.
attributesdict, optional: Group attributes.

Returns:

gAsyncGroup

async delitem(key: str) → None[source]#

Delete a group member.

Parameters:

keystr: Array or group name

async empty(

*,

name: str,

shape: zarr.core.common.ChunkCoords,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Create an empty array in this Group.

Parameters:

namestr: Name of the array.
shapeint or tuple of int: Shape of the empty array.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Notes

The contents of an empty Zarr array are not defined. On attempting to retrieve data from an empty Zarr array, any values may be returned, and these are not guaranteed to be stable from one access to the next.

async empty_like(

*,

name: str,

data: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Create an empty sub-array like data.

Parameters:

namestr: Name of the array.
dataarray-like: The array to create an empty array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

AsyncArray: The new array.

classmethod from_dict( store_path: zarr.storage.StorePath, data: dict[str, Any], ) → AsyncGroup[source]#

classmethod from_store( store: zarr.storage.StoreLike, *, attributes: dict[str, Any] | None = None, overwrite: bool = False, zarr_format: zarr.core.common.ZarrFormat = 3, ) → AsyncGroup[source]#

Async:

async full(

*,

name: str,

shape: zarr.core.common.ChunkCoords,

fill_value: Any | None,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Create an array, with “fill_value” being used as the default value for uninitialized portions of the array.

Parameters:

namestr: Name of the array.
shapeint or tuple of int: Shape of the empty array.
fill_valuescalar: Value to fill the array with.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

AsyncArray: The new array.

async full_like(

*,

name: str,

data: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Create a sub-array like data filled with the fill_value of data .

Parameters:

namestr: Name of the array.
dataarray-like: The array to create the new array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

AsyncArray: The new array.

async get( key: str, default: DefaultT | None = None, ) → zarr.core.array.AsyncArray[Any] | AsyncGroup | DefaultT | None[source]#

Obtain a group member, returning default if not found.

Parameters:

keystr: Group member name.
defaultobject: Default value to return if key is not found (default: None).

Returns:

object: Group member (AsyncArray or AsyncGroup) or default if not found.

async getitem( key: str, ) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata] | AsyncGroup[source]#

Get a subarray or subgroup from the group.

Parameters:

keystr: Array or group name

Returns:

AsyncArray or AsyncGroup

async group_keys() → collections.abc.AsyncGenerator[str, None][source]#: Iterate over group names.

async group_values() → collections.abc.AsyncGenerator[AsyncGroup, None][source]#: Iterate over group values.

async groups() → collections.abc.AsyncGenerator[tuple[str, AsyncGroup], None][source]#: Iterate over subgroups.

async info_complete() → Any[source]#

Return all the information for a group.

This includes dynamic information like the number of child Groups or Arrays. If this group doesn’t contain consolidated metadata then this will need to read from the backing Store.

Returns:

GroupInfo

See also

AsyncGroup.info

async keys() → collections.abc.AsyncGenerator[str, None][source]#: Iterate over member names.

async members( max_depth: int | None = 0, ) → collections.abc.AsyncGenerator[tuple[str, zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata] | AsyncGroup], None][source]#

Returns an AsyncGenerator over the arrays and groups contained in this group. This method requires that store_path.store supports directory listing.

The results are not guaranteed to be ordered.

Parameters:

max_depthint, default 0: The maximum number of levels of the hierarchy to include. By default, (max_depth=0) only immediate children are included. Set max_depth=None to include all nodes, and some positive integer to consider children within that many levels of the root Group.

Returns:

path:: A string giving the path to the target, relative to the Group self.
value: AsyncArray or AsyncGroup: The AsyncArray or AsyncGroup that is a child of self.

abstract move(source: str, dest: str) → None[source]#

Async:

Move a sub-group or sub-array from one path to another.

Notes

Not implemented

async nmembers(max_depth: int | None = 0) → int[source]#

Count the number of members in this group.

Parameters:

max_depthint, default 0: The maximum number of levels of the hierarchy to include. By default, (max_depth=0) only immediate children are included. Set max_depth=None to include all nodes, and some positive integer to consider children within that many levels of the root Group.

Returns:

countint

async ones(

*,

name: str,

shape: zarr.core.common.ChunkCoords,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Create an array, with one being used as the default value for uninitialized portions of the array.

Parameters:

namestr: Name of the array.
shapeint or tuple of int: Shape of the empty array.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

AsyncArray: The new array.

async ones_like(

*,

name: str,

data: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Create a sub-array of ones like data.

Parameters:

namestr: Name of the array.
dataarray-like: The array to create the new array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

AsyncArray: The new array.

classmethod open( store: zarr.storage.StoreLike, zarr_format: zarr.core.common.ZarrFormat | None = 3, use_consolidated: bool | str | None = None, ) → AsyncGroup[source]#

Async:

Open a new AsyncGroup

Parameters:

storeStoreLike

zarr_format{2, 3}, optional

use_consolidatedbool or str, default None

Whether to use consolidated metadata.

By default, consolidated metadata is used if it’s present in the store (in the zarr.json for Zarr format 3 and in the .zmetadata file for Zarr format 2).

To explicitly require consolidated metadata, set use_consolidated=True, which will raise an exception if consolidated metadata is not found.

To explicitly not use consolidated metadata, set use_consolidated=False, which will fall back to using the regular, non consolidated metadata.

Zarr format 2 allowed configuring the key storing the consolidated metadata (.zmetadata by default). Specify the custom key as use_consolidated to load consolidated metadata from a non-default key.

async require_array(

name: str,

*,

shape: zarr.core.common.ShapeLike,

dtype: numpy.typing.DTypeLike = None,

exact: bool = False,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Obtain an array, creating if it doesn’t exist.

Other kwargs are as per zarr.AsyncGroup.create_dataset().

Parameters:

namestr: Array name.
shapeint or tuple of ints: Array shape.
dtypestr or dtype, optional: NumPy dtype.
exactbool, optional: If True, require dtype to match exactly. If false, require dtype can be cast from array dtype.

Returns:

aAsyncArray

async require_dataset(

name: str,

*,

shape: zarr.core.common.ChunkCoords,

dtype: numpy.typing.DTypeLike = None,

exact: bool = False,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Obtain an array, creating if it doesn’t exist.

Deprecated since version 3.0.0: The h5py compatibility methods will be removed in 3.1.0. Use AsyncGroup.require_dataset instead.

Arrays are known as “datasets” in HDF5 terminology. For compatibility with h5py, Zarr groups also implement the zarr.AsyncGroup.create_dataset() method.

Other kwargs are as per zarr.AsyncGroup.create_dataset().

Parameters:

namestr: Array name.
shapeint or tuple of ints: Array shape.
dtypestr or dtype, optional: NumPy dtype.
exactbool, optional: If True, require dtype to match exactly. If false, require dtype can be cast from array dtype.

Returns:

aAsyncArray

async require_group(name: str, overwrite: bool = False) → AsyncGroup[source]#

Obtain a sub-group, creating one if it doesn’t exist.

Parameters:

namestr: Group name.
overwritebool, optional: Overwrite any existing group with given name if present.

Returns:

gAsyncGroup

async require_groups(*names: str) → tuple[AsyncGroup, Ellipsis][source]#

Convenience method to require multiple groups in a single call.

Parameters:

*namesstr: Group names.

Returns:

Tuple[AsyncGroup, …]

async setitem(key: str, value: Any) → None[source]#

Fastpath for creating a new array New arrays will be created with default array settings for the array type.

Parameters:

keystr: Array name
valuearray-like: Array data

async tree(expand: bool | None = None, level: int | None = None) → Any[source]#

Return a tree-like representation of a hierarchy.

This requires the optional rich dependency.

Parameters:

expandbool, optional: This keyword is not yet supported. A NotImplementedError is raised if it’s used.
levelint, optional: The maximum depth below this Group to display in the tree.

Returns:

TreeRepr: A pretty-printable object displaying the hierarchy.

async update_attributes(new_attributes: dict[str, Any]) → AsyncGroup[source]#

Update group attributes.

Parameters:

new_attributesdict: New attributes to set on the group.

Returns:

selfAsyncGroup

async zeros(

*,

name: str,

shape: zarr.core.common.ChunkCoords,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Create an array, with zero being used as the default value for uninitialized portions of the array.

Parameters:

namestr: Name of the array.
shapeint or tuple of int: Shape of the empty array.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

AsyncArray: The new array.

async zeros_like(

*,

name: str,

data: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV2Metadata] | zarr.core.array.AsyncArray[zarr.core.metadata.ArrayV3Metadata][source]#

Create a sub-array of zeros like data.

Parameters:

namestr: Name of the array.
dataarray-like: The array to create the new array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

AsyncArray: The new array.

property attrs: dict[str, Any]#

property basename: str#: Final component of name.

property info: Any#

Return a visual representation of the statically known information about a group.

Note that this doesn’t include dynamic information, like the number of child Groups or Arrays.

Returns:

GroupInfo

See also

AsyncGroup.info_complete: All information about a group, including dynamic information

metadata: GroupMetadata#

property name: str#: Group name following h5py convention.

property path: str#: Storage path.

property read_only: bool#

property store: zarr.abc.store.Store#

store_path: zarr.storage.StorePath#

property synchronizer: None#

class zarr.Group[source]#

Bases: zarr.core.sync.SyncMixin

array( name: str, *, shape: zarr.core.common.ShapeLike, dtype: numpy.typing.DTypeLike, chunks: zarr.core.common.ChunkCoords | Literal['auto'] = 'auto', shards: zarr.core.common.ChunkCoords | Literal['auto'] | None = None, filters: zarr.core.array.FiltersLike = 'auto', compressors: zarr.core.array.CompressorsLike = 'auto', compressor: zarr.core.array.CompressorLike = None, serializer: zarr.core.array.SerializerLike = 'auto', fill_value: Any | None = 0, order: zarr.core.common.MemoryOrder | None = 'C', attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncoding | zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | None = None, dimension_names: collections.abc.Iterable[str] | None = None, storage_options: dict[str, Any] | None = None, overwrite: bool = False, config: zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | None = None, data: numpy.typing.ArrayLike | None = None, ) → zarr.core.array.Array[source]#

Create an array within this group.

Deprecated since version 3.0.0: Use Group.create_array instead.

This method lightly wraps zarr.core.array.create_array().

Parameters:

namestr

The name of the array relative to the group. If path is None, the array will be located at the root of the store.

shapeChunkCoords

Shape of the array.

dtypenpt.DTypeLike

Data type of the array.

chunksChunkCoords, optional

Chunk shape of the array. If not specified, default are guessed based on the shape and dtype.

shardsChunkCoords, optional

Shard shape of the array. The default value of None results in no sharding at all.

filtersIterable[Codec], optional

Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes.

For Zarr format 3, a “filter” is a codec that takes an array and returns an array, and these values must be instances of ArrayArrayCodec, or dict representations of ArrayArrayCodec. If no filters are provided, a default set of filters will be used. These defaults can be changed by modifying the value of array.v3_default_filters in zarr.core.config. Use None to omit default filters.

For Zarr format 2, a “filter” can be any numcodecs codec; you should ensure that the the order if your filters is consistent with the behavior of each filter. If no filters are provided, a default set of filters will be used. These defaults can be changed by modifying the value of array.v2_default_filters in zarr.core.config. Use None to omit default filters.

compressorsIterable[Codec], optional

List of compressors to apply to the array. Compressors are applied in order, and after any filters are applied (if any are specified) and the data is serialized into bytes.

For Zarr format 3, a “compressor” is a codec that takes a bytestream, and returns another bytestream. Multiple compressors my be provided for Zarr format 3. If no compressors are provided, a default set of compressors will be used. These defaults can be changed by modifying the value of array.v3_default_compressors in zarr.core.config. Use None to omit default compressors.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single compressor may be provided for Zarr format 2. If no compressor is provided, a default compressor will be used. in zarr.core.config. Use None to omit the default compressor.

compressorCodec, optional

Deprecated in favor of compressors.

serializerdict[str, JSON] | ArrayBytesCodec, optional

Array-to-bytes codec to use for encoding the array data. Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion. If no serializer is provided, a default serializer will be used. These defaults can be changed by modifying the value of array.v3_default_serializer in zarr.core.config.

fill_valueAny, optional

Fill value for the array.

order{“C”, “F”}, optional

The memory of the array (default is “C”). For Zarr format 2, this parameter sets the memory order of the array. For Zarr format 3, this parameter is deprecated, because memory order is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory order for Zarr format 3 arrays is via the config parameter, e.g. {'config': 'C'}. If no order is provided, a default order will be used. This default can be changed by modifying the value of array.order in zarr.core.config.

attributesdict, optional

Attributes for the array.

chunk_key_encodingChunkKeyEncoding, optional

A specification of how the chunk keys are represented in storage. For Zarr format 3, the default is {"name": "default", "separator": "/"}}. For Zarr format 2, the default is {"name": "v2", "separator": "."}}.

dimension_namesIterable[str], optional

The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter.

storage_optionsdict, optional

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.

overwritebool, default False

Whether to overwrite an array with the same name in the store, if one exists.

configArrayConfig or ArrayConfigLike, optional

Runtime configuration for the array.

dataarray_like

The data to fill the array with.

Returns:

AsyncArray

array_keys() → collections.abc.Generator[str, None][source]#

Return an iterator over group member names.

Examples

>>> import zarr
>>> group = zarr.group()
>>> group.create_array("subarray", shape=(10,), chunks=(10,))
>>> for name in group.array_keys():
...     print(name)
subarray

array_values() → collections.abc.Generator[zarr.core.array.Array, None][source]#

Return an iterator over group members.

Examples

>>> import zarr
>>> group = zarr.group()
>>> group.create_array("subarray", shape=(10,), chunks=(10,))
>>> for subarray in group.array_values():
...     print(subarray)
<Array memory://140198565357056/subarray shape=(10,) dtype=float64>

arrays() → collections.abc.Generator[tuple[str, zarr.core.array.Array], None][source]#

Return the sub-arrays of this group as a generator of (name, array) pairs

Examples

>>> import zarr
>>> group = zarr.group()
>>> group.create_array("subarray", shape=(10,), chunks=(10,))
>>> for name, subarray in group.arrays():
...     print(name, subarray)
subarray <Array memory://140198565357056/subarray shape=(10,) dtype=float64>

create(*args: Any, **kwargs: Any) → zarr.core.array.Array[source]#

create_array( name: str, *, shape: zarr.core.common.ShapeLike, dtype: numpy.typing.DTypeLike, chunks: zarr.core.common.ChunkCoords | Literal['auto'] = 'auto', shards: zarr.core.array.ShardsLike | None = None, filters: zarr.core.array.FiltersLike = 'auto', compressors: zarr.core.array.CompressorsLike = 'auto', compressor: zarr.core.array.CompressorLike = 'auto', serializer: zarr.core.array.SerializerLike = 'auto', fill_value: Any | None = 0, order: zarr.core.common.MemoryOrder | None = 'C', attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncoding | zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | None = None, dimension_names: collections.abc.Iterable[str] | None = None, storage_options: dict[str, Any] | None = None, overwrite: bool = False, config: zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | None = None, ) → zarr.core.array.Array[source]#

Create an array within this group.

This method lightly wraps zarr.core.array.create_array().

Parameters:

namestr

The name of the array relative to the group. If path is None, the array will be located at the root of the store.

shapeChunkCoords

Shape of the array.

dtypenpt.DTypeLike

Data type of the array.

chunksChunkCoords, optional

Chunk shape of the array. If not specified, default are guessed based on the shape and dtype.

shardsChunkCoords, optional

Shard shape of the array. The default value of None results in no sharding at all.

filtersIterable[Codec], optional

Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes.

For Zarr format 3, a “filter” is a codec that takes an array and returns an array, and these values must be instances of ArrayArrayCodec, or dict representations of ArrayArrayCodec. If no filters are provided, a default set of filters will be used. These defaults can be changed by modifying the value of array.v3_default_filters in zarr.core.config. Use None to omit default filters.

For Zarr format 2, a “filter” can be any numcodecs codec; you should ensure that the the order if your filters is consistent with the behavior of each filter. If no filters are provided, a default set of filters will be used. These defaults can be changed by modifying the value of array.v2_default_filters in zarr.core.config. Use None to omit default filters.

compressorsIterable[Codec], optional

List of compressors to apply to the array. Compressors are applied in order, and after any filters are applied (if any are specified) and the data is serialized into bytes.

For Zarr format 3, a “compressor” is a codec that takes a bytestream, and returns another bytestream. Multiple compressors my be provided for Zarr format 3. If no compressors are provided, a default set of compressors will be used. These defaults can be changed by modifying the value of array.v3_default_compressors in zarr.core.config. Use None to omit default compressors.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single compressor may be provided for Zarr format 2. If no compressor is provided, a default compressor will be used. in zarr.core.config. Use None to omit the default compressor.

compressorCodec, optional

Deprecated in favor of compressors.

serializerdict[str, JSON] | ArrayBytesCodec, optional

Array-to-bytes codec to use for encoding the array data. Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion. If no serializer is provided, a default serializer will be used. These defaults can be changed by modifying the value of array.v3_default_serializer in zarr.core.config.

fill_valueAny, optional

Fill value for the array.

order{“C”, “F”}, optional

The memory of the array (default is “C”). For Zarr format 2, this parameter sets the memory order of the array. For Zarr format 3, this parameter is deprecated, because memory order is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory order for Zarr format 3 arrays is via the config parameter, e.g. {'config': 'C'}. If no order is provided, a default order will be used. This default can be changed by modifying the value of array.order in zarr.core.config.

attributesdict, optional

Attributes for the array.

chunk_key_encodingChunkKeyEncoding, optional

A specification of how the chunk keys are represented in storage. For Zarr format 3, the default is {"name": "default", "separator": "/"}}. For Zarr format 2, the default is {"name": "v2", "separator": "."}}.

dimension_namesIterable[str], optional

The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter.

storage_optionsdict, optional

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.

overwritebool, default False

Whether to overwrite an array with the same name in the store, if one exists.

configArrayConfig or ArrayConfigLike, optional

Runtime configuration for the array.

Returns:

AsyncArray

create_dataset(name: str, **kwargs: Any) → zarr.core.array.Array[source]#

Create an array.

Deprecated since version 3.0.0: The h5py compatibility methods will be removed in 3.1.0. Use Group.create_array instead.

Arrays are known as “datasets” in HDF5 terminology. For compatibility with h5py, Zarr groups also implement the zarr.Group.require_dataset() method.

Parameters:

namestr: Array name.
**kwargsdict: Additional arguments passed to zarr.Group.create_array()

Returns:

aArray

create_group(name: str, **kwargs: Any) → Group[source]#

Create a sub-group.

Parameters:

namestr: Name of the new subgroup.

Returns:

Group

Examples

>>> import zarr
>>> group = zarr.group()
>>> subgroup = group.create_group("subgroup")
>>> subgroup
<Group memory://132270269438272/subgroup>

empty(

*,

name: str,

shape: zarr.core.common.ChunkCoords,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an empty array in this Group.

Parameters:

namestr: Name of the array.
shapeint or tuple of int: Shape of the empty array.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Notes

The contents of an empty Zarr array are not defined. On attempting to retrieve data from an empty Zarr array, any values may be returned, and these are not guaranteed to be stable from one access to the next.

empty_like(

*,

name: str,

data: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an empty sub-array like data.

Parameters:

namestr: Name of the array.
dataarray-like: The array to create an empty array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

classmethod from_store( store: zarr.storage.StoreLike, *, attributes: dict[str, Any] | None = None, zarr_format: zarr.core.common.ZarrFormat = 3, overwrite: bool = False, ) → Group[source]#

Instantiate a group from an initialized store.

Parameters:

storeStoreLike: StoreLike containing the Group.
attributesdict, optional: A dictionary of JSON-serializable values with user-defined attributes.
zarr_format{2, 3}, optional: Zarr storage format version.
overwritebool, optional: If True, do not raise an error if the group already exists.

Returns:

Group: Group instantiated from the store.

Raises:

ContainsArrayError, ContainsGroupError, ContainsArrayAndGroupError

full(

*,

name: str,

shape: zarr.core.common.ChunkCoords,

fill_value: Any | None,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an array, with “fill_value” being used as the default value for uninitialized portions of the array.

Parameters:

namestr: Name of the array.
shapeint or tuple of int: Shape of the empty array.
fill_valuescalar: Value to fill the array with.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

full_like(

*,

name: str,

data: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create a sub-array like data filled with the fill_value of data .

Parameters:

namestr: Name of the array.
dataarray-like: The array to create the new array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

get( path: str, default: DefaultT | None = None, ) → zarr.core.array.Array | Group | DefaultT | None[source]#

Obtain a group member, returning default if not found.

Parameters:

pathstr: Group member name.
defaultobject: Default value to return if key is not found (default: None).

Returns:

object: Group member (Array or Group) or default if not found.

Examples

>>> import zarr
>>> group = Group.from_store(zarr.storage.MemoryStore()
>>> group.create_array(name="subarray", shape=(10,), chunks=(10,))
>>> group.create_group(name="subgroup")
>>> group.get("subarray")
<Array memory://132270269438272/subarray shape=(10,) dtype=float64>
>>> group.get("subgroup")
<Group memory://132270269438272/subgroup>
>>> group.get("nonexistent", None)

group_keys() → collections.abc.Generator[str, None][source]#

Return an iterator over group member names.

Examples

>>> import zarr
>>> group = zarr.group()
>>> group.create_group("subgroup")
>>> for name in group.group_keys():
...     print(name)
subgroup

group_values() → collections.abc.Generator[Group, None][source]#

Return an iterator over group members.

Examples

>>> import zarr
>>> group = zarr.group()
>>> group.create_group("subgroup")
>>> for subgroup in group.group_values():
...     print(subgroup)
<Group memory://132270269438272/subgroup>

groups() → collections.abc.Generator[tuple[str, Group], None][source]#

Return the sub-groups of this group as a generator of (name, group) pairs.

Examples

>>> import zarr
>>> group = zarr.group()
>>> group.create_group("subgroup")
>>> for name, subgroup in group.groups():
...     print(name, subgroup)
subgroup <Group memory://132270269438272/subgroup>

info_complete() → Any[source]#

Return information for a group.

If this group doesn’t contain consolidated metadata then this will need to read from the backing Store.

Returns:

GroupInfo

See also

Group.info

keys() → collections.abc.Generator[str, None][source]#

Return an iterator over group member names.

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> d1 = g1.create_array('baz', shape=(10,), chunks=(10,))
>>> d2 = g1.create_array('quux', shape=(10,), chunks=(10,))
>>> for name in g1.keys():
...     print(name)
baz
bar
foo
quux

members( max_depth: int | None = 0, ) → tuple[tuple[str, zarr.core.array.Array | Group], Ellipsis][source]#: Return the sub-arrays and sub-groups of this group as a tuple of (name, array | group) pairs

move(source: str, dest: str) → None[source]#

Move a sub-group or sub-array from one path to another.

Notes

Not implemented

nmembers(max_depth: int | None = 0) → int[source]#

Count the number of members in this group.

Parameters:

max_depthint, default 0: The maximum number of levels of the hierarchy to include. By default, (max_depth=0) only immediate children are included. Set max_depth=None to include all nodes, and some positive integer to consider children within that many levels of the root Group.

Returns:

countint

ones(

*,

name: str,

shape: zarr.core.common.ChunkCoords,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an array, with one being used as the default value for uninitialized portions of the array.

Parameters:

namestr: Name of the array.
shapeint or tuple of int: Shape of the empty array.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

ones_like(

*,

name: str,

data: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create a sub-array of ones like data.

Parameters:

namestr: Name of the array.
dataarray-like: The array to create the new array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

classmethod open( store: zarr.storage.StoreLike, zarr_format: zarr.core.common.ZarrFormat | None = 3, ) → Group[source]#

Open a group from an initialized store.

Parameters:

storeStoreLike: Store containing the Group.
zarr_format{2, 3, None}, optional: Zarr storage format version.

Returns:

Group: Group instantiated from the store.

require_array(

name: str,

*,

shape: zarr.core.common.ShapeLike,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Obtain an array, creating if it doesn’t exist.

Other kwargs are as per zarr.Group.create_array().

Parameters:

namestr: Array name.
**kwargs: See zarr.Group.create_array().

Returns:

aArray

require_dataset(

name: str,

*,

shape: zarr.core.common.ShapeLike,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Obtain an array, creating if it doesn’t exist.

Deprecated since version 3.0.0: The h5py compatibility methods will be removed in 3.1.0. Use Group.require_array instead.

Arrays are known as “datasets” in HDF5 terminology. For compatibility with h5py, Zarr groups also implement the zarr.Group.create_dataset() method.

Other kwargs are as per zarr.Group.create_dataset().

Parameters:

namestr: Array name.
**kwargs: See zarr.Group.create_dataset().

Returns:

aArray

require_group(name: str, **kwargs: Any) → Group[source]#

Obtain a sub-group, creating one if it doesn’t exist.

Parameters:

namestr: Group name.

Returns:

gGroup

require_groups(*names: str) → tuple[Group, Ellipsis][source]#

Convenience method to require multiple groups in a single call.

Parameters:

*namesstr: Group names.

Returns:

groupstuple of Groups

tree(expand: bool | None = None, level: int | None = None) → Any[source]#

Return a tree-like representation of a hierarchy.

This requires the optional rich dependency.

Parameters:

expandbool, optional: This keyword is not yet supported. A NotImplementedError is raised if it’s used.
levelint, optional: The maximum depth below this Group to display in the tree.

Returns:

TreeRepr: A pretty-printable object displaying the hierarchy.

update_attributes(new_attributes: dict[str, Any]) → Group[source]#

Update the attributes of this group.

Examples

>>> import zarr
>>> group = zarr.group()
>>> group.update_attributes({"foo": "bar"})
>>> group.attrs.asdict()
{'foo': 'bar'}

async update_attributes_async(new_attributes: dict[str, Any]) → Group[source]#

Update the attributes of this group.

Examples

>>> import zarr
>>> group = zarr.group()
>>> await group.update_attributes_async({"foo": "bar"})
>>> group.attrs.asdict()
{'foo': 'bar'}

zeros(

*,

name: str,

shape: zarr.core.common.ChunkCoords,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an array, with zero being used as the default value for uninitialized portions of the array.

Parameters:

namestr: Name of the array.
shapeint or tuple of int: Shape of the empty array.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

zeros_like(

*,

name: str,

data: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create a sub-array of zeros like data.

Parameters:

namestr: Name of the array.
dataarray-like: The array to create the new array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

property attrs: zarr.core.attributes.Attributes#: Attributes of this Group

property basename: str#: Final component of name.

property info: Any#

Return the statically known information for a group.

Returns:

GroupInfo

See also

Group.info_complete: All information about a group, including dynamic information like the children members.

property metadata: GroupMetadata#: Group metadata.

property name: str#: Group name following h5py convention.

property path: str#: Storage path.

property read_only: bool#

property store: zarr.abc.store.Store#

property store_path: zarr.storage.StorePath#: Path-like interface for the Store.

property synchronizer: None#

zarr.array(data: numpy.typing.ArrayLike, **kwargs: Any) → zarr.core.array.Array[source]#

Create an array filled with data.

Parameters:

dataarray_like: The data to fill the array with.
**kwargs: Passed through to create().

Returns:

arrayArray: The new array.

zarr.consolidate_metadata( store: zarr.storage.StoreLike, path: str | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, ) → zarr.core.group.Group[source]#

Consolidate the metadata of all nodes in a hierarchy.

Upon completion, the metadata of the root node in the Zarr hierarchy will be updated to include all the metadata of child nodes.

Parameters:

storeStoreLike

The store-like object whose metadata you wish to consolidate.

pathstr, optional

A path to a group in the store to consolidate at. Only children below that group will be consolidated.

By default, the root node is used so all the metadata in the store is consolidated.

zarr_format{2, 3, None}, optional

The zarr format of the hierarchy. By default the zarr format is inferred.

Returns:

group: Group: The group, with the consolidated_metadata field set to include the metadata of each child node.

zarr.copy(*args: Any, **kwargs: Any) → tuple[int, int, int][source]#

zarr.copy_all(*args: Any, **kwargs: Any) → tuple[int, int, int][source]#

zarr.copy_store(*args: Any, **kwargs: Any) → tuple[int, int, int][source]#

zarr.create(

shape: zarr.core.common.ChunkCoords | int,

*,

chunks: zarr.core.common.ChunkCoords | int | bool | None = None,

dtype: numpy.typing.DTypeLike | None = None,

compressor: dict[str, zarr.core.common.JSON] | None = None,

fill_value: Any | None = 0,

order: zarr.core.common.MemoryOrder | None = None,

store: str | zarr.storage.StoreLike | None = None,

synchronizer: Any | None = None,

overwrite: bool = False,

path: zarr.api.asynchronous.PathLike | None = None,

chunk_store: zarr.storage.StoreLike | None = None,

filters: list[dict[str, zarr.core.common.JSON]] | None = None,

cache_metadata: bool | None = None,

cache_attrs: bool | None = None,

read_only: bool | None = None,

object_codec: zarr.abc.codec.Codec | None = None,

dimension_separator: Literal['.', '/'] | None = None,

write_empty_chunks: bool | None = None,

zarr_version: zarr.core.common.ZarrFormat | None = None,

zarr_format: zarr.core.common.ZarrFormat | None = None,

meta_array: Any | None = None,

attributes: dict[str, zarr.core.common.JSON] | None = None,

chunk_shape: zarr.core.common.ChunkCoords | int | None = None,

chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncoding | tuple[Literal['default'], Literal['.', '/']] | tuple[Literal['v2'], Literal['.', '/']] | None = None,

codecs: collections.abc.Iterable[zarr.abc.codec.Codec | dict[str, zarr.core.common.JSON]] | None = None,

dimension_names: collections.abc.Iterable[str] | None = None,

storage_options: dict[str, Any] | None = None,

config: zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | None = None,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an array.

Parameters:

shapeint or tuple of ints: Array shape.
chunksint or tuple of ints, optional: Chunk shape. If True, will be guessed from shape and dtype. If False, will be set to shape, i.e., single chunk for the whole array. If an int, the chunk size in each dimension will be given by the value of chunks. Default is True.
dtypestr or dtype, optional: NumPy dtype.
compressorCodec, optional: Primary compressor.
fill_valueobject: Default value to use for uninitialized portions of the array.
order{‘C’, ‘F’}, optional: Deprecated in favor of the config keyword argument. Pass {'order': <value>} to create instead of using this parameter. Memory layout to be used within each chunk. If not specified, the array.order parameter in the global config will be used.
storeStore or str: Store or path to directory in file system or name of zip file.
synchronizerobject, optional: Array synchronizer.
overwritebool, optional: If True, delete all pre-existing data in store at path before creating the array.
pathstr, optional: Path under which array is stored.
chunk_storeMutableMapping, optional: Separate storage for chunks. If not provided, store will be used for storage of both chunks and metadata.
filterssequence of Codecs, optional: Sequence of filters to use to encode chunk data prior to compression.
cache_metadatabool, optional: If True, array configuration metadata will be cached for the lifetime of the object. If False, array metadata will be reloaded prior to all data access and modification operations (may incur overhead depending on storage and data access pattern).
cache_attrsbool, optional: If True (default), user attributes will be cached for attribute read operations. If False, user attributes are reloaded from the store prior to all attribute read operations.
read_onlybool, optional: True if array should be protected against modification.
object_codecCodec, optional: A codec to encode object arrays, only needed if dtype=object.
dimension_separator{‘.’, ‘/’}, optional: Separator placed between the dimensions of a chunk.
write_empty_chunksbool, optional: Deprecated in favor of the config keyword argument. Pass {'write_empty_chunks': <value>} to create instead of using this parameter. If True, all chunks will be stored regardless of their contents. If False, each chunk is compared to the array’s fill value prior to storing. If a chunk is uniformly equal to the fill value, then that chunk is not be stored, and the store entry for that chunk’s key is deleted.
zarr_format{2, 3, None}, optional: The zarr format to use when saving.
meta_arrayarray-like, optional: An array instance to use for determining arrays to create and return to users. Use numpy.empty(()) by default.
storage_optionsdict: If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
configArrayConfig or ArrayConfigLike, optional: Runtime configuration of the array. If provided, will override the default values from zarr.config.array.

Returns:

zArray: The array.

zarr.create_array( store: str | zarr.storage.StoreLike, *, name: str | None = None, shape: zarr.core.common.ShapeLike, dtype: numpy.typing.DTypeLike, chunks: zarr.core.common.ChunkCoords | Literal['auto'] = 'auto', shards: zarr.core.array.ShardsLike | None = None, filters: zarr.core.array.FiltersLike = 'auto', compressors: zarr.core.array.CompressorsLike = 'auto', serializer: zarr.core.array.SerializerLike = 'auto', fill_value: Any | None = None, order: zarr.core.common.MemoryOrder | None = None, zarr_format: zarr.core.common.ZarrFormat | None = 3, attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_key_encoding: zarr.core.chunk_key_encodings.ChunkKeyEncoding | zarr.core.chunk_key_encodings.ChunkKeyEncodingLike | None = None, dimension_names: collections.abc.Iterable[str] | None = None, storage_options: dict[str, Any] | None = None, overwrite: bool = False, config: zarr.core.array_spec.ArrayConfig | zarr.core.array_spec.ArrayConfigLike | None = None, ) → zarr.core.array.Array[source]#

Create an array.

This function wraps zarr.core.array.create_array().

Parameters:

storestr or Store

Store or path to directory in file system or name of zip file.

namestr or None, optional

The name of the array within the store. If name is None, the array will be located at the root of the store.

shapeChunkCoords

Shape of the array.

dtypenpt.DTypeLike

Data type of the array.

chunksChunkCoords, optional

Chunk shape of the array. If not specified, default are guessed based on the shape and dtype.

shardsChunkCoords, optional

Shard shape of the array. The default value of None results in no sharding at all.

filtersIterable[Codec], optional

Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes.

For Zarr format 3, a “filter” is a codec that takes an array and returns an array, and these values must be instances of ArrayArrayCodec, or dict representations of ArrayArrayCodec. If no filters are provided, a default set of filters will be used. These defaults can be changed by modifying the value of array.v3_default_filters in zarr.core.config. Use None to omit default filters.

For Zarr format 2, a “filter” can be any numcodecs codec; you should ensure that the the order if your filters is consistent with the behavior of each filter. If no filters are provided, a default set of filters will be used. These defaults can be changed by modifying the value of array.v2_default_filters in zarr.core.config. Use None to omit default filters.

compressorsIterable[Codec], optional

List of compressors to apply to the array. Compressors are applied in order, and after any filters are applied (if any are specified) and the data is serialized into bytes.

For Zarr format 3, a “compressor” is a codec that takes a bytestream, and returns another bytestream. Multiple compressors my be provided for Zarr format 3. If no compressors are provided, a default set of compressors will be used. These defaults can be changed by modifying the value of array.v3_default_compressors in zarr.core.config. Use None to omit default compressors.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single compressor may be provided for Zarr format 2. If no compressor is provided, a default compressor will be used. in zarr.core.config. Use None to omit the default compressor.

serializerdict[str, JSON] | ArrayBytesCodec, optional

Array-to-bytes codec to use for encoding the array data. Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion. If no serializer is provided, a default serializer will be used. These defaults can be changed by modifying the value of array.v3_default_serializer in zarr.core.config.

fill_valueAny, optional

Fill value for the array.

order{“C”, “F”}, optional

The memory of the array (default is “C”). For Zarr format 2, this parameter sets the memory order of the array. For Zarr format 3, this parameter is deprecated, because memory order is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory order for Zarr format 3 arrays is via the config parameter, e.g. {'config': 'C'}. If no order is provided, a default order will be used. This default can be changed by modifying the value of array.order in zarr.core.config.

zarr_format{2, 3}, optional

The zarr format to use when saving.

attributesdict, optional

Attributes for the array.

chunk_key_encodingChunkKeyEncoding, optional

A specification of how the chunk keys are represented in storage. For Zarr format 3, the default is {"name": "default", "separator": "/"}}. For Zarr format 2, the default is {"name": "v2", "separator": "."}}.

dimension_namesIterable[str], optional

The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter.

storage_optionsdict, optional

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.

overwritebool, default False

Whether to overwrite an array with the same name in the store, if one exists.

configArrayConfig or ArrayConfigLike, optional

Runtime configuration for the array.

Returns:

Array: The array.

Examples

>>> import zarr
>>> store = zarr.storage.MemoryStore(mode='w')
>>> arr = await zarr.create_array(
>>>     store=store,
>>>     shape=(100,100),
>>>     chunks=(10,10),
>>>     dtype='i4',
>>>     fill_value=0)
<Array memory://140349042942400 shape=(100, 100) dtype=int32>

zarr.create_group( store: zarr.storage.StoreLike, *, path: str | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, overwrite: bool = False, attributes: dict[str, Any] | None = None, storage_options: dict[str, Any] | None = None, ) → zarr.core.group.Group[source]#

Create a group.

Parameters:

storeStore or str: Store or path to directory in file system.
pathstr, optional: Group path within store.
overwritebool, optional: If True, pre-existing data at path will be deleted before creating the group.
zarr_format{2, 3, None}, optional: The zarr format to use when saving. If no zarr_format is provided, the default format will be used. This default can be changed by modifying the value of default_zarr_format in zarr.core.config.
storage_optionsdict: If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.

Returns:

Group: The new group.

zarr.empty(

shape: zarr.core.common.ChunkCoords,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an empty array.

Parameters:

shapeint or tuple of int: Shape of the empty array.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

Notes

The contents of an empty Zarr array are not defined. On attempting to retrieve data from an empty Zarr array, any values may be returned, and these are not guaranteed to be stable from one access to the next.

zarr.empty_like(

a: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an empty array like another array.

Parameters:

aarray-like: The array to create an empty array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

zarr.full(

shape: zarr.core.common.ChunkCoords,

fill_value: Any,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an array with a default fill value.

Parameters:

shapeint or tuple of int: Shape of the empty array.
fill_valuescalar: Fill value.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

zarr.full_like(

a: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create a filled array like another array.

Parameters:

aarray-like: The array to create an empty array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

zarr.group( store: zarr.storage.StoreLike | None = None, *, overwrite: bool = False, chunk_store: zarr.storage.StoreLike | None = None, cache_attrs: bool | None = None, synchronizer: Any | None = None, path: str | None = None, zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, meta_array: Any | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, storage_options: dict[str, Any] | None = None, ) → zarr.core.group.Group[source]#

Create a group.

Parameters:

storeStore or str, optional: Store or path to directory in file system.
overwritebool, optional: If True, delete any pre-existing data in store at path before creating the group.
chunk_storeStore, optional: Separate storage for chunks. If not provided, store will be used for storage of both chunks and metadata.
cache_attrsbool, optional: If True (default), user attributes will be cached for attribute read operations. If False, user attributes are reloaded from the store prior to all attribute read operations.
synchronizerobject, optional: Array synchronizer.
pathstr, optional: Group path within store.
meta_arrayarray-like, optional: An array instance to use for determining arrays to create and return to users. Use numpy.empty(()) by default.
zarr_format{2, 3, None}, optional: The zarr format to use when saving.
storage_optionsdict: If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.

Returns:

gGroup: The new group.

zarr.load( store: zarr.storage.StoreLike, path: str | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, zarr_version: zarr.core.common.ZarrFormat | None = None, ) → zarr.core.buffer.NDArrayLike | dict[str, zarr.core.buffer.NDArrayLike][source]#

Load data from an array or group into memory.

Parameters:

storeStore or str: Store or path to directory in file system or name of zip file.
pathstr or None, optional: The path within the store from which to load.

Returns:

out: If the path contains an array, out will be a numpy array. If the path contains a group, out will be a dict-like object where keys are array names and values are numpy arrays.

See also

save, savez

Notes

If loading data from a group of arrays, data will not be immediately loaded into memory. Rather, arrays will be loaded into memory as they are requested.

zarr.ones(

shape: zarr.core.common.ChunkCoords,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an array with a fill value of one.

Parameters:

shapeint or tuple of int: Shape of the empty array.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

zarr.ones_like(

a: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an array of ones like another array.

Parameters:

aarray-like: The array to create an empty array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

zarr.open(

store: zarr.storage.StoreLike | None = None,

*,

mode: zarr.core.common.AccessModeLiteral = 'a',

zarr_version: zarr.core.common.ZarrFormat | None = None,

zarr_format: zarr.core.common.ZarrFormat | None = None,

path: str | None = None,

storage_options: dict[str, Any] | None = None,

**kwargs: Any,

) → zarr.core.array.Array | zarr.core.group.Group[source]#

Open a group or array using file-mode-like semantics.

Parameters:

storeStore or str, optional: Store or path to directory in file system or name of zip file.
mode{‘r’, ‘r+’, ‘a’, ‘w’, ‘w-‘}, optional: Persistence mode: ‘r’ means read only (must exist); ‘r+’ means read/write (must exist); ‘a’ means read/write (create if doesn’t exist); ‘w’ means create (overwrite if exists); ‘w-’ means create (fail if exists).
zarr_format{2, 3, None}, optional: The zarr format to use when saving.
pathstr or None, optional: The path within the store to open.
storage_optionsdict: If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
**kwargs: Additional parameters are passed through to zarr.api.asynchronous.open_array() or zarr.api.asynchronous.open_group().

Returns:

zarray or group: Return type depends on what exists in the given store.

zarr.open_array(

store: zarr.storage.StoreLike | None = None,

*,

zarr_version: zarr.core.common.ZarrFormat | None = None,

path: zarr.api.asynchronous.PathLike = '',

storage_options: dict[str, Any] | None = None,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Open an array using file-mode-like semantics.

Parameters:

storeStore or str: Store or path to directory in file system or name of zip file.
zarr_version{2, 3, None}, optional: The zarr format to use when saving.
pathstr, optional: Path in store to array.
storage_optionsdict: If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
**kwargs: Any keyword arguments to pass to create.

Returns:

AsyncArray: The opened array.

zarr.open_consolidated(

*args: Any,

use_consolidated: Literal[True] = True,

**kwargs: Any,

) → zarr.core.group.Group[source]#: Alias for open_group() with use_consolidated=True.

zarr.open_group( store: zarr.storage.StoreLike | None = None, *, mode: zarr.core.common.AccessModeLiteral = 'a', cache_attrs: bool | None = None, synchronizer: Any = None, path: str | None = None, chunk_store: zarr.storage.StoreLike | None = None, storage_options: dict[str, Any] | None = None, zarr_version: zarr.core.common.ZarrFormat | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, meta_array: Any | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, use_consolidated: bool | str | None = None, ) → zarr.core.group.Group[source]#

Open a group using file-mode-like semantics.

Parameters:

storeStore, str, or mapping, optional

Store or path to directory in file system or name of zip file.

Strings are interpreted as paths on the local file system and used as the root argument to zarr.storage.LocalStore.

Dictionaries are used as the store_dict argument in zarr.storage.MemoryStore`.

By default (store=None) a new zarr.storage.MemoryStore is created.

mode{‘r’, ‘r+’, ‘a’, ‘w’, ‘w-‘}, optional

Persistence mode: ‘r’ means read only (must exist); ‘r+’ means read/write (must exist); ‘a’ means read/write (create if doesn’t exist); ‘w’ means create (overwrite if exists); ‘w-’ means create (fail if exists).

cache_attrsbool, optional

If True (default), user attributes will be cached for attribute read operations. If False, user attributes are reloaded from the store prior to all attribute read operations.

synchronizerobject, optional

Array synchronizer.

pathstr, optional

Group path within store.

chunk_storeStore or str, optional

Store or path to directory in file system or name of zip file.

storage_optionsdict

If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.

meta_arrayarray-like, optional

An array instance to use for determining arrays to create and return to users. Use numpy.empty(()) by default.

attributesdict

A dictionary of JSON-serializable values with user-defined attributes.

use_consolidatedbool or str, default None

Whether to use consolidated metadata.

By default, consolidated metadata is used if it’s present in the store (in the zarr.json for Zarr format 3 and in the .zmetadata file for Zarr format 2).

To explicitly require consolidated metadata, set use_consolidated=True, which will raise an exception if consolidated metadata is not found.

To explicitly not use consolidated metadata, set use_consolidated=False, which will fall back to using the regular, non consolidated metadata.

Zarr format 2 allows configuring the key storing the consolidated metadata (.zmetadata by default). Specify the custom key as use_consolidated to load consolidated metadata from a non-default key.

Returns:

gGroup: The new group.

zarr.open_like(

a: zarr.api.asynchronous.ArrayLike,

path: str,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Open a persistent array like another array.

Parameters:

aArray: The shape and data-type of a define these same attributes of the returned array.
pathstr: The path to the new array.
**kwargs: Any keyword arguments to pass to the array constructor.

Returns:

AsyncArray: The opened array.

zarr.save(

store: zarr.storage.StoreLike,

*args: zarr.core.buffer.NDArrayLike,

zarr_version: zarr.core.common.ZarrFormat | None = None,

zarr_format: zarr.core.common.ZarrFormat | None = None,

path: str | None = None,

**kwargs: Any,

) → None[source]#

Save an array or group of arrays to the local file system.

Parameters:

storeStore or str: Store or path to directory in file system or name of zip file.
*argsndarray: NumPy arrays with data to save.
zarr_format{2, 3, None}, optional: The zarr format to use when saving.
pathstr or None, optional: The path within the group where the arrays will be saved.
**kwargs: NumPy arrays with data to save.

zarr.save_array(

store: zarr.storage.StoreLike,

arr: zarr.core.buffer.NDArrayLike,

*,

zarr_version: zarr.core.common.ZarrFormat | None = None,

zarr_format: zarr.core.common.ZarrFormat | None = None,

path: str | None = None,

storage_options: dict[str, Any] | None = None,

**kwargs: Any,

) → None[source]#

Save a NumPy array to the local file system.

Follows a similar API to the NumPy save() function.

Parameters:

storeStore or str: Store or path to directory in file system or name of zip file.
arrndarray: NumPy array with data to save.
zarr_format{2, 3, None}, optional: The zarr format to use when saving.
pathstr or None, optional: The path within the store where the array will be saved.
storage_optionsdict: If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
**kwargs: Passed through to create(), e.g., compressor.

zarr.save_group(

store: zarr.storage.StoreLike,

*args: zarr.core.buffer.NDArrayLike,

zarr_version: zarr.core.common.ZarrFormat | None = None,

zarr_format: zarr.core.common.ZarrFormat | None = None,

path: str | None = None,

storage_options: dict[str, Any] | None = None,

**kwargs: zarr.core.buffer.NDArrayLike,

) → None[source]#

Save several NumPy arrays to the local file system.

Follows a similar API to the NumPy savez()/savez_compressed() functions.

Parameters:

storeStore or str: Store or path to directory in file system or name of zip file.
*argsndarray: NumPy arrays with data to save.
zarr_format{2, 3, None}, optional: The zarr format to use when saving.
pathstr or None, optional: Path within the store where the group will be saved.
storage_optionsdict: If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.
**kwargs: NumPy arrays with data to save.

zarr.tree( grp: zarr.core.group.Group, expand: bool | None = None, level: int | None = None, ) → Any[source]#

Provide a rich display of the hierarchy.

Deprecated since version 3.0.0: zarr.tree() is deprecated and will be removed in a future release. Use group.tree() instead.

Parameters:

grpGroup: Zarr or h5py group.
expandbool, optional: Only relevant for HTML representation. If True, tree will be fully expanded.
levelint, optional: Maximum depth to descend into hierarchy.

Returns:

TreeRepr: A pretty-printable object displaying the hierarchy.

zarr.zeros(

shape: zarr.core.common.ChunkCoords,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an array with a fill value of zero.

Parameters:

shapeint or tuple of int: Shape of the empty array.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

zarr.zeros_like(

a: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array[source]#

Create an array of zeros like another array.

Parameters:

aarray-like: The array to create an empty array like.
**kwargs: Keyword arguments passed to zarr.api.asynchronous.create().

Returns:

Array: The new array.

zarr.config#

zarr#

Submodules#

Attributes#

Classes#

Functions#

Package Contents#

This Page