Array creation (zarr.creation)

zarr.creation.create(shape, chunks=None, dtype=None, compressor='default', fill_value=0, order='C', store=None, synchronizer=None, overwrite=False, path=None, chunk_store=None, filters=None, cache_metadata=True, **kwargs)

Create an array.

Parameters:

shape : int or tuple of ints

Array shape.

chunks : int or tuple of ints, optional

Chunk shape. If not provided, will be guessed from shape and dtype.

dtype : string or dtype, optional

NumPy dtype.

compressor : Codec, optional

Primary compressor.

fill_value : object

Default value to use for uninitialized portions of the array.

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

Memory layout to be used within each chunk.

store : MutableMapping or string

Store or path to directory in file system.

synchronizer : object, optional

Array synchronizer.

overwrite : bool, optional

If True, delete all pre-existing data in store at path before creating the array.

path : string, optional

Path under which array is stored.

chunk_store : MutableMapping, optional

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

filters : sequence of Codecs, optional

Sequence of filters to use to encode chunk data prior to compression.

cache_metadata : bool, 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).

Returns:

z : zarr.core.Array

Examples

Create an array with default settings:

>>> import zarr
>>> z = zarr.create((10000, 10000), chunks=(1000, 1000))
>>> z
Array((10000, 10000), float64, chunks=(1000, 1000), order=C)
  nbytes: 762.9M; nbytes_stored: ...; ratio: ...; initialized: 0/100
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  store: dict

Create an array with different some different configuration options:

>>> from numcodecs import Blosc
>>> z = zarr.create((10000, 10000), chunks=(1000, 1000), dtype='i1', order='F',
...                 compressor=Blosc(cname='zstd', clevel=1, shuffle=Blosc.BITSHUFFLE))
>>> z
Array((10000, 10000), int8, chunks=(1000, 1000), order=F)
  nbytes: 95.4M; nbytes_stored: ...; ratio: ...; initialized: 0/100
  compressor: Blosc(cname='zstd', clevel=1, shuffle=BITSHUFFLE, blocksize=0)
  store: dict

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',
...                 filters=[MsgPack()])
>>> z
Array((10000, 10000), object, chunks=(1000, 1000), order=C)
  nbytes: 762.9M; nbytes_stored: ...; ratio: ...; initialized: 0/100
  filters: MsgPack(encoding='utf-8')
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  store: dict

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
Array((10000, 10000), float64, chunks=(1000, 1000), order=C)
  nbytes: 762.9M; nbytes_stored: ...; ratio: ...; initialized: 0/100
  filters: Quantize(digits=2, dtype='<f8')
           Adler32()
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  store: dict; chunk_store: dict
zarr.creation.empty(shape, **kwargs)

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)

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
Array((10000, 10000), float64, chunks=(1000, 1000), order=C)
  nbytes: 762.9M; nbytes_stored: ...; ratio: ...; initialized: 0/100
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  store: dict
>>> z[:2, :2]
array([[ 0.,  0.],
       [ 0.,  0.]])
zarr.creation.ones(shape, **kwargs)

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
Array((10000, 10000), float64, chunks=(1000, 1000), order=C)
  nbytes: 762.9M; nbytes_stored: ...; ratio: ...; initialized: 0/100
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  store: dict
>>> z[:2, :2]
array([[ 1.,  1.],
       [ 1.,  1.]])
zarr.creation.full(shape, fill_value, **kwargs)

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
Array((10000, 10000), float64, chunks=(1000, 1000), order=C)
  nbytes: 762.9M; nbytes_stored: ...; ratio: ...; initialized: 0/100
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  store: dict
>>> z[:2, :2]
array([[ 42.,  42.],
       [ 42.,  42.]])
zarr.creation.array(data, **kwargs)

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
Array((10000, 10000), int64, chunks=(1000, 1000), order=C)
  nbytes: 762.9M; nbytes_stored: 15.2M; ratio: 50.2; initialized: 100/100
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  store: dict
zarr.creation.open_array(store=None, mode='a', shape=None, chunks=None, dtype=None, compressor='default', fill_value=0, order='C', synchronizer=None, filters=None, cache_metadata=True, path=None, **kwargs)

Open array using mode-like semantics.

Parameters:

store : MutableMapping or string

Store or path to directory in file system.

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

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).

shape : int or tuple of ints

Array shape.

chunks : int or tuple of ints, optional

Chunk shape. If not provided, will be guessed from shape and dtype.

dtype : string or dtype, optional

NumPy dtype.

compressor : Codec, optional

Primary compressor.

fill_value : object

Default value to use for uninitialized portions of the array.

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

Memory layout to be used within each chunk.

synchronizer : object, optional

Array synchronizer.

filters : sequence, optional

Sequence of filters to use to encode chunk data prior to compression.

cache_metadata : bool, 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).

path : string, optional

Array path.

Returns:

z : zarr.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('example.zarr', mode='w', shape=(10000, 10000),
...                      chunks=(1000, 1000), fill_value=0)
>>> z1[:] = np.arange(100000000).reshape(10000, 10000)
>>> z1
Array((10000, 10000), float64, chunks=(1000, 1000), order=C)
  nbytes: 762.9M; nbytes_stored: 23.0M; ratio: 33.2; initialized: 100/100
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  store: DirectoryStore
>>> z2 = zarr.open_array('example.zarr', mode='r')
>>> z2
Array((10000, 10000), float64, chunks=(1000, 1000), order=C)
  nbytes: 762.9M; nbytes_stored: 23.0M; ratio: 33.2; initialized: 100/100
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  store: DirectoryStore
>>> np.all(z1[:] == z2[:])
True
zarr.creation.empty_like(a, **kwargs)

Create an empty array like a.

zarr.creation.zeros_like(a, **kwargs)

Create an array of zeros like a.

zarr.creation.ones_like(a, **kwargs)

Create an array of ones like a.

zarr.creation.full_like(a, **kwargs)

Create a filled array like a.

zarr.creation.open_like(a, path, **kwargs)

Open a persistent array like a.