def move(self, source, dest):
"""Move contents from one path to another relative to the Group.
Parameters
----------
source : string
Name or path to a Zarr object to move.
dest : string
New name or path of the Zarr object.
"""
source = self._item_path(source)
dest = self._item_path(dest)
# Check that source exists.
if not (contains_array(self._store, source) or
contains_group(self._store, source)):
raise ValueError('The source, "%s", does not exist.' % source)
if contains_array(self._store, dest) or contains_group(self._store, dest):
raise ValueError('The dest, "%s", already exists.' % dest)
# Ensure groups needed for `dest` exist.
if "/" in dest:
self.require_group("/" + dest.rsplit("/", 1)[0])
self._write_op(self._move_nosync, source, dest)
def group_keys(self):
"""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']
"""
if self._version == 2:
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
if contains_group(self._store, path):
yield key
else:
dir_name = meta_root + self._path
group_sfx = '.group' + self._metadata_key_suffix
for key in sorted(listdir(self._store, dir_name)):
if key.endswith(group_sfx):
key = key[:-len(group_sfx)]
path = self._key_prefix + key
if path.endswith(".array" + self._metadata_key_suffix):
# skip array keys
continue
if contains_group(self._store, path, explicit_only=False):
yield key
def _array_iter(self, keys_only, method, recurse):
if self._version == 2:
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
assert not path.startswith("meta")
if contains_array(self._store, path):
_key = key.rstrip("/")
yield _key if keys_only else (_key, self[key])
elif recurse and contains_group(self._store, path):
group = self[key]
for i in getattr(group, method)(recurse=recurse):
yield i
else:
dir_name = meta_root + self._path
array_sfx = '.array' + self._metadata_key_suffix
for key in sorted(listdir(self._store, dir_name)):
if key.endswith(array_sfx):
key = key[:-len(array_sfx)]
path = self._key_prefix + key
assert not path.startswith("meta")
if key.endswith('.group' + self._metadata_key_suffix):
# skip group metadata keys
continue
if contains_array(self._store, path):
_key = key.rstrip("/")
yield _key if keys_only else (_key, self[key])
elif recurse and contains_group(self._store, path):
group = self[key]
for i in getattr(group, method)(recurse=recurse):
yield i
def move(self, source, dest):
"""Move contents from one path to another relative to the Group.
Parameters
----------
source : string
Name or path to a Zarr object to move.
dest : string
New name or path of the Zarr object.
"""
source = self._item_path(source)
dest = self._item_path(dest)
# Check that source exists.
if not (contains_array(self._store, source)
or contains_group(self._store, source)):
raise ValueError('The source, "%s", does not exist.' % source)
if contains_array(self._store, dest) or contains_group(
self._store, dest):
raise ValueError('The dest, "%s", already exists.' % dest)
# Ensure groups needed for `dest` exist.
if "/" in dest:
self.require_group("/" + dest.rsplit("/", 1)[0])
self._write_op(self._move_nosync, source, dest)
def group(store=None,
overwrite=False,
chunk_store=None,
synchronizer=None,
path=None):
"""Create a group.
Parameters
----------
store : MutableMapping or string, optional
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 within store.
Returns
-------
g : zarr.hierarchy.Group
Examples
--------
Create a group in memory::
>>> import zarr
>>> g = zarr.group()
>>> g
<zarr.hierarchy.Group '/'>
Create a group with a different store::
>>> store = zarr.DirectoryStore('data/example.zarr')
>>> g = zarr.group(store=store, overwrite=True)
>>> g
<zarr.hierarchy.Group '/'>
"""
# handle polymorphic store arg
store = _normalize_store_arg(store)
path = normalize_storage_path(path)
# require group
if overwrite or not contains_group(store):
init_group(store,
overwrite=overwrite,
chunk_store=chunk_store,
path=path)
return Group(store,
read_only=False,
chunk_store=chunk_store,
synchronizer=synchronizer,
path=path)
def _delitem_nosync(self, item):
path = self._item_path(item)
if contains_array(self._store, path) or \
contains_group(self._store, path):
rmdir(self._store, path)
else:
raise KeyError(item)
def __getitem__(self, 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']
<zarr.hierarchy.Group '/foo'>
>>> g1['foo/bar']
<zarr.hierarchy.Group '/foo/bar'>
>>> g1['foo/bar/baz']
<zarr.core.Array '/foo/bar/baz' (100,) float64>
"""
path = self._item_path(item)
if contains_array(self._store, path):
return Array(self._store, read_only=self._read_only, path=path,
chunk_store=self._chunk_store,
synchronizer=self._synchronizer, cache_attrs=self.attrs.cache)
elif contains_group(self._store, path):
return Group(self._store, read_only=self._read_only, path=path,
chunk_store=self._chunk_store, cache_attrs=self.attrs.cache,
synchronizer=self._synchronizer)
else:
raise KeyError(item)
def load(store):
"""Load data from an array or group into memory.
Parameters
----------
store : MutableMapping or string
Store or path to directory in file system or name of zip file.
Returns
-------
out
If the store contains an array, out will be a numpy array. If the store contains
a group, out will be a dict-like object where keys are array names and values
are numpy arrays.
See Also
--------
save, savez
Notes
-----
If loading data from a group of arrays, data will not be immediately loaded into
memory. Rather, arrays will be loaded into memory as they are requested.
"""
# handle polymorphic store arg
store = normalize_store_arg(store)
if contains_array(store, path=None):
return Array(store=store, path=None)[...]
elif contains_group(store, path=None):
grp = Group(store=store, path=None)
return LazyLoader(grp)
def __getitem__(self, 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']
<zarr.hierarchy.Group '/foo'>
>>> g1['foo/bar']
<zarr.hierarchy.Group '/foo/bar'>
>>> g1['foo/bar/baz']
<zarr.core.Array '/foo/bar/baz' (100,) float64>
"""
path = self._item_path(item)
if contains_array(self._store, path):
return Array(self._store, read_only=self._read_only, path=path,
chunk_store=self._chunk_store,
synchronizer=self._synchronizer, cache_attrs=self.attrs.cache)
elif contains_group(self._store, path):
return Group(self._store, read_only=self._read_only, path=path,
chunk_store=self._chunk_store, cache_attrs=self.attrs.cache,
synchronizer=self._synchronizer)
else:
raise KeyError(item)
def groups(self):
"""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'>
"""
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
if contains_group(self._store, path):
yield key, Group(self._store,
path=path,
read_only=self._read_only,
chunk_store=self._chunk_store,
cache_attrs=self.attrs.cache,
synchronizer=self._synchronizer)
def _delitem_nosync(self, item):
path = self._item_path(item)
if contains_array(self._store, path) or \
contains_group(self._store, path):
rmdir(self._store, path)
else:
raise KeyError(item)
def load(store: StoreLike):
"""Load data from an array or group into memory.
Parameters
----------
store : MutableMapping or string
Store or path to directory in file system or name of zip file.
Returns
-------
out
If the store contains an array, out will be a numpy array. If the store contains
a group, out will be a dict-like object where keys are array names and values
are numpy arrays.
See Also
--------
save, savez
Notes
-----
If loading data from a group of arrays, data will not be immediately loaded into
memory. Rather, arrays will be loaded into memory as they are requested.
"""
# handle polymorphic store arg
_store = normalize_store_arg(store)
if contains_array(_store, path=None):
return Array(store=_store, path=None)[...]
elif contains_group(_store, path=None):
grp = Group(store=_store, path=None)
return LazyLoader(grp)
def groups(self):
"""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'>
"""
if self._version == 2:
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
if contains_group(self._store, path, explicit_only=False):
yield key, Group(self._store,
path=path,
read_only=self._read_only,
chunk_store=self._chunk_store,
cache_attrs=self.attrs.cache,
synchronizer=self._synchronizer,
zarr_version=self._version)
else:
dir_name = meta_root + self._path
group_sfx = '.group' + self._metadata_key_suffix
for key in sorted(listdir(self._store, dir_name)):
if key.endswith(group_sfx):
key = key[:-len(group_sfx)]
path = self._key_prefix + key
if path.endswith(".array" + self._metadata_key_suffix):
# skip array keys
continue
if contains_group(self._store, path, explicit_only=False):
yield key, Group(self._store,
path=path,
read_only=self._read_only,
chunk_store=self._chunk_store,
cache_attrs=self.attrs.cache,
synchronizer=self._synchronizer,
zarr_version=self._version)
def _array_iter(self, keys_only, method, recurse):
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
if contains_array(self._store, path):
yield key if keys_only else (key, self[key])
elif recurse and contains_group(self._store, path):
group = self[key]
for i in getattr(group, method)(recurse=recurse):
yield i
def group(store=None, overwrite=False, chunk_store=None,
cache_attrs=True, synchronizer=None, path=None):
"""Create a group.
Parameters
----------
store : MutableMapping or string, optional
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.
cache_attrs : bool, 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.
synchronizer : object, optional
Array synchronizer.
path : string, optional
Group path within store.
Returns
-------
g : zarr.hierarchy.Group
Examples
--------
Create a group in memory::
>>> import zarr
>>> g = zarr.group()
>>> g
<zarr.hierarchy.Group '/'>
Create a group with a different store::
>>> store = zarr.DirectoryStore('data/example.zarr')
>>> g = zarr.group(store=store, overwrite=True)
>>> g
<zarr.hierarchy.Group '/'>
"""
# handle polymorphic store arg
store = _normalize_store_arg(store)
path = normalize_storage_path(path)
# require group
if overwrite or not contains_group(store):
init_group(store, overwrite=overwrite, chunk_store=chunk_store,
path=path)
return Group(store, read_only=False, chunk_store=chunk_store,
cache_attrs=cache_attrs, synchronizer=synchronizer, path=path)
def _require_group_nosync(self, name, overwrite=False):
path = self._item_path(name)
# create terminal group if necessary
if not contains_group(self._store, path):
init_group(store=self._store, path=path, chunk_store=self._chunk_store,
overwrite=overwrite)
return Group(self._store, path=path, read_only=self._read_only,
chunk_store=self._chunk_store, synchronizer=self._synchronizer)
def 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
"""
# handle polymorphic store arg
store = _handle_store_arg(store)
path = normalize_storage_path(path)
# require group
if overwrite or not contains_group(store):
init_group(store, overwrite=overwrite, chunk_store=chunk_store,
path=path)
return Group(store, read_only=False, chunk_store=chunk_store,
synchronizer=synchronizer, path=path)
def _require_group_nosync(self, name, overwrite=False):
path = self._item_path(name)
# create terminal group if necessary
if not contains_group(self._store, path):
init_group(store=self._store, path=path, chunk_store=self._chunk_store,
overwrite=overwrite)
return Group(self._store, path=path, read_only=self._read_only,
chunk_store=self._chunk_store, cache_attrs=self.attrs.cache,
synchronizer=self._synchronizer)
def __getitem__(self, 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']
<zarr.hierarchy.Group '/foo'>
>>> g1['foo/bar']
<zarr.hierarchy.Group '/foo/bar'>
>>> g1['foo/bar/baz']
<zarr.core.Array '/foo/bar/baz' (100,) float64>
"""
path = self._item_path(item)
if contains_array(self._store, path):
return Array(self._store,
read_only=self._read_only,
path=path,
chunk_store=self._chunk_store,
synchronizer=self._synchronizer,
cache_attrs=self.attrs.cache,
zarr_version=self._version)
elif contains_group(self._store, path, explicit_only=True):
return Group(self._store,
read_only=self._read_only,
path=path,
chunk_store=self._chunk_store,
cache_attrs=self.attrs.cache,
synchronizer=self._synchronizer,
zarr_version=self._version)
elif self._version == 3:
implicit_group = meta_root + path + '/'
# non-empty folder in the metadata path implies an implicit group
if self._store.list_prefix(implicit_group):
return Group(self._store,
read_only=self._read_only,
path=path,
chunk_store=self._chunk_store,
cache_attrs=self.attrs.cache,
synchronizer=self._synchronizer,
zarr_version=self._version)
else:
raise KeyError(item)
else:
raise KeyError(item)
def __iter__(self):
"""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
"""
if getattr(self._store, '_store_version', 2) == 2:
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
if (contains_array(self._store, path)
or contains_group(self._store, path)):
yield key
else:
# TODO: Should this iterate over data folders and/or metadata
# folders and/or metadata files
dir_path = meta_root + self._key_prefix
name_start = len(dir_path)
keys, prefixes = self._store.list_dir(dir_path)
# yield any groups or arrays
sfx = self._metadata_key_suffix
for key in keys:
len_suffix = len('.group') + len(sfx) # same for .array
if key.endswith(('.group' + sfx, '.array' + sfx)):
yield key[name_start:-len_suffix]
# also yield any implicit groups
for prefix in prefixes:
prefix = prefix.rstrip('/')
# only implicit if there is no .group.sfx file
if not prefix + '.group' + sfx in self._store:
yield prefix[name_start:]
def group_keys(self):
"""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']
"""
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
if contains_group(self._store, path):
yield key
def group_keys(self):
"""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']
"""
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
if contains_group(self._store, path):
yield key
def __getitem__(self, 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: 290; ratio: 2.8; initialized: 0/10
compressor: Blosc(cname='lz4', clevel=5, shuffle=1)
store: DictStore
""" # flake8: noqa
path = self._item_path(item)
if contains_array(self._store, path):
return Array(self._store,
read_only=self._read_only,
path=path,
chunk_store=self._chunk_store,
synchronizer=self._synchronizer)
elif contains_group(self._store, path):
return Group(self._store,
read_only=self._read_only,
path=path,
chunk_store=self._chunk_store,
synchronizer=self._synchronizer)
else:
raise KeyError(item)
def __contains__(self, 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
"""
path = self._item_path(item)
return contains_array(self._store, path) or \
contains_group(self._store, path)
def __contains__(self, 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
"""
path = self._item_path(item)
return contains_array(self._store, path) or \
contains_group(self._store, path)
def load(store: StoreLike, zarr_version=None, path=None):
"""Load data from an array or group into memory.
Parameters
----------
store : MutableMapping or string
Store or path to directory in file system or name of zip file.
zarr_version : {2, 3, None}, optional
The zarr protocol version to use when loading. The default value of
None will attempt to infer the version from `store` if possible,
otherwise it will fall back to 2.
path : str or None, optional
The path within the store from which to load.
Returns
-------
out
If the store contains an array, out will be a numpy array. If the store contains
a group, out will be a dict-like object where keys are array names and values
are numpy arrays.
See Also
--------
save, savez
Notes
-----
If loading data from a group of arrays, data will not be immediately loaded into
memory. Rather, arrays will be loaded into memory as they are requested.
"""
# handle polymorphic store arg
_store = normalize_store_arg(store, zarr_version=zarr_version)
path = _check_and_update_path(_store, path)
if contains_array(_store, path=path):
return Array(store=_store, path=path)[...]
elif contains_group(_store, path=path):
grp = Group(store=_store, path=path)
return LazyLoader(grp)
def __getitem__(self, 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: 290; ratio: 2.8; initialized: 0/10
compressor: Blosc(cname='lz4', clevel=5, shuffle=1)
store: DictStore
""" # flake8: noqa
path = self._item_path(item)
if contains_array(self._store, path):
return Array(self._store, read_only=self._read_only, path=path,
chunk_store=self._chunk_store,
synchronizer=self._synchronizer)
elif contains_group(self._store, path):
return Group(self._store, read_only=self._read_only, path=path,
chunk_store=self._chunk_store,
synchronizer=self._synchronizer)
else:
raise KeyError(item)
def groups(self):
"""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'>
"""
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
if contains_group(self._store, path):
yield key, Group(self._store, path=path, read_only=self._read_only,
chunk_store=self._chunk_store,
synchronizer=self._synchronizer)
def __iter__(self):
"""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
"""
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
if (contains_array(self._store, path)
or contains_group(self._store, path)):
yield key
def __iter__(self):
"""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
"""
for key in sorted(listdir(self._store, self._path)):
path = self._key_prefix + key
if (contains_array(self._store, path) or
contains_group(self._store, path)):
yield key
def 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
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=1)
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=1)
store: DirectoryStore
>>> np.all(z1[:] == z2[:])
True
Notes
-----
There is no need to close an array. Data are automatically flushed to the
file system.
""" # flake8: noqa
# use same mode semantics as h5py
# r : read only, must exist
# r+ : read/write, must exist
# w : create, delete if exists
# w- or x : create, fail if exists
# a : read/write if exists, create otherwise (default)
# handle polymorphic store arg
store = _handle_store_arg(store)
path = normalize_storage_path(path)
# compatibility
compressor, fill_value = _handle_kwargs(compressor, fill_value, kwargs)
# ensure store is initialized
if mode in ['r', 'r+']:
if contains_group(store, path=path):
err_contains_group(path)
elif not contains_array(store, path=path):
err_array_not_found(path)
elif mode == 'w':
init_array(store, shape=shape, chunks=chunks, dtype=dtype,
compressor=compressor, fill_value=fill_value,
order=order, filters=filters, overwrite=True, path=path)
elif mode == 'a':
if contains_group(store, path=path):
err_contains_group(path)
elif not contains_array(store, path=path):
init_array(store, shape=shape, chunks=chunks, dtype=dtype,
compressor=compressor, fill_value=fill_value,
order=order, filters=filters, path=path)
elif mode in ['w-', 'x']:
if contains_group(store, path=path):
err_contains_group(path)
elif contains_array(store, path=path):
err_contains_array(path)
else:
init_array(store, shape=shape, chunks=chunks, dtype=dtype,
compressor=compressor, fill_value=fill_value,
order=order, filters=filters, path=path)
# determine read only status
read_only = mode == 'r'
# instantiate array
z = Array(store, read_only=read_only, synchronizer=synchronizer,
cache_metadata=cache_metadata, path=path)
return z
def 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
"""
# handle polymorphic store arg
store = _handle_store_arg(store)
path = normalize_storage_path(path)
# ensure store is initialized
if mode in ['r', 'r+']:
if contains_array(store, path=path):
err_contains_array(path)
elif not contains_group(store, path=path):
err_group_not_found(path)
elif mode == 'w':
init_group(store, overwrite=True, path=path)
elif mode == 'a':
if contains_array(store, path=path):
err_contains_array(path)
if not contains_group(store, path=path):
init_group(store, path=path)
elif mode in ['w-', 'x']:
if contains_array(store, path=path):
err_contains_array(path)
elif contains_group(store, path=path):
err_contains_group(path)
else:
init_group(store, path=path)
# determine read only status
read_only = mode == 'r'
return Group(store,
read_only=read_only,
synchronizer=synchronizer,
path=path)
def open_group(store,
mode='a',
cache_attrs=True,
synchronizer=None,
path=None):
"""Open a group using file-mode-like semantics.
Parameters
----------
store : MutableMapping or string
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).
cache_attrs : bool, 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.
synchronizer : object, optional
Array synchronizer.
path : string, optional
Group path within store.
Returns
-------
g : zarr.hierarchy.Group
Examples
--------
>>> import zarr
>>> root = zarr.open_group('data/example.zarr', mode='w')
>>> foo = root.create_group('foo')
>>> bar = root.create_group('bar')
>>> root
<zarr.hierarchy.Group '/'>
>>> root2 = zarr.open_group('data/example.zarr', mode='a')
>>> root2
<zarr.hierarchy.Group '/'>
>>> root == root2
True
"""
# handle polymorphic store arg
store = _normalize_store_arg(store)
path = normalize_storage_path(path)
# ensure store is initialized
if mode in ['r', 'r+']:
if contains_array(store, path=path):
err_contains_array(path)
elif not contains_group(store, path=path):
err_group_not_found(path)
elif mode == 'w':
init_group(store, overwrite=True, path=path)
elif mode == 'a':
if contains_array(store, path=path):
err_contains_array(path)
if not contains_group(store, path=path):
init_group(store, path=path)
elif mode in ['w-', 'x']:
if contains_array(store, path=path):
err_contains_array(path)
elif contains_group(store, path=path):
err_contains_group(path)
else:
init_group(store, path=path)
# determine read only status
read_only = mode == 'r'
return Group(store,
read_only=read_only,
cache_attrs=cache_attrs,
synchronizer=synchronizer,
path=path)
def open_array(store,
mode='a',
shape=None,
chunks=True,
dtype=None,
compressor='default',
fill_value=0,
order='C',
synchronizer=None,
filters=None,
cache_metadata=True,
path=None,
**kwargs):
"""Open an array using file-mode-like semantics.
Parameters
----------
store : MutableMapping or string
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).
shape : int or tuple of ints, optional
Array shape.
chunks : int 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.
dtype : string or dtype, optional
NumPy dtype.
compressor : Codec, optional
Primary compressor.
fill_value : object, optional
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 within store.
Returns
-------
z : zarr.core.Array
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
Notes
-----
There is no need to close an array. Data are automatically flushed to the
file system.
"""
# use same mode semantics as h5py
# r : read only, must exist
# r+ : read/write, must exist
# w : create, delete if exists
# w- or x : create, fail if exists
# a : read/write if exists, create otherwise (default)
# handle polymorphic store arg
store = normalize_store_arg(store, clobber=(mode == 'w'))
path = normalize_storage_path(path)
# API compatibility with h5py
compressor, fill_value = _kwargs_compat(compressor, fill_value, kwargs)
# ensure fill_value of correct type
if fill_value is not None:
fill_value = np.array(fill_value, dtype=dtype)[()]
# ensure store is initialized
if mode in ['r', 'r+']:
if contains_group(store, path=path):
err_contains_group(path)
elif not contains_array(store, path=path):
err_array_not_found(path)
elif mode == 'w':
init_array(store,
shape=shape,
chunks=chunks,
dtype=dtype,
compressor=compressor,
fill_value=fill_value,
order=order,
filters=filters,
overwrite=True,
path=path)
elif mode == 'a':
if contains_group(store, path=path):
err_contains_group(path)
elif not contains_array(store, path=path):
init_array(store,
shape=shape,
chunks=chunks,
dtype=dtype,
compressor=compressor,
fill_value=fill_value,
order=order,
filters=filters,
path=path)
elif mode in ['w-', 'x']:
if contains_group(store, path=path):
err_contains_group(path)
elif contains_array(store, path=path):
err_contains_array(path)
else:
init_array(store,
shape=shape,
chunks=chunks,
dtype=dtype,
compressor=compressor,
fill_value=fill_value,
order=order,
filters=filters,
path=path)
# determine read only status
read_only = mode == 'r'
# instantiate array
z = Array(store,
read_only=read_only,
synchronizer=synchronizer,
cache_metadata=cache_metadata,
path=path)
return z
def open(store, mode='a', **kwargs):
"""Convenience function to open a group or array using file-mode-like semantics.
Parameters
----------
store : MutableMapping or string
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).
**kwargs
Additional parameters are passed through to :func:`zarr.open_array` or
:func:`zarr.open_group`.
See Also
--------
zarr.open_array, zarr.open_group
Examples
--------
Storing data in a directory 'data/example.zarr' on the local file system::
>>> import zarr
>>> store = 'data/example.zarr'
>>> zw = zarr.open(store, mode='w', shape=100, dtype='i4') # open new array
>>> zw
<zarr.core.Array (100,) int32>
>>> za = zarr.open(store, mode='a') # open existing array for reading and writing
>>> za
<zarr.core.Array (100,) int32>
>>> zr = zarr.open(store, mode='r') # open existing array read-only
>>> zr
<zarr.core.Array (100,) int32 read-only>
>>> gw = zarr.open(store, mode='w') # open new group, overwriting previous data
>>> gw
<zarr.hierarchy.Group '/'>
>>> ga = zarr.open(store, mode='a') # open existing group for reading and writing
>>> ga
<zarr.hierarchy.Group '/'>
>>> gr = zarr.open(store, mode='r') # open existing group read-only
>>> gr
<zarr.hierarchy.Group '/' read-only>
"""
path = kwargs.get('path', None)
# handle polymorphic store arg
store = normalize_store_arg(store, clobber=(mode == 'w'))
path = normalize_storage_path(path)
if mode in {'w', 'w-', 'x'}:
if 'shape' in kwargs:
return open_array(store, mode=mode, **kwargs)
else:
return open_group(store, mode=mode, **kwargs)
elif mode == 'a':
if contains_array(store, path):
return open_array(store, mode=mode, **kwargs)
elif contains_group(store, path):
return open_group(store, mode=mode, **kwargs)
elif 'shape' in kwargs:
return open_array(store, mode=mode, **kwargs)
else:
return open_group(store, mode=mode, **kwargs)
else:
if contains_array(store, path):
return open_array(store, mode=mode, **kwargs)
elif contains_group(store, path):
return open_group(store, mode=mode, **kwargs)
else:
err_path_not_found(path)
def open(store: StoreLike = None, mode: str = "a", **kwargs):
"""Convenience function to open a group or array using file-mode-like semantics.
Parameters
----------
store : Store 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).
**kwargs
Additional parameters are passed through to :func:`zarr.creation.open_array` or
:func:`zarr.hierarchy.open_group`.
Returns
-------
z : :class:`zarr.core.Array` or :class:`zarr.hierarchy.Group`
Array or group, depending on what exists in the given store.
See Also
--------
zarr.creation.open_array, zarr.hierarchy.open_group
Examples
--------
Storing data in a directory 'data/example.zarr' on the local file system::
>>> import zarr
>>> store = 'data/example.zarr'
>>> zw = zarr.open(store, mode='w', shape=100, dtype='i4') # open new array
>>> zw
<zarr.core.Array (100,) int32>
>>> za = zarr.open(store, mode='a') # open existing array for reading and writing
>>> za
<zarr.core.Array (100,) int32>
>>> zr = zarr.open(store, mode='r') # open existing array read-only
>>> zr
<zarr.core.Array (100,) int32 read-only>
>>> gw = zarr.open(store, mode='w') # open new group, overwriting previous data
>>> gw
<zarr.hierarchy.Group '/'>
>>> ga = zarr.open(store, mode='a') # open existing group for reading and writing
>>> ga
<zarr.hierarchy.Group '/'>
>>> gr = zarr.open(store, mode='r') # open existing group read-only
>>> gr
<zarr.hierarchy.Group '/' read-only>
"""
path = kwargs.get('path', None)
# handle polymorphic store arg
clobber = mode == 'w'
# we pass storage options explicitly, since normalize_store_arg might construct
# a store if the input is a fsspec-compatible URL
_store: BaseStore = normalize_store_arg(store,
clobber=clobber,
storage_options=kwargs.pop(
"storage_options", {}))
path = normalize_storage_path(path)
if mode in {'w', 'w-', 'x'}:
if 'shape' in kwargs:
return open_array(_store, mode=mode, **kwargs)
else:
return open_group(_store, mode=mode, **kwargs)
elif mode == "a":
if "shape" in kwargs or contains_array(_store, path):
return open_array(_store, mode=mode, **kwargs)
else:
return open_group(_store, mode=mode, **kwargs)
else:
if contains_array(_store, path):
return open_array(_store, mode=mode, **kwargs)
elif contains_group(_store, path):
return open_group(_store, mode=mode, **kwargs)
else:
raise PathNotFoundError(path)
def 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=None,
**kwargs):
"""Open an array using file-mode-like semantics.
Parameters
----------
store : MutableMapping 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).
shape : int or tuple of ints, optional
Array shape.
chunks : int 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.
dtype : string or dtype, optional
NumPy dtype.
compressor : Codec, optional
Primary compressor.
fill_value : object, optional
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).
cache_attrs : bool, 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.
path : string, optional
Array path within store.
object_codec : Codec, optional
A codec to encode object arrays, only needed if dtype=object.
chunk_store : MutableMapping or string, optional
Store or path to directory in file system or name of zip file.
storage_options : dict
If using an fsspec URL to create the store, these will be passed to
the backend implementation. Ignored otherwise.
partial_decompress : bool, 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_chunks : bool, 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.
.. versionadded:: 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.
Returns
-------
z : zarr.core.Array
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
Notes
-----
There is no need to close an array. Data are automatically flushed to the
file system.
"""
# use same mode semantics as h5py
# r : read only, must exist
# r+ : read/write, must exist
# w : create, delete if exists
# w- or x : create, fail if exists
# a : read/write if exists, create otherwise (default)
if zarr_version is None and store is None:
zarr_version = getattr(chunk_store, '_store_version',
DEFAULT_ZARR_VERSION)
# handle polymorphic store arg
store = normalize_store_arg(store,
storage_options=storage_options,
mode=mode,
zarr_version=zarr_version)
zarr_version = getattr(store, '_store_version', DEFAULT_ZARR_VERSION)
if chunk_store is not None:
chunk_store = normalize_store_arg(chunk_store,
storage_options=storage_options,
mode=mode,
zarr_version=zarr_version)
# respect the dimension separator specified in a store, if present
if dimension_separator is None:
if hasattr(store, '_dimension_separator'):
dimension_separator = store._dimension_separator
else:
dimension_separator = '.' if zarr_version == 2 else '/'
if zarr_version == 3 and path is None:
path = 'array' # TODO: raise ValueError instead?
path = normalize_storage_path(path)
# API compatibility with h5py
compressor, fill_value = _kwargs_compat(compressor, fill_value, kwargs)
# ensure fill_value of correct type
if fill_value is not None:
fill_value = np.array(fill_value, dtype=dtype)[()]
# ensure store is initialized
if mode in ['r', 'r+']:
if not contains_array(store, path=path):
if contains_group(store, path=path):
raise ContainsGroupError(path)
raise ArrayNotFoundError(path)
elif mode == 'w':
init_array(store,
shape=shape,
chunks=chunks,
dtype=dtype,
compressor=compressor,
fill_value=fill_value,
order=order,
filters=filters,
overwrite=True,
path=path,
object_codec=object_codec,
chunk_store=chunk_store,
dimension_separator=dimension_separator)
elif mode == 'a':
if not contains_array(store, path=path):
if contains_group(store, path=path):
raise ContainsGroupError(path)
init_array(store,
shape=shape,
chunks=chunks,
dtype=dtype,
compressor=compressor,
fill_value=fill_value,
order=order,
filters=filters,
path=path,
object_codec=object_codec,
chunk_store=chunk_store,
dimension_separator=dimension_separator)
elif mode in ['w-', 'x']:
if contains_group(store, path=path):
raise ContainsGroupError(path)
elif contains_array(store, path=path):
raise ContainsArrayError(path)
else:
init_array(store,
shape=shape,
chunks=chunks,
dtype=dtype,
compressor=compressor,
fill_value=fill_value,
order=order,
filters=filters,
path=path,
object_codec=object_codec,
chunk_store=chunk_store,
dimension_separator=dimension_separator)
# determine read only status
read_only = mode == 'r'
# instantiate array
z = Array(store,
read_only=read_only,
synchronizer=synchronizer,
cache_metadata=cache_metadata,
cache_attrs=cache_attrs,
path=path,
chunk_store=chunk_store,
write_empty_chunks=write_empty_chunks)
return z
def open_array(store, 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,
**kwargs):
"""Open an array using file-mode-like semantics.
Parameters
----------
store : MutableMapping or string
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).
shape : int or tuple of ints, optional
Array shape.
chunks : int 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.
dtype : string or dtype, optional
NumPy dtype.
compressor : Codec, optional
Primary compressor.
fill_value : object, optional
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).
cache_attrs : bool, 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.
path : string, optional
Array path within store.
object_codec : Codec, optional
A codec to encode object arrays, only needed if dtype=object.
Returns
-------
z : zarr.core.Array
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
Notes
-----
There is no need to close an array. Data are automatically flushed to the
file system.
"""
# use same mode semantics as h5py
# r : read only, must exist
# r+ : read/write, must exist
# w : create, delete if exists
# w- or x : create, fail if exists
# a : read/write if exists, create otherwise (default)
# handle polymorphic store arg
store = normalize_store_arg(store, clobber=(mode == 'w'))
path = normalize_storage_path(path)
# API compatibility with h5py
compressor, fill_value = _kwargs_compat(compressor, fill_value, kwargs)
# ensure fill_value of correct type
if fill_value is not None:
fill_value = np.array(fill_value, dtype=dtype)[()]
# ensure store is initialized
if mode in ['r', 'r+']:
if contains_group(store, path=path):
err_contains_group(path)
elif not contains_array(store, path=path):
err_array_not_found(path)
elif mode == 'w':
init_array(store, shape=shape, chunks=chunks, dtype=dtype,
compressor=compressor, fill_value=fill_value,
order=order, filters=filters, overwrite=True, path=path,
object_codec=object_codec)
elif mode == 'a':
if contains_group(store, path=path):
err_contains_group(path)
elif not contains_array(store, path=path):
init_array(store, shape=shape, chunks=chunks, dtype=dtype,
compressor=compressor, fill_value=fill_value,
order=order, filters=filters, path=path,
object_codec=object_codec)
elif mode in ['w-', 'x']:
if contains_group(store, path=path):
err_contains_group(path)
elif contains_array(store, path=path):
err_contains_array(path)
else:
init_array(store, shape=shape, chunks=chunks, dtype=dtype,
compressor=compressor, fill_value=fill_value,
order=order, filters=filters, path=path,
object_codec=object_codec)
# determine read only status
read_only = mode == 'r'
# instantiate array
z = Array(store, read_only=read_only, synchronizer=synchronizer,
cache_metadata=cache_metadata, cache_attrs=cache_attrs, path=path)
return z
def group(store=None,
overwrite=False,
chunk_store=None,
cache_attrs=True,
synchronizer=None,
path=None,
*,
zarr_version=None):
"""Create a group.
Parameters
----------
store : MutableMapping or string, optional
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.
cache_attrs : bool, 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.
synchronizer : object, optional
Array synchronizer.
path : string, optional
Group path within store.
Returns
-------
g : zarr.hierarchy.Group
Examples
--------
Create a group in memory::
>>> import zarr
>>> g = zarr.group()
>>> g
<zarr.hierarchy.Group '/'>
Create a group with a different store::
>>> store = zarr.DirectoryStore('data/example.zarr')
>>> g = zarr.group(store=store, overwrite=True)
>>> g
<zarr.hierarchy.Group '/'>
"""
# handle polymorphic store arg
store = _normalize_store_arg(store, zarr_version=zarr_version)
if zarr_version is None:
zarr_version = getattr(store, '_store_version', DEFAULT_ZARR_VERSION)
if zarr_version == 3 and path is None:
raise ValueError(f"path must be provided for a v{zarr_version} group")
path = normalize_storage_path(path)
if zarr_version == 2:
requires_init = overwrite or not contains_group(store)
elif zarr_version == 3:
requires_init = overwrite or not contains_group(store, path)
if requires_init:
init_group(store,
overwrite=overwrite,
chunk_store=chunk_store,
path=path)
return Group(store,
read_only=False,
chunk_store=chunk_store,
cache_attrs=cache_attrs,
synchronizer=synchronizer,
path=path,
zarr_version=zarr_version)
def open(store, mode='a', **kwargs):
"""Convenience function to open a group or array using file-mode-like semantics.
Parameters
----------
store : MutableMapping or string
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).
**kwargs
Additional parameters are passed through to :func:`zarr.open_array` or
:func:`zarr.open_group`.
See Also
--------
zarr.open_array, zarr.open_group
Examples
--------
Storing data in a directory 'data/example.zarr' on the local file system::
>>> import zarr
>>> store = 'data/example.zarr'
>>> zw = zarr.open(store, mode='w', shape=100, dtype='i4') # open new array
>>> zw
<zarr.core.Array (100,) int32>
>>> za = zarr.open(store, mode='a') # open existing array for reading and writing
>>> za
<zarr.core.Array (100,) int32>
>>> zr = zarr.open(store, mode='r') # open existing array read-only
>>> zr
<zarr.core.Array (100,) int32 read-only>
>>> gw = zarr.open(store, mode='w') # open new group, overwriting previous data
>>> gw
<zarr.hierarchy.Group '/'>
>>> ga = zarr.open(store, mode='a') # open existing group for reading and writing
>>> ga
<zarr.hierarchy.Group '/'>
>>> gr = zarr.open(store, mode='r') # open existing group read-only
>>> gr
<zarr.hierarchy.Group '/' read-only>
"""
path = kwargs.get('path', None)
# handle polymorphic store arg
store = normalize_store_arg(store, clobber=(mode == 'w'))
path = normalize_storage_path(path)
if mode in {'w', 'w-', 'x'}:
if 'shape' in kwargs:
return open_array(store, mode=mode, **kwargs)
else:
return open_group(store, mode=mode, **kwargs)
elif mode == 'a':
if contains_array(store, path):
return open_array(store, mode=mode, **kwargs)
elif contains_group(store, path):
return open_group(store, mode=mode, **kwargs)
elif 'shape' in kwargs:
return open_array(store, mode=mode, **kwargs)
else:
return open_group(store, mode=mode, **kwargs)
else:
if contains_array(store, path):
return open_array(store, mode=mode, **kwargs)
elif contains_group(store, path):
return open_group(store, mode=mode, **kwargs)
else:
err_path_not_found(path)
def open_group(store=None, mode='a', cache_attrs=True, synchronizer=None, path=None,
chunk_store=None, storage_options=None):
"""Open a group using file-mode-like semantics.
Parameters
----------
store : MutableMapping 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).
cache_attrs : bool, 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.
synchronizer : object, optional
Array synchronizer.
path : string, optional
Group path within store.
chunk_store : MutableMapping or string, optional
Store or path to directory in file system or name of zip file.
storage_options : dict
If using an fsspec URL to create the store, these will be passed to
the backend implementation. Ignored otherwise.
Returns
-------
g : zarr.hierarchy.Group
Examples
--------
>>> import zarr
>>> root = zarr.open_group('data/example.zarr', mode='w')
>>> foo = root.create_group('foo')
>>> bar = root.create_group('bar')
>>> root
<zarr.hierarchy.Group '/'>
>>> root2 = zarr.open_group('data/example.zarr', mode='a')
>>> root2
<zarr.hierarchy.Group '/'>
>>> root == root2
True
"""
# handle polymorphic store arg
clobber = mode != "r"
store = _normalize_store_arg(
store, clobber=clobber, storage_options=storage_options, mode=mode
)
if chunk_store is not None:
chunk_store = _normalize_store_arg(chunk_store, clobber=clobber,
storage_options=storage_options)
path = normalize_storage_path(path)
# ensure store is initialized
if mode in ['r', 'r+']:
if contains_array(store, path=path):
raise ContainsArrayError(path)
elif not contains_group(store, path=path):
raise GroupNotFoundError(path)
elif mode == 'w':
init_group(store, overwrite=True, path=path, chunk_store=chunk_store)
elif mode == 'a':
if contains_array(store, path=path):
raise ContainsArrayError(path)
if not contains_group(store, path=path):
init_group(store, path=path, chunk_store=chunk_store)
elif mode in ['w-', 'x']:
if contains_array(store, path=path):
raise ContainsArrayError(path)
elif contains_group(store, path=path):
raise ContainsGroupError(path)
else:
init_group(store, path=path, chunk_store=chunk_store)
# determine read only status
read_only = mode == 'r'
return Group(store, read_only=read_only, cache_attrs=cache_attrs,
synchronizer=synchronizer, path=path, chunk_store=chunk_store)
def open_group(store, mode='a', cache_attrs=True, synchronizer=None, path=None):
"""Open a group using file-mode-like semantics.
Parameters
----------
store : MutableMapping or string
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).
cache_attrs : bool, 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.
synchronizer : object, optional
Array synchronizer.
path : string, optional
Group path within store.
Returns
-------
g : zarr.hierarchy.Group
Examples
--------
>>> import zarr
>>> root = zarr.open_group('data/example.zarr', mode='w')
>>> foo = root.create_group('foo')
>>> bar = root.create_group('bar')
>>> root
<zarr.hierarchy.Group '/'>
>>> root2 = zarr.open_group('data/example.zarr', mode='a')
>>> root2
<zarr.hierarchy.Group '/'>
>>> root == root2
True
"""
# handle polymorphic store arg
store = _normalize_store_arg(store)
path = normalize_storage_path(path)
# ensure store is initialized
if mode in ['r', 'r+']:
if contains_array(store, path=path):
err_contains_array(path)
elif not contains_group(store, path=path):
err_group_not_found(path)
elif mode == 'w':
init_group(store, overwrite=True, path=path)
elif mode == 'a':
if contains_array(store, path=path):
err_contains_array(path)
if not contains_group(store, path=path):
init_group(store, path=path)
elif mode in ['w-', 'x']:
if contains_array(store, path=path):
err_contains_array(path)
elif contains_group(store, path=path):
err_contains_group(path)
else:
init_group(store, path=path)
# determine read only status
read_only = mode == 'r'
return Group(store, read_only=read_only, cache_attrs=cache_attrs,
synchronizer=synchronizer, path=path)
def 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
"""
# handle polymorphic store arg
store = _handle_store_arg(store)
path = normalize_storage_path(path)
# ensure store is initialized
if mode in ['r', 'r+']:
if contains_array(store, path=path):
err_contains_array(path)
elif not contains_group(store, path=path):
err_group_not_found(path)
elif mode == 'w':
init_group(store, overwrite=True, path=path)
elif mode == 'a':
if contains_array(store, path=path):
err_contains_array(path)
if not contains_group(store, path=path):
init_group(store, path=path)
elif mode in ['w-', 'x']:
if contains_array(store, path=path):
err_contains_array(path)
elif contains_group(store, path=path):
err_contains_group(path)
else:
init_group(store, path=path)
# determine read only status
read_only = mode == 'r'
return Group(store, read_only=read_only, synchronizer=synchronizer,
path=path)
def 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,
**kwargs):
"""Open an array using file-mode-like semantics.
Parameters
----------
store : MutableMapping 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).
shape : int or tuple of ints, optional
Array shape.
chunks : int 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.
dtype : string or dtype, optional
NumPy dtype.
compressor : Codec, optional
Primary compressor.
fill_value : object, optional
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).
cache_attrs : bool, 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.
path : string, optional
Array path within store.
object_codec : Codec, optional
A codec to encode object arrays, only needed if dtype=object.
chunk_store : MutableMapping or string, optional
Store or path to directory in file system or name of zip file.
storage_options : dict
If using an fsspec URL to create the store, these will be passed to
the backend implementation. Ignored otherwise.
partial_decompress : bool, optional
If True and while the chunk_store is a FSStore and the compresion used
is Blosc, when getting data from the array chunks will be partially
read and decompressed when possible.
.. versionadded:: 2.7
Returns
-------
z : zarr.core.Array
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
Notes
-----
There is no need to close an array. Data are automatically flushed to the
file system.
"""
# use same mode semantics as h5py
# r : read only, must exist
# r+ : read/write, must exist
# w : create, delete if exists
# w- or x : create, fail if exists
# a : read/write if exists, create otherwise (default)
# handle polymorphic store arg
clobber = (mode == 'w')
store = normalize_store_arg(store,
clobber=clobber,
storage_options=storage_options,
mode=mode)
if chunk_store is not None:
chunk_store = normalize_store_arg(chunk_store,
clobber=clobber,
storage_options=storage_options)
path = normalize_storage_path(path)
# API compatibility with h5py
compressor, fill_value = _kwargs_compat(compressor, fill_value, kwargs)
# ensure fill_value of correct type
if fill_value is not None:
fill_value = np.array(fill_value, dtype=dtype)[()]
# ensure store is initialized
if mode in ['r', 'r+']:
if contains_group(store, path=path):
raise ContainsGroupError(path)
elif not contains_array(store, path=path):
raise ArrayNotFoundError(path)
elif mode == 'w':
init_array(store,
shape=shape,
chunks=chunks,
dtype=dtype,
compressor=compressor,
fill_value=fill_value,
order=order,
filters=filters,
overwrite=True,
path=path,
object_codec=object_codec,
chunk_store=chunk_store)
elif mode == 'a':
if contains_group(store, path=path):
raise ContainsGroupError(path)
elif not contains_array(store, path=path):
init_array(store,
shape=shape,
chunks=chunks,
dtype=dtype,
compressor=compressor,
fill_value=fill_value,
order=order,
filters=filters,
path=path,
object_codec=object_codec,
chunk_store=chunk_store)
elif mode in ['w-', 'x']:
if contains_group(store, path=path):
raise ContainsGroupError(path)
elif contains_array(store, path=path):
raise ContainsArrayError(path)
else:
init_array(store,
shape=shape,
chunks=chunks,
dtype=dtype,
compressor=compressor,
fill_value=fill_value,
order=order,
filters=filters,
path=path,
object_codec=object_codec,
chunk_store=chunk_store)
# determine read only status
read_only = mode == 'r'
# instantiate array
z = Array(store,
read_only=read_only,
synchronizer=synchronizer,
cache_metadata=cache_metadata,
cache_attrs=cache_attrs,
path=path,
chunk_store=chunk_store)
return z
