zarr.api.synchronous#

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_hierarchy`(→ collections.abc.Iterator[tuple[str, ...)	Create a complete zarr hierarchy from a collection of metadata objects.
`empty`(→ zarr.core.array.Array)	Create an empty array with the specified shape. The contents will be filled with the
`empty_like`(→ zarr.core.array.Array)	Create an empty array like another array. The contents will be filled with the
`from_array`(→ zarr.core.array.Array)	Create an array from an existing array or array-like.
`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`(...)	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.

Module Contents#

zarr.api.synchronous.array(

data: numpy.typing.ArrayLike | zarr.core.array.Array,

**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.api.synchronous.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.api.synchronous.copy(*args: Any, **kwargs: Any) → tuple[int, int, int][source]#

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

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

zarr.api.synchronous.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.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.
configArrayConfigLike, optional: Runtime configuration of the array. If provided, will override the default values from zarr.config.array.

Returns:

zArray: The array.

zarr.api.synchronous.create_array( store: str | zarr.storage.StoreLike, *, name: str | None = None, shape: zarr.core.common.ShapeLike | None = None, dtype: numpy.typing.DTypeLike | None = None, data: numpy.ndarray[Any, numpy.dtype[Any]] | None = None, 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.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.ArrayConfigLike | None = None, write_data: bool = True, ) → 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, optional

Shape of the array. Can be None if data is provided.

dtypenpt.DTypeLike, optional

Data type of the array. Can be None if data is provided.

datanp.ndarray, optional

Array-like data to use for initializing the array. If this parameter is provided, the shape and dtype parameters must be identical to data.shape and data.dtype, or None.

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.

configArrayConfigLike, optional

Runtime configuration for the array.

write_databool

If a pre-existing array-like object was provided to this function via the data parameter then write_data determines whether the values in that array-like object should be written to the Zarr array created by this function. If write_data is False, then the array will be left empty.

Returns:

Array: The array.

Examples

>>> import zarr
>>> store = zarr.storage.MemoryStore()
>>> 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.api.synchronous.create_hierarchy( *, store: zarr.abc.store.Store, nodes: dict[str, zarr.core.group.GroupMetadata | zarr.core.metadata.ArrayV2Metadata | zarr.core.metadata.ArrayV3Metadata], overwrite: bool = False, ) → collections.abc.Iterator[tuple[str, zarr.core.group.Group | zarr.core.array.Array]][source]#

Create a complete zarr hierarchy from a collection of metadata objects.

This function will parse its input to ensure that the hierarchy is complete. Any implicit groups will be inserted as needed. For example, an input like `{'a/b': GroupMetadata}` will be parsed to `{'': GroupMetadata, 'a': GroupMetadata, 'b': Groupmetadata}`

After input parsing, this function then creates all the nodes in the hierarchy concurrently.

Arrays and Groups are yielded in the order they are created. This order is not stable and should not be relied on.

Parameters:

storeStore

The storage backend to use.

nodesdict[str, GroupMetadata | ArrayV3Metadata | ArrayV2Metadata]

A dictionary defining the hierarchy. The keys are the paths of the nodes in the hierarchy, relative to the root of the Store. The root of the store can be specified with the empty string ''. The values are instances of GroupMetadata or ArrayMetadata. Note that all values must have the same zarr_format – it is an error to mix zarr versions in the same hierarchy.

Leading “/” characters from keys will be removed.

overwritebool

Whether to overwrite existing nodes. Defaults to False, in which case an error is raised instead of overwriting an existing array or group.

This function will not erase an existing group unless that group is explicitly named in nodes. If nodes defines implicit groups, e.g. {`'a/b/c': GroupMetadata}, and a group already exists at path a, then this function will leave the group at a as-is.

Yields:

tuple[str, Group | Array]: This function yields (path, node) pairs, in the order the nodes were created.

Examples

>>> from zarr import create_hierarchy
>>> from zarr.storage import MemoryStore
>>> from zarr.core.group import GroupMetadata

>>> store = MemoryStore()
>>> nodes = {'a': GroupMetadata(attributes={'name': 'leaf'})}
>>> nodes_created = dict(create_hierarchy(store=store, nodes=nodes))
>>> print(nodes)
# {'a': GroupMetadata(attributes={'name': 'leaf'}, zarr_format=3, consolidated_metadata=None, node_type='group')}

zarr.api.synchronous.empty(

shape: zarr.core.common.ChunkCoords,

**kwargs: Any,

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

Create an empty array with the specified shape. The contents will be filled with the array’s fill value or zeros if no fill value is provided.

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.api.synchronous.empty_like(

a: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

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

Create an empty array like another array. The contents will be filled with the array’s fill value or zeros if no fill value is provided.

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.

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.api.synchronous.from_array( store: str | zarr.storage.StoreLike, *, data: zarr.core.array.Array | numpy.typing.ArrayLike, write_data: bool = True, name: str | None = None, chunks: Literal['auto', 'keep'] | zarr.core.common.ChunkCoords = 'keep', shards: zarr.core.array.ShardsLike | None | Literal['keep'] = 'keep', filters: zarr.core.array.FiltersLike | Literal['keep'] = 'keep', compressors: zarr.core.array.CompressorsLike | Literal['keep'] = 'keep', serializer: zarr.core.array.SerializerLike | Literal['keep'] = 'keep', fill_value: Any | None = None, order: zarr.core.common.MemoryOrder | None = None, zarr_format: zarr.core.common.ZarrFormat | None = None, attributes: dict[str, zarr.core.common.JSON] | None = None, chunk_key_encoding: 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.ArrayConfigLike | None = None, ) → zarr.core.array.Array[source]#

Create an array from an existing array or array-like.

Parameters:

storestr or Store

Store or path to directory in file system or name of zip file for the new array.

dataArray | array-like

The array to copy.

write_databool, default True

Whether to copy the data from the input array to the new array. If write_data is False, the new array will be created with the same metadata as the input array, but without any data.

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.

chunksChunkCoords or “auto” or “keep”, optional

Chunk shape of the array. Following values are supported:

“auto”: Automatically determine the chunk shape based on the array’s shape and dtype.
“keep”: Retain the chunk shape of the data array if it is a zarr Array.
ChunkCoords: A tuple of integers representing the chunk shape.

If not specified, defaults to “keep” if data is a zarr Array, otherwise “auto”.

shardsChunkCoords, optional

Shard shape of the array. Following values are supported:

“auto”: Automatically determine the shard shape based on the array’s shape and chunk shape.
“keep”: Retain the shard shape of the data array if it is a zarr Array.
ChunkCoords: A tuple of integers representing the shard shape.
None: No sharding.

If not specified, defaults to “keep” if data is a zarr Array, otherwise None.

filtersIterable[Codec] or “auto” or “keep”, 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.

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.

Following values are supported:

Iterable[Codec]: List of filters to apply to the array.
“auto”: Automatically determine the filters based on the array’s dtype.
“keep”: Retain the filters of the data array if it is a zarr Array.

If no filters are provided, defaults to “keep” if data is a zarr Array, otherwise “auto”.

compressorsIterable[Codec] or “auto” or “keep”, 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.

For Zarr format 2, a “compressor” can be any numcodecs codec. Only a single compressor may be provided for Zarr format 2.

Following values are supported:

Iterable[Codec]: List of compressors to apply to the array.
“auto”: Automatically determine the compressors based on the array’s dtype.
“keep”: Retain the compressors of the input array if it is a zarr Array.

If no compressors are provided, defaults to “keep” if data is a zarr Array, otherwise “auto”.

serializerdict[str, JSON] | ArrayBytesCodec or “auto” or “keep”, 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.

Following values are supported:

dict[str, JSON]: A dict representation of an ArrayBytesCodec.
ArrayBytesCodec: An instance of ArrayBytesCodec.
“auto”: a default serializer will be used. These defaults can be changed by modifying the value of array.v3_default_serializer in zarr.core.config.
“keep”: Retain the serializer of the input array if it is a zarr Array.

fill_valueAny, optional

Fill value for the array. If not specified, defaults to the fill value of the data 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 not specified, defaults to the memory order of the data array.

zarr_format{2, 3}, optional

The zarr format to use when saving. If not specified, defaults to the zarr format of the data array.

attributesdict, optional

Attributes for the array. If not specified, defaults to the attributes of the data 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": "."}}. If not specified and the data array has the same zarr format as the target array, the chunk key encoding of the data array is used.

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. If not specified, defaults to the dimension names of the data array.

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

Create an array from an existing Array:

>>> import zarr
>>> store = zarr.storage.MemoryStore()
>>> store2 = zarr.storage.LocalStore('example.zarr')
>>> arr = zarr.create_array(
>>>     store=store,
>>>     shape=(100,100),
>>>     chunks=(10,10),
>>>     dtype='int32',
>>>     fill_value=0)
>>> arr2 = zarr.from_array(store2, data=arr)
<Array file://example.zarr shape=(100, 100) dtype=int32>

Create an array from an existing NumPy array:

>>> import numpy as np
>>> arr3 = zarr.from_array(
        zarr.storage.MemoryStore(),
>>>     data=np.arange(10000, dtype='i4').reshape(100, 100),
>>> )
<Array memory://125477403529984 shape=(100, 100) dtype=int32>

Create an array from any array-like object:

>>> arr4 = zarr.from_array(
>>>     zarr.storage.MemoryStore(),
>>>     data=[[1, 2], [3, 4]],
>>> )
<Array memory://125477392154368 shape=(2, 2) dtype=int64>
>>> arr4[...]
array([[1, 2],[3, 4]])

Create an array from an existing Array without copying the data:

>>> arr5 = zarr.from_array(
>>>     zarr.storage.MemoryStore(),
>>>     data=arr4,
>>>     write_data=False,
>>> )
<Array memory://140678602965568 shape=(2, 2) dtype=int64>
>>> arr5[...]
array([[0, 0],[0, 0]])

zarr.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.NDArrayLikeOrScalar | dict[str, zarr.core.buffer.NDArrayLikeOrScalar][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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous.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.api.synchronous#

Functions#

Module Contents#

This Page