Array creation (zarr.creation)#

zarr.creation.create(shape: int | Tuple[int, ...], chunks: int | Tuple[int, ...] | bool = True, dtype: dtype[Any] | None | type[Any] | _SupportsDType[dtype[Any]] | str | tuple[Any, int] | tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | list[Any] | _DTypeDict | tuple[Any, Any] = None, compressor='default', fill_value: int | None = 0, order: Literal['C', 'F'] = 'C', store: str | MutableMapping | None = None, synchronizer: Synchronizer | None = None, overwrite: bool = False, path: str | bytes | None = None, chunk_store: MutableMapping | None = None, filters: Sequence[Codec] | None = None, cache_metadata: bool = True, cache_attrs: bool = True, read_only: bool = False, object_codec: Codec | None = None, dimension_separator: Literal['.', '/'] | None = None, write_empty_chunks: bool = True, *, zarr_version: Literal[2, 3] | None = None, meta_array: MetaArray | None = None, storage_transformers: Sequence[StorageTransformer] = (), **kwargs)[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.

dtypestring 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

Memory layout to be used within each chunk.

storeMutableMapping or string

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.

pathstring, 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.

New in version 2.8.

write_empty_chunksbool, optional

If True (default), 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. This setting enables sparser storage, as only chunks with non-fill-value data are stored, at the expense of overhead associated with checking the data of each chunk.

New in version 2.11.

storage_transformerssequence of StorageTransformers, optional

Setting storage transformers, changes the storage structure and behaviour of data coming from the underlying store. The transformers are applied in the order of the given sequence. Supplying an empty sequence is the same as omitting the argument or setting it to None. May only be set when using zarr_version 3.

New in version 2.13.

zarr_version{None, 2, 3}, optional

The zarr protocol version of the created array. If None, it will be inferred from store or chunk_store if they are provided, otherwise defaulting to 2.

New in version 2.12.

meta_arrayarray-like, optional

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

New in version 2.13.

Returns:
zzarr.core.Array

Examples

Create an array with default settings:

>>> import zarr
>>> z = zarr.create((10000, 10000), chunks=(1000, 1000))
>>> z
<zarr.core.Array (10000, 10000) float64>

Create an array with different some different configuration options:

>>> from numcodecs import Blosc
>>> compressor = Blosc(cname='zstd', clevel=1, shuffle=Blosc.BITSHUFFLE)
>>> z = zarr.create((10000, 10000), chunks=(1000, 1000), dtype='i1', order='F',
...                 compressor=compressor)
>>> z
<zarr.core.Array (10000, 10000) int8>

To create an array with object dtype requires a filter that can handle Python object encoding, e.g., MsgPack or Pickle from numcodecs:

>>> from numcodecs import MsgPack
>>> z = zarr.create((10000, 10000), chunks=(1000, 1000), dtype=object,
...                 object_codec=MsgPack())
>>> z
<zarr.core.Array (10000, 10000) object>

Example with some filters, and also storing chunks separately from metadata:

>>> from numcodecs import Quantize, Adler32
>>> store, chunk_store = dict(), dict()
>>> z = zarr.create((10000, 10000), chunks=(1000, 1000), dtype='f8',
...                 filters=[Quantize(digits=2, dtype='f8'), Adler32()],
...                 store=store, chunk_store=chunk_store)
>>> z
<zarr.core.Array (10000, 10000) float64>
zarr.creation.empty(shape, **kwargs)[source]#

Create an empty array.

For parameter definitions see zarr.creation.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.

zarr.creation.zeros(shape, **kwargs)[source]#

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

For parameter definitions see zarr.creation.create().

Examples

>>> import zarr
>>> z = zarr.zeros((10000, 10000), chunks=(1000, 1000))
>>> z
<zarr.core.Array (10000, 10000) float64>
>>> z[:2, :2]
array([[0., 0.],
       [0., 0.]])
zarr.creation.ones(shape, **kwargs)[source]#

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

For parameter definitions see zarr.creation.create().

Examples

>>> import zarr
>>> z = zarr.ones((10000, 10000), chunks=(1000, 1000))
>>> z
<zarr.core.Array (10000, 10000) float64>
>>> z[:2, :2]
array([[1., 1.],
       [1., 1.]])
zarr.creation.full(shape, fill_value, **kwargs)[source]#

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

For parameter definitions see zarr.creation.create().

Examples

>>> import zarr
>>> z = zarr.full((10000, 10000), chunks=(1000, 1000), fill_value=42)
>>> z
<zarr.core.Array (10000, 10000) float64>
>>> z[:2, :2]
array([[42., 42.],
       [42., 42.]])
zarr.creation.array(data, **kwargs)[source]#

Create an array filled with data.

The data argument should be a NumPy array or array-like object. For other parameter definitions see zarr.creation.create().

Examples

>>> import numpy as np
>>> import zarr
>>> a = np.arange(100000000).reshape(10000, 10000)
>>> z = zarr.array(a, chunks=(1000, 1000))
>>> z
<zarr.core.Array (10000, 10000) int64>
zarr.creation.open_array(store=None, mode='a', shape=None, chunks=True, dtype=None, compressor='default', fill_value=0, order='C', synchronizer=None, filters=None, cache_metadata=True, cache_attrs=True, path=None, object_codec=None, chunk_store=None, storage_options=None, partial_decompress=False, write_empty_chunks=True, *, zarr_version=None, dimension_separator: Literal['.', '/'] | None = None, meta_array=None, **kwargs)[source]#

Open an array using file-mode-like semantics.

Parameters:
storeMutableMapping or string, 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).

shapeint or tuple of ints, optional

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.

dtypestring or dtype, optional

NumPy dtype.

compressorCodec, optional

Primary compressor.

fill_valueobject, optional

Default value to use for uninitialized portions of the array.

order{‘C’, ‘F’}, optional

Memory layout to be used within each chunk.

synchronizerobject, optional

Array synchronizer.

filterssequence, 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.

pathstring, optional

Array path within store.

object_codecCodec, optional

A codec to encode object arrays, only needed if dtype=object.

chunk_storeMutableMapping or string, 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.

partial_decompressbool, optional

If True and while the chunk_store is a FSStore and the compression used is Blosc, when getting data from the array chunks will be partially read and decompressed when possible.

write_empty_chunksbool, optional

If True (default), 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. This setting enables sparser storage, as only chunks with non-fill-value data are stored, at the expense of overhead associated with checking the data of each chunk.

New in version 2.11.

zarr_version{None, 2, 3}, optional

The zarr protocol version of the array to be opened. If None, it will be inferred from store or chunk_store if they are provided, otherwise defaulting to 2.

dimension_separator{None, ‘.’, ‘/’}, optional

Can be used to specify whether the array is in a flat (‘.’) or nested (‘/’) format. If None, the appropriate value will be read from store when present. Otherwise, defaults to ‘.’ when zarr_version == 2 and / otherwise.

meta_arrayarray-like, optional

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

New in version 2.15.

Returns:
zzarr.core.Array

Notes

There is no need to close an array. Data are automatically flushed to the file system.

Examples

>>> import numpy as np
>>> import zarr
>>> z1 = zarr.open_array('data/example.zarr', mode='w', shape=(10000, 10000),
...                      chunks=(1000, 1000), fill_value=0)
>>> z1[:] = np.arange(100000000).reshape(10000, 10000)
>>> z1
<zarr.core.Array (10000, 10000) float64>
>>> z2 = zarr.open_array('data/example.zarr', mode='r')
>>> z2
<zarr.core.Array (10000, 10000) float64 read-only>
>>> np.all(z1[:] == z2[:])
True
zarr.creation.empty_like(a, **kwargs)[source]#

Create an empty array like a.

zarr.creation.zeros_like(a, **kwargs)[source]#

Create an array of zeros like a.

zarr.creation.ones_like(a, **kwargs)[source]#

Create an array of ones like a.

zarr.creation.full_like(a, **kwargs)[source]#

Create a filled array like a.

zarr.creation.open_like(a, path, **kwargs)[source]#

Open a persistent array like a.