v2
NodeSpec #
Bases: StrictBase
The base class for V2 ArraySpec
and GroupSpec
.
Attributes:
Name | Type | Description |
---|---|---|
zarr_format |
Literal[2]
|
The Zarr version represented by this node. Must be 2. |
ArraySpec #
Bases: NodeSpec
, Generic[TAttr]
A model of a Zarr Version 2 Array. The specification for the data structure being modeled by this class can be found in the Zarr specification.
Attributes:
Name | Type | Description |
---|---|---|
attributes |
TAttr, default = {}
|
User-defined metadata associated with this array. Should be JSON-serializable. |
shape |
tuple[int, ...]
|
The shape of this array. |
dtype |
str
|
The data type of this array. |
chunks |
Tuple[int, ...]
|
The chunk size for this array. |
order |
"C" | "F", default = "C"
|
The memory order of this array. Must be either "C", which designates "C order", AKA lexicographic ordering or "F", which designates "F order", AKA colexicographic ordering. The default is "C". |
fill_value |
FillValue, default = 0
|
The fill value for this array. The default is 0. |
compressor |
CodecDict | None
|
A JSON-serializable representation of a compression codec, or None. The default is None. |
filters |
List[CodecDict] | None, default = None
|
A list of JSON-serializable representations of compression codec, or None. The default is None. |
dimension_separator |
"." | "/", default = "/"
|
The character used for partitioning the different dimensions of a chunk key. Must be either "/" or ".", or absent, in which case it is interpreted as ".". The default is "/". |
check_ndim #
Check that the shape
and chunks
and attributes have the same length.
Source code in src/pydantic_zarr/v2.py
from_array
classmethod
#
from_array(
array,
chunks="auto",
attributes="auto",
fill_value="auto",
order="auto",
filters="auto",
dimension_separator="auto",
compressor="auto",
)
Create an ArraySpec
from an array-like object. This is a convenience method for when Zarr array will be modelled from an existing array.
This method takes nearly the same arguments as the ArraySpec
constructor, minus shape
and dtype
, which will be inferred from the array
argument.
Additionally, this method accepts the string "auto" as a parameter for all other ArraySpec
attributes, in which case these attributes will be
inferred from the array
argument, with a fallback value equal to the default ArraySpec
parameters.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
array |
an array-like object.
|
Must have |
required |
attributes |
Literal['auto'] | TAttr
|
User-defined metadata associated with this array. Should be JSON-serializable. The default is "auto", which means that |
'auto'
|
chunks |
Literal['auto'] | tuple[int, ...]
|
The chunks for this |
'auto'
|
order |
Literal['auto', 'C', 'F']
|
The memory order of the |
'auto'
|
fill_value |
Literal['auto'] | int | float | None
|
The fill value for this array. Either "auto" or FillValue. The default is "auto", which means that |
'auto'
|
compressor |
Literal['auto'] | CodecDict | None
|
The compressor for this |
'auto'
|
filters |
Literal['auto'] | list[CodecDict] | None
|
The filters for this |
'auto'
|
dimension_separator |
Literal['auto', '/', '.']
|
Sets the character used for partitioning the different dimensions of a chunk key.
Must be one of "auto", "/" or ".". The default is "auto", which means that |
'auto'
|
Returns:
Type | Description |
---|---|
ArraySpec
|
An instance of |
Examples:
>>> from pydantic_zarr.v2 import ArraySpec
>>> import numpy as np
>>> x = ArraySpec.from_array(np.arange(10))
>>> x
ArraySpec(zarr_version=2, attributes={}, shape=(10,), chunks=(10,), dtype='<i8', fill_value=0, order='C', filters=None, dimension_separator='/', compressor=None)
Source code in src/pydantic_zarr/v2.py
181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 |
|
from_zarr
classmethod
#
Create an ArraySpec
from an instance of zarr.Array
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
array |
Array
|
|
required |
Returns:
Type | Description |
---|---|
ArraySpec
|
An instance of |
Examples:
>>> import zarr
>>> from pydantic_zarr.v2 import ArraySpec
>>> x = zarr.create((10,10))
>>> ArraySpec.from_zarr(x)
ArraySpec(zarr_version=2, attributes={}, shape=(10, 10), chunks=(10, 10), dtype='<f8', fill_value=0.0, order='C', filters=None, dimension_separator='.', compressor={'id': 'blosc', 'cname': 'lz4', 'clevel': 5, 'shuffle': 1, 'blocksize': 0})
Source code in src/pydantic_zarr/v2.py
to_zarr #
Serialize an ArraySpec
to a Zarr array at a specific path in a Zarr store. This operation
will create metadata documents in the store, but will not write any chunks.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
store |
instance of zarr.BaseStore
|
The storage backend that will manifest the array. |
required |
path |
str
|
The location of the array inside the store. |
required |
overwrite |
bool
|
Whether to overwrite existing objects in storage to create the Zarr array. |
False
|
**kwargs |
Any
|
Additional keyword arguments are passed to |
{}
|
Returns:
Type | Description |
---|---|
Array
|
A Zarr array that is structurally identical to |
Source code in src/pydantic_zarr/v2.py
like #
Compare am ArraySpec
to another ArraySpec
or a zarr.Array
, parameterized over the
fields to exclude or include in the comparison. Models are first converted to dict
via the
model_dump
method of pydantic.BaseModel
, then compared with the ==
operator.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
other |
ArraySpec | Array
|
The array (model or actual) to compare with. If other is a |
required |
include |
IncEx
|
A specification of fields to include in the comparison. The default value is |
None
|
exclude |
IncEx
|
A specification of fields to exclude from the comparison. The default value is |
None
|
Returns:
Type | Description |
---|---|
bool
|
|
Examples:
>>> import zarr
>>> from pydantic_zarr.v2 import ArraySpec
>>> x = zarr.create((10,10))
>>> x.attrs.put({'foo': 10})
>>> x_model = ArraySpec.from_zarr(x)
>>> print(x_model.like(x_model)) # it is like itself.
True
>>> print(x_model.like(x))
True
>>> y = zarr.create((10,10))
>>> y.attrs.put({'foo': 11}) # x and y are the same, other than their attrs
>>> print(x_model.like(y))
False
>>> print(x_model.like(y, exclude={'attributes'}))
True
Source code in src/pydantic_zarr/v2.py
GroupSpec #
Bases: NodeSpec
, Generic[TAttr, TItem]
A model of a Zarr Version 2 Group. The specification for the data structure being modeled by this class can be found in the Zarr specification.
Attributes:
Name | Type | Description |
---|---|---|
attributes |
TAttr, default = {}
|
The user-defined attributes of this group. Should be JSON-serializable. |
members |
dict[str, TItem] | None, default = {}
|
The members of this group. |
from_zarr
classmethod
#
Create a GroupSpec from an instance of zarr.Group
. Subgroups and arrays contained in the
Zarr group will be converted to instances of GroupSpec
and ArraySpec
, respectively,
and these spec instances will be stored in the members
attribute of the parent
GroupSpec
.
This is a recursive function, and the depth of recursion can be controlled by the depth
keyword argument. The default value for depth
is -1, which directs this function to
traverse the entirety of a zarr.Group
. This may be slow for large hierarchies, in which
case setting depth
to a positive integer can limit how deep into the hierarchy the
recursion goes.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
group |
Group
|
The Zarr group to model. |
required |
depth |
int
|
An integer which may be no lower than -1. Determines how far into the tree to parse. |
-1
|
Returns:
Type | Description |
---|---|
An instance of GroupSpec that represents the structure of the Zarr hierarchy.
|
|
Source code in src/pydantic_zarr/v2.py
to_zarr #
Serialize this GroupSpec
to a Zarr group at a specific path in a zarr.BaseStore
.
This operation will create metadata documents in the store.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
store |
BaseStore
|
The storage backend that will manifest the group and its contents. |
required |
path |
str
|
The location of the group inside the store. |
required |
overwrite |
bool
|
Whether to overwrite existing objects in storage to create the Zarr group. |
False
|
**kwargs |
Any
|
Additional keyword arguments that will be passed to |
{}
|
Returns:
Type | Description |
---|---|
Group
|
A zarr group that is structurally identical to |
Source code in src/pydantic_zarr/v2.py
like #
Compare a GroupSpec
to another GroupSpec
or a zarr.Group
, parameterized over the
fields to exclude or include in the comparison. Models are first converted to dict via the
model_dump
method of pydantic.BaseModel
, then compared with the ==
operator.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
other |
GroupSpec | Group
|
The group (model or actual) to compare with. If other is a |
required |
include |
IncEx
|
A specification of fields to include in the comparison. The default is |
None
|
exclude |
IncEx
|
A specification of fields to exclude from the comparison. The default is |
None
|
Returns:
Type | Description |
---|---|
bool
|
|
Examples:
>>> import zarr
>>> from pydantic_zarr.v2 import GroupSpec
>>> import numpy as np
>>> z1 = zarr.group(path='z1')
>>> z1a = z1.array(name='foo', data=np.arange(10))
>>> z1_model = GroupSpec.from_zarr(z1)
>>> print(z1_model.like(z1_model)) # it is like itself
True
>>> print(z1_model.like(z1))
True
>>> z2 = zarr.group(path='z2')
>>> z2a = z2.array(name='foo', data=np.arange(10))
>>> print(z1_model.like(z2))
True
>>> z2.attrs.put({'foo' : 100}) # now they have different attributes
>>> print(z1_model.like(z2))
False
>>> print(z1_model.like(z2, exclude={'attributes'}))
True
Source code in src/pydantic_zarr/v2.py
to_flat #
Flatten this GroupSpec
.
This method returns a dict
with string keys and values that are GroupSpec
or
ArraySpec
.
Then the resulting dict
will contain a copy of the input with a null members
attribute
under the key root_path
, as well as copies of the result of calling node.to_flat
on each
element of node.members
, each under a key created by joining root_path
with a '/`
character to the name of each member, and so on recursively for each sub-member.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
root_path |
str
|
The root path. The keys in |
''
|
Returns:
Type | Description |
---|---|
Dict[str, ArraySpec | GroupSpec]
|
A flattened representation of the hierarchy. |
Examples:
>>> from pydantic_zarr.v2 import to_flat, GroupSpec
>>> g1 = GroupSpec(members=None, attributes={'foo': 'bar'})
>>> to_flat(g1)
{'': GroupSpec(zarr_version=2, attributes={'foo': 'bar'}, members=None)}
>>> to_flat(g1 root_path='baz')
{'baz': GroupSpec(zarr_version=2, attributes={'foo': 'bar'}, members=None)}
>>> to_flat(GroupSpec(members={'g1': g1}, attributes={'foo': 'bar'}))
{'/g1': GroupSpec(zarr_version=2, attributes={'foo': 'bar'}, members=None), '': GroupSpec(zarr_version=2, attributes={'foo': 'bar'}, members=None)}
Source code in src/pydantic_zarr/v2.py
from_flat
classmethod
#
Create a GroupSpec
from a flat hierarchy representation. The flattened hierarchy is a
dict
with the following constraints: keys must be valid paths; values must
be ArraySpec
or GroupSpec
instances.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data |
Dict[str, ArraySpec | GroupSpec]
|
A flattened representation of a Zarr hierarchy. |
required |
Returns:
Type | Description |
---|---|
GroupSpec
|
A |
Examples:
>>> from pydantic_zarr.v2 import GroupSpec, ArraySpec
>>> import numpy as np
>>> flat = {'': GroupSpec(attributes={'foo': 10}, members=None)}
>>> GroupSpec.from_flat(flat)
GroupSpec(zarr_version=2, attributes={'foo': 10}, members={})
>>> flat = {
'': GroupSpec(attributes={'foo': 10}, members=None),
'/a': ArraySpec.from_array(np.arange(10))}
>>> GroupSpec.from_flat(flat)
GroupSpec(zarr_version=2, attributes={'foo': 10}, members={'a': ArraySpec(zarr_version=2, attributes={}, shape=(10,), chunks=(10,), dtype='<i8', fill_value=0, order='C', filters=None, dimension_separator='/', compressor=None)})
Source code in src/pydantic_zarr/v2.py
stringify_dtype #
Convert a numpy.dtype
object into a str
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
value |
DTypeLike
|
Some object that can be coerced to a numpy dtype |
required |
Returns:
Type | Description |
---|---|
A numpy dtype string representation of `value`.
|
|
Source code in src/pydantic_zarr/v2.py
dictify_codec #
Ensure that a numcodecs.abc.Codec
is converted to a dict
. If the input is not an
insance of numcodecs.abc.Codec
, then it is assumed to be a dict
with string keys
and it is returned unaltered.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
value |
dict[str, Any] | Codec
|
The value to be dictified if it is not already a dict. |
required |
Returns:
Type | Description |
---|---|
dict[str, Any]
|
If the input was a |
Source code in src/pydantic_zarr/v2.py
parse_dimension_separator #
Parse the dimension_separator metadata as per the Zarr version 2 specification.
If the input is None
, this returns ".".
If the input is either "." or "/", this returns it.
Otherwise, raises a ValueError.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data |
Any
|
The input data to parse. |
required |
Returns:
Type | Description |
---|---|
Literal['/', '.']
|
|
Source code in src/pydantic_zarr/v2.py
from_zarr #
Recursively parse a zarr.Group
or zarr.Array
into an ArraySpec
or GroupSpec
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
element |
Array | Group
|
The |
required |
depth |
int
|
An integer which may be no lower than -1. If |
-1
|
Returns:
Type | Description |
---|---|
ArraySpec | GroupSpec
|
An instance of |
Source code in src/pydantic_zarr/v2.py
to_zarr #
Serialize a GroupSpec
or ArraySpec
to a Zarr group or array at a specific path in
a Zarr store.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
spec |
ArraySpec | GroupSpec
|
The |
required |
store |
BaseStore
|
The storage backend that will manifest the Zarr group or array modeled by |
required |
path |
str
|
The location of the Zarr group or array inside the store. |
required |
overwrite |
bool
|
Whether to overwrite existing objects in storage to create the Zarr group or array. |
= False
|
**kwargs |
Additional keyword arguments will be |
{}
|
Returns:
Type | Description |
---|---|
Array | Group
|
A |
Source code in src/pydantic_zarr/v2.py
to_flat #
Flatten a GroupSpec
or ArraySpec
.
Converts a GroupSpec
or ArraySpec
and a string, into a dict
with string keys and
values that are GroupSpec
or ArraySpec
.
If the input is an ArraySpec
, then this function just returns the dict {root_path: node}
.
If the input is a GroupSpec
, then the resulting dict
will contain a copy of the input
with a null members
attribute under the key root_path
, as well as copies of the result of
calling flatten_node
on each element of node.members
, each under a key created by joining
root_path
with a '/` character to the name of each member, and so on recursively for each
sub-member.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
node |
ArraySpec | GroupSpec
|
The node to flatten. |
required |
root_path |
str
|
The root path. If |
''
|
Returns:
Type | Description |
---|---|
Dict[str, ArraySpec | GroupSpec]
|
A flattened representation of the hierarchy. |
Examples:
>>> from pydantic_zarr.v2 import flatten, GroupSpec
>>> g1 = GroupSpec(members=None, attributes={'foo': 'bar'})
>>> to_flat(g1)
{'': GroupSpec(zarr_version=2, attributes={'foo': 'bar'}, members=None)}
>>> to_flat(g1 root_path='baz')
{'baz': GroupSpec(zarr_version=2, attributes={'foo': 'bar'}, members=None)}
>>> to_flat(GroupSpec(members={'g1': g1}, attributes={'foo': 'bar'}))
{'/g1': GroupSpec(zarr_version=2, attributes={'foo': 'bar'}, members=None), '': GroupSpec(zarr_version=2, attributes={'foo': 'bar'}, members=None)}
Source code in src/pydantic_zarr/v2.py
from_flat #
Wraps from_flat_group
, handling the special case where a Zarr array is defined at the root of
a hierarchy and thus is not contained by a Zarr group.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data |
Dict[str, ArraySpec | GroupSpec]
|
A flat representation of a Zarr hierarchy. This is a |
required |
Returns:
Type | Description |
---|---|
ArraySpec | GroupSpec
|
The |
Examples:
>>> from pydantic_zarr.v2 import from_flat, GroupSpec, ArraySpec
>>> import numpy as np
>>> tree = {'': ArraySpec.from_array(np.arange(10))}
>>> from_flat(tree) # special case of a Zarr array at the root of the hierarchy
ArraySpec(zarr_version=2, attributes={}, shape=(10,), chunks=(10,), dtype='<i8', fill_value=0, order='C', filters=None, dimension_separator='/', compressor=None)
>>> tree = {'/foo': ArraySpec.from_array(np.arange(10))}
>>> from_flat(tree) # note that an implicit Group is created
GroupSpec(zarr_version=2, attributes={}, members={'foo': ArraySpec(zarr_version=2, attributes={}, shape=(10,), chunks=(10,), dtype='<i8', fill_value=0, order='C', filters=None, dimension_separator='/', compressor=None)})
Source code in src/pydantic_zarr/v2.py
from_flat_group #
Generate a GroupSpec
from a flat representation of a hierarchy, i.e. a dict
with
string keys (paths) and ArraySpec
/ GroupSpec
values (nodes).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
data |
Dict[str, ArraySpec | GroupSpec]
|
A flat representation of a Zarr hierarchy rooted at a Zarr group. |
required |
Returns:
Type | Description |
---|---|
GroupSpec
|
A |
Examples:
>>> from pydantic_zarr.v2 import from_flat_group, GroupSpec, ArraySpec
>>> import numpy as np
>>> tree = {'/foo': ArraySpec.from_array(np.arange(10))}
>>> from_flat_group(tree) # note that an implicit Group is created
GroupSpec(zarr_version=2, attributes={}, members={'foo': ArraySpec(zarr_version=2, attributes={}, shape=(10,), chunks=(10,), dtype='<i8', fill_value=0, order='C', filters=None, dimension_separator='/', compressor=None)})
Source code in src/pydantic_zarr/v2.py
912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 |
|
auto_chunks #
Guess chunks from:
input with a chunksize
attribute, or
input with a chunks
attribute, or,
input with shape
and dtype
attributes
Source code in src/pydantic_zarr/v2.py
auto_attributes #
Guess attributes from:
input with an attrs
attribute, or
input with an attributes
attribute,
or anything (returning {})
Source code in src/pydantic_zarr/v2.py
auto_fill_value #
Guess fill value from an input with a fill_value
attribute, returning 0 otherwise.
auto_compresser #
Guess compressor from an input with a compressor
attribute, returning None
otherwise.
auto_filters #
Guess filters from an input with a filters
attribute, returning None
otherwise.
auto_order #
Guess array order from an input with an order
attribute, returning "C" otherwise.
auto_dimension_separator #
Guess dimension separator from an input with a dimension_separator
attribute, returning "/" otherwise.