Groups (zarr.hierarchy)

zarr.hierarchy.group(store=None, overwrite=False, chunk_store=None, synchronizer=None)

Create a group.

Parameters:

store : MutableMapping, optional

Group storage. If not provided, a DictStore will be used, meaning that data will be stored in memory.

overwrite : bool, optional

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

chunk_store : MutableMapping, optional

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

synchronizer : object, optional

Array synchronizer.

Returns:

g : zarr.hierarchy.Group

Examples

Create a group in memory:

>>> import zarr
>>> g = zarr.group()
>>> g
Group(/, 0)
  store: DictStore

Create a group with a different store:

>>> store = zarr.DirectoryStore('example')
>>> g = zarr.group(store=store, overwrite=True)
>>> g
Group(/, 0)
  store: DirectoryStore
zarr.hierarchy.open_group(path, mode='a', synchronizer=None)

Convenience function to instantiate a group stored in a directory on the file system.

Parameters:

path : string

Path to directory in file system in which to store the group.

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

synchronizer : object, optional

Array synchronizer.

Returns:

g : zarr.hierarchy.Group

Examples

>>> import zarr
>>> root = zarr.open_group('example', mode='w')
>>> foo = root.create_group('foo')
>>> bar = root.create_group('bar')
>>> root
Group(/, 2)
  groups: 2; bar, foo
  store: DirectoryStore
>>> root2 = zarr.open_group('example', mode='a')
>>> root2
Group(/, 2)
  groups: 2; bar, foo
  store: DirectoryStore
>>> root == root2
True
class zarr.hierarchy.Group(store, path=None, read_only=False, chunk_store=None, synchronizer=None)

Instantiate a group from an initialized store.

Parameters:

store : HierarchicalStore

Group store, already initialized.

path : string, optional

Storage path.

read_only : bool, optional

True if group should be protected against modification.

chunk_store : MutableMapping, optional

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

synchronizer : object, optional

Array synchronizer.

Attributes

store A MutableMapping providing the underlying storage for the group.
path Storage path.
name Group name following h5py convention.
read_only A boolean, True if modification operations are not permitted.
chunk_store A MutableMapping providing the underlying storage for array chunks.
synchronizer Object used to synchronize write access to groups and arrays.
attrs A MutableMapping containing user-defined attributes.

Methods

__len__() Number of members.
__iter__() Return an iterator over group member names.
__contains__(item) Test for group membership.
__getitem__(item) Obtain a group member.
group_keys() Return an iterator over member names for groups only.
groups() Return an iterator over (name, value) pairs for groups only.
array_keys() Return an iterator over member names for arrays only.
arrays() Return an iterator over (name, value) pairs for arrays only.
create_group(name) Create a sub-group.
require_group(name) Obtain a sub-group, creating one if it doesn’t exist.
create_groups(*names) Convenience method to create multiple groups in a single call.
require_groups(*names) Convenience method to require multiple groups in a single call.
create_dataset(name[, data, shape, chunks, ...]) Create an array.
require_dataset(name, shape[, dtype, exact]) Obtain an array, creating if it doesn’t exist.
create(name, **kwargs) Create an array.
empty(name, **kwargs) Create an array.
zeros(name, **kwargs) Create an array.
ones(name, **kwargs) Create an array.
full(name, fill_value, **kwargs) Create an array.
array(name, data, **kwargs) Create an array.
empty_like(name, data, **kwargs) Create an array.
zeros_like(name, data, **kwargs) Create an array.
ones_like(name, data, **kwargs) Create an array.
full_like(name, data, **kwargs) Create an array.
__len__()

Number of members.

__iter__()

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_dataset('baz', shape=100, chunks=10)
>>> d2 = g1.create_dataset('quux', shape=200, chunks=20)
>>> for name in g1:
...     print(name)
bar
baz
foo
quux
__contains__(item)

Test for group membership.

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> d1 = g1.create_dataset('bar', shape=100, chunks=10)
>>> 'foo' in g1
True
>>> 'bar' in g1
True
>>> 'baz' in g1
False
__getitem__(item)

Obtain a group member.

Parameters:

item : string

Member name or path.

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> d1 = g1.create_dataset('foo/bar/baz', shape=100, chunks=10)
>>> g1['foo']
Group(/foo, 1)
  groups: 1; bar
  store: DictStore
>>> g1['foo/bar']
Group(/foo/bar, 1)
  arrays: 1; baz
  store: DictStore
>>> g1['foo/bar/baz']
Array(/foo/bar/baz, (100,), float64, chunks=(10,), order=C)
  nbytes: 800; nbytes_stored: 293; ratio: 2.7; initialized: 0/10
  compressor: Blosc(cname='lz4', clevel=5, shuffle=1)
  store: DictStore
group_keys()

Return an iterator over member names for groups only.

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> d1 = g1.create_dataset('baz', shape=100, chunks=10)
>>> d2 = g1.create_dataset('quux', shape=200, chunks=20)
>>> sorted(g1.group_keys())
['bar', 'foo']
groups()

Return an iterator over (name, value) pairs for groups only.

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> d1 = g1.create_dataset('baz', shape=100, chunks=10)
>>> d2 = g1.create_dataset('quux', shape=200, chunks=20)
>>> for n, v in g1.groups():
...     print(n, type(v))
bar <class 'zarr.hierarchy.Group'>
foo <class 'zarr.hierarchy.Group'>
array_keys()

Return an iterator over member names for arrays only.

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> d1 = g1.create_dataset('baz', shape=100, chunks=10)
>>> d2 = g1.create_dataset('quux', shape=200, chunks=20)
>>> sorted(g1.array_keys())
['baz', 'quux']
arrays()

Return an iterator over (name, value) pairs for arrays only.

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> d1 = g1.create_dataset('baz', shape=100, chunks=10)
>>> d2 = g1.create_dataset('quux', shape=200, chunks=20)
>>> for n, v in g1.arrays():
...     print(n, type(v))
baz <class 'zarr.core.Array'>
quux <class 'zarr.core.Array'>
create_group(name)

Create a sub-group.

Parameters:

name : string

Group name.

Returns:

g : zarr.hierarchy.Group

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> g4 = g1.create_group('baz/quux')
require_group(name)

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

Parameters:

name : string

Group name.

Returns:

g : zarr.hierarchy.Group

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.require_group('foo')
>>> g3 = g1.require_group('foo')
>>> g2 == g3
True
create_groups(*names)

Convenience method to create multiple groups in a single call.

require_groups(*names)

Convenience method to require multiple groups in a single call.

create_dataset(name, data=None, shape=None, chunks=None, dtype=None, compressor='default', fill_value=None, order='C', synchronizer=None, filters=None, **kwargs)

Create an array.

Parameters:

name : string

Array name.

data : array_like, optional

Initial data.

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 : zarr.sync.ArraySynchronizer, optional

Array synchronizer.

filters : sequence of Codecs, optional

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

Returns:

a : zarr.core.Array

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> d1 = g1.create_dataset('foo', shape=(10000, 10000),
...                        chunks=(1000, 1000))
>>> d1
Array(/foo, (10000, 10000), float64, chunks=(1000, 1000), order=C)
  nbytes: 762.9M; nbytes_stored: 326; ratio: 2453987.7; initialized: 0/100
  compressor: Blosc(cname='lz4', clevel=5, shuffle=1)
  store: DictStore
require_dataset(name, shape, dtype=None, exact=False, **kwargs)

Obtain an array, creating if it doesn’t exist. Other kwargs are as per zarr.hierarchy.Group.create_dataset().

Parameters:

name : string

Array name.

shape : int or tuple of ints

Array shape.

dtype : string or dtype, optional

NumPy dtype.

exact : bool, optional

If True, require dtype to match exactly. If false, require dtype can be cast from array dtype.

create(name, **kwargs)

Create an array. Keyword arguments as per zarr.creation.create().

empty(name, **kwargs)

Create an array. Keyword arguments as per zarr.creation.empty().

zeros(name, **kwargs)

Create an array. Keyword arguments as per zarr.creation.zeros().

ones(name, **kwargs)

Create an array. Keyword arguments as per zarr.creation.ones().

full(name, fill_value, **kwargs)

Create an array. Keyword arguments as per zarr.creation.full().

array(name, data, **kwargs)

Create an array. Keyword arguments as per zarr.creation.array().

empty_like(name, data, **kwargs)

Create an array. Keyword arguments as per zarr.creation.empty_like().

zeros_like(name, data, **kwargs)

Create an array. Keyword arguments as per zarr.creation.zeros_like().

ones_like(name, data, **kwargs)

Create an array. Keyword arguments as per zarr.creation.ones_like().

full_like(name, data, **kwargs)

Create an array. Keyword arguments as per zarr.creation.full_like().