zarr.creation

Helpers for creating arrays.

Warning

This sub-module is deprecated. All functions here are defined in the top level zarr namespace instead.

Functions

array(→ zarr.core.array.Array)	Create an array filled with data.
create(→ zarr.core.array.Array)	Create an array.
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
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.
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_array(→ zarr.core.array.Array)	Open an array using file-mode-like semantics.
open_like(→ zarr.core.array.Array)	Open a persistent array like another array.
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.creation.array(

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

**kwargs: Any,

) → zarr.core.array.Array

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.creation.create(

shape: tuple[int, Ellipsis] | int,

*,

chunks: tuple[int, Ellipsis] | int | bool | None = None,

dtype: zarr.core.dtype.ZDTypeLike | None = None,

compressor: zarr.core.array.CompressorLike = 'auto',

fill_value: Any | None = DEFAULT_FILL_VALUE,

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

store: 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: collections.abc.Iterable[dict[str, zarr.core.common.JSON] | zarr.abc.numcodec.Numcodec] | 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: tuple[int, Ellipsis] | 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: zarr.core.common.DimensionNames = None,

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

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

**kwargs: Any,

) → zarr.core.array.Array

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 to compress chunk data. Zarr format 2 only. Zarr format 3 arrays should use codecs instead.

If neither compressor nor filters are provided, the default compressor zarr.codecs.ZstdCodec is used.

If compressor is set to None, no compression is used.

fill_valueAny, optional

Fill value for 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.

storeStoreLike or None, default=None

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_storeStoreLike or None, default=None

Separate storage for chunks. If not provided, store will be used for storage of both chunks and metadata.

filtersIterable[Codec] | Literal[“auto”], 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 zarr.abc.codec.ArrayArrayCodec, or a dict representations of zarr.abc.codec.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.

The default value of "auto" instructs Zarr to use a default used based on the data type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like zarr.dtype.VariableLengthUTF8 or zarr.dtype.VariableLengthUTF8. In these cases, the default filters contains a single element which is a codec specific to that particular data type.

To create an array with no filters, provide an empty iterable or the value None.

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. Zarr format 2 only. Zarr format 3 arrays should use chunk_key_encoding instead.

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 creating an array. The default is None, which instructs Zarr to choose the default Zarr format value defined in the runtime configuration.

meta_arrayarray-like, optional

Not implemented.

attributesdict[str, JSON], optional

A dictionary of user attributes to store with the array.

chunk_shapeint or tuple of ints, optional

The shape of the Array’s chunks (default is None). Zarr format 3 only. Zarr format 2 arrays should use chunks instead.

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. Zarr V3 only.

The elements of codecs 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 based on the data type of the array. For most data types, the default codecs are the tuple (BytesCodec(), ZstdCodec()); data types that require a special zarr.abc.codec.ArrayBytesCodec, like variable-length strings or bytes, will use the zarr.abc.codec.ArrayBytesCodec required for the data type instead of zarr.codecs.BytesCodec.

dimension_namesIterable[str | None] | None = None

An iterable of dimension names. Zarr format 3 only.

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.creation.empty(shape: tuple[int, Ellipsis], **kwargs: Any) → zarr.core.array.Array

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.creation.empty_like(

a: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array

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.creation.full(

shape: tuple[int, Ellipsis],

fill_value: Any,

**kwargs: Any,

) → zarr.core.array.Array

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.creation.full_like(

a: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array

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.creation.ones(shape: tuple[int, Ellipsis], **kwargs: Any) → zarr.core.array.Array

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.creation.ones_like(

a: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array

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.creation.open_array(

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

*,

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

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

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

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

**kwargs: Any,

) → zarr.core.array.Array

Open an array using file-mode-like semantics.

Parameters:

storeStoreLike

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. Deprecated in favor of zarr_format.

zarr_format{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.creation.open_like(

a: zarr.api.asynchronous.ArrayLike,

path: str,

**kwargs: Any,

) → zarr.core.array.Array

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.creation.zeros(shape: tuple[int, Ellipsis], **kwargs: Any) → zarr.core.array.Array

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.creation.zeros_like(

a: zarr.api.asynchronous.ArrayLike,

**kwargs: Any,

) → zarr.core.array.Array

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.