Groups (zarr.hierarchy)

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

Create a group.

Parameters:

store : MutableMapping or string

Store or path to directory in file system.

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.

path : string, optional

Group path.

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(store=None, mode='a', synchronizer=None, path=None)

Open a group 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).

synchronizer : object, optional

Array synchronizer.

path : string, optional

Group path.

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 : MutableMapping

Group store, already initialized.

path : string, optional

Group 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.
visit(func) Run func on each object’s path.
visitkeys(func) An alias for visit().
visitvalues(func) Run func on each object.
visititems(func) Run func on each object’s path and the object itself.
create_group(name[, overwrite]) Create a sub-group.
require_group(name[, overwrite]) Obtain a sub-group, creating one if it doesn’t exist.
create_groups(*names, **kwargs) 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, **kwargs) 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: ...; ratio: ...; initialized: 0/10
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  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'>
visit(func)

Run func on each object’s path.

Note: If func returns None (or doesn’t return),
iteration continues. However, if func returns anything else, it ceases and returns that value.

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> g4 = g3.create_group('baz')
>>> g5 = g3.create_group('quux')
>>> def print_visitor(name):
...     print(name)
>>> g1.visit(print_visitor)
bar
bar/baz
bar/quux
foo
>>> g3.visit(print_visitor)
baz
quux
visitkeys(func)

An alias for visit().

visitvalues(func)

Run func on each object.

Note: If func returns None (or doesn’t return),
iteration continues. However, if func returns anything else, it ceases and returns that value.

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> g4 = g3.create_group('baz')
>>> g5 = g3.create_group('quux')
>>> def print_visitor(obj):
...     print(obj)
>>> g1.visitvalues(print_visitor)
Group(/bar, 2)
  groups: 2; baz, quux
  store: DictStore
Group(/bar/baz, 0)
  store: DictStore
Group(/bar/quux, 0)
  store: DictStore
Group(/foo, 0)
  store: DictStore
>>> g3.visitvalues(print_visitor)
Group(/bar/baz, 0)
  store: DictStore
Group(/bar/quux, 0)
  store: DictStore
visititems(func)

Run func on each object’s path and the object itself.

Note: If func returns None (or doesn’t return),
iteration continues. However, if func returns anything else, it ceases and returns that value.

Examples

>>> import zarr
>>> g1 = zarr.group()
>>> g2 = g1.create_group('foo')
>>> g3 = g1.create_group('bar')
>>> g4 = g3.create_group('baz')
>>> g5 = g3.create_group('quux')
>>> def print_visitor(name, obj):
...     print((name, obj))
>>> g1.visititems(print_visitor)
('bar', Group(/bar, 2)
  groups: 2; baz, quux
  store: DictStore)
('bar/baz', Group(/bar/baz, 0)
  store: DictStore)
('bar/quux', Group(/bar/quux, 0)
  store: DictStore)
('foo', Group(/foo, 0)
  store: DictStore)
>>> g3.visititems(print_visitor)
('baz', Group(/bar/baz, 0)
  store: DictStore)
('quux', Group(/bar/quux, 0)
  store: DictStore)
create_group(name, overwrite=False)

Create a sub-group.

Parameters:

name : string

Group name.

overwrite : bool, optional

If True, overwrite any existing array with the given 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, overwrite=False)

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

Parameters:

name : string

Group name.

overwrite : bool, optional

Overwrite any existing array with given name if present.

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, **kwargs)

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

overwrite : bool, optional

If True, replace any existing array or group with the given name.

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:

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: ...; ratio: ...; initialized: 0/100
  compressor: Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
  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().