hdmf.spec.spec module

class hdmf.spec.spec.DtypeHelper

Bases: object

primary_dtype_synonyms = {'ascii': ['ascii', 'bytes'], 'bool': ['bool'], 'double': ['double', 'float64'], 'float': ['float', 'float32'], 'int': ['int32', 'int'], 'int8': ['int8'], 'isodatetime': ['isodatetime', 'datetime', 'date'], 'long': ['int64', 'long'], 'numeric': ['numeric'], 'object': ['object'], 'region': ['region'], 'short': ['int16', 'short'], 'uint16': ['uint16'], 'uint32': ['uint32', 'uint'], 'uint64': ['uint64'], 'uint8': ['uint8'], 'utf': ['text', 'utf', 'utf8', 'utf-8']}
recommended_primary_dtypes = ['float', 'double', 'short', 'int', 'long', 'utf', 'ascii', 'bool', 'int8', 'uint8', 'uint16', 'uint32', 'uint64', 'object', 'region', 'numeric', 'isodatetime']
valid_primary_dtypes = {'ascii', 'bool', 'bytes', 'date', 'datetime', 'double', 'float', 'float32', 'float64', 'int', 'int16', 'int32', 'int64', 'int8', 'isodatetime', 'long', 'numeric', 'object', 'region', 'short', 'text', 'uint', 'uint16', 'uint32', 'uint64', 'uint8', 'utf', 'utf-8', 'utf8'}
static simplify_cpd_type(cpd_type)

Transform a list of DtypeSpecs into a list of strings. Use for simple representation of compound type and validation.

Parameters:

cpd_type (list) – The list of DtypeSpecs to simplify

static check_dtype(dtype)

Check that the dtype string is a reference or a valid primary dtype.

class hdmf.spec.spec.ConstructableDict

Bases: dict

classmethod build_const_args(spec_dict)

Build constructor arguments for this ConstructableDict class from a dictionary

classmethod build_spec(spec_dict)

Build a Spec object from the given Spec dict

class hdmf.spec.spec.Spec(doc, name=None, required=True, parent=None)

Bases: ConstructableDict

A base specification class

Parameters:

  • doc (str) – a description about what this specification represents

  • name (str) – The name of this attribute

  • required (bool) – whether or not this attribute is required

  • parent (Spec) – the parent of this spec

property doc

Documentation on what this Spec is specifying

property name

The name of the object being specified

property parent

The parent specification of this specification

classmethod build_const_args(spec_dict)

Build constructor arguments for this Spec class from a dictionary

property path
class hdmf.spec.spec.RefSpec(target_type, reftype)

Bases: ConstructableDict

Parameters:

  • target_type (str) – the target type GroupSpec or DatasetSpec

  • reftype (str) – the type of references this is i.e. region or object

property target_type

The data_type of the target of the reference

property reftype

The type of reference

is_region()
Returns:

True if this RefSpec specifies a region reference, False otherwise

Return type:

bool

class hdmf.spec.spec.AttributeSpec(name, doc, dtype, shape=None, dims=None, required=True, parent=None, value=None, default_value=None)

Bases: Spec

Specification for attributes

Parameters:

  • name (str) – The name of this attribute

  • doc (str) – a description about what this specification represents

  • dtype (str or RefSpec) – The data type of this attribute

  • shape (list or tuple) – the shape of this dataset

  • dims (list or tuple) – the dimensions of this dataset

  • required (bool) – whether or not this attribute is required. ignored when “value” is specified

  • parent (BaseStorageSpec) – the parent of this spec

  • value (None) – a constant value for this attribute

  • default_value (None) – a default value for this attribute

property dtype

The data type of the attribute

property value

The constant value of the attribute. “None” if this attribute is not constant

property default_value

The default value of the attribute. “None” if this attribute has no default value

property required

True if this attribute is required, False otherwise.

property dims

The dimensions of this attribute’s value

property shape

The shape of this attribute’s value

classmethod build_const_args(spec_dict)

Build constructor arguments for this Spec class from a dictionary

class hdmf.spec.spec.BaseStorageSpec(doc, name=None, default_name=None, attributes=[], linkable=True, quantity=1, data_type_def=None, data_type_inc=None)

Bases: Spec

A specification for any object that can hold attributes.

Parameters:

  • doc (str) – a description about what this specification represents

  • name (str) – the name of this base storage container, allowed only if quantity is not ‘+’ or ‘*’

  • default_name (str) – The default name of this base storage container, used only if name is None

  • attributes (list) – the attributes on this group

  • linkable (bool) – whether or not this group can be linked

  • quantity (str or int) – the required number of allowed instance

  • data_type_def (str) – the data type this specification represents

  • data_type_inc (str or BaseStorageSpec) – the data type this specification extends

property default_name

The default name for this spec

property resolved
property required

Whether or not the this spec represents a required field

resolve_spec(inc_spec)

Add attributes from the inc_spec to this spec and track which attributes are new and overridden.

Parameters:

inc_spec (BaseStorageSpec) – the data type this specification represents

is_inherited_spec(spec)

Return True if this spec was inherited from the parent type, False otherwise.

Returns False if the spec is not found.

Parameters:

spec (Spec or str) – the specification to check

is_overridden_spec(spec)

Return True if this spec overrides a specification from the parent type, False otherwise.

Returns False if the spec is not found.

Parameters:

spec (Spec or str) – the specification to check

is_inherited_attribute(name)

Return True if the attribute was inherited from the parent type, False otherwise.

Raises a ValueError if the spec is not found.

Parameters:

name (str) – the name of the attribute to check

is_overridden_attribute(name)

Return True if the given attribute overrides the specification from the parent, False otherwise.

Raises a ValueError if the spec is not found.

Parameters:

name (str) – the name of the attribute to check

is_many()
classmethod get_data_type_spec(data_type_def)
classmethod get_namespace_spec()
property attributes

Tuple of attribute specifications for this specification

property linkable

True if object can be a link, False otherwise

classmethod id_key()

Get the key used to store data ID on an instance

Override this method to use a different name for ‘object_id’

classmethod type_key()

Get the key used to store data type on an instance

Override this method to use a different name for ‘data_type’. HDMF supports combining schema that uses ‘data_type’ and at most one different name for ‘data_type’.

classmethod inc_key()

Get the key used to define a data_type include.

Override this method to use a different keyword for ‘data_type_inc’. HDMF supports combining schema that uses ‘data_type_inc’ and at most one different name for ‘data_type_inc’.

classmethod def_key()

Get the key used to define a data_type definition.

Override this method to use a different keyword for ‘data_type_def’ HDMF supports combining schema that uses ‘data_type_def’ and at most one different name for ‘data_type_def’.

property data_type_inc

The data type this specification inherits

property data_type_def

The data type this specification defines

property data_type

The data type of this specification

property quantity

The number of times the object being specified should be present

add_attribute(name, doc, dtype, shape=None, dims=None, required=True, parent=None, value=None, default_value=None)

Add an attribute to this specification

Parameters:

  • name (str) – The name of this attribute

  • doc (str) – a description about what this specification represents

  • dtype (str or RefSpec) – The data type of this attribute

  • shape (list or tuple) – the shape of this dataset

  • dims (list or tuple) – the dimensions of this dataset

  • required (bool) – whether or not this attribute is required. ignored when “value” is specified

  • parent (BaseStorageSpec) – the parent of this spec

  • value (None) – a constant value for this attribute

  • default_value (None) – a default value for this attribute

set_attribute(spec)

Set an attribute on this specification

Parameters:

spec (AttributeSpec) – the specification for the attribute to add

get_attribute(name)

Get an attribute on this specification

Parameters:

name (str) – the name of the attribute to the Spec for

classmethod build_const_args(spec_dict)

Build constructor arguments for this Spec class from a dictionary

class hdmf.spec.spec.DtypeSpec(name, doc, dtype)

Bases: ConstructableDict

A class for specifying a component of a compound type

Parameters:

  • name (str) – the name of this column

  • doc (str) – a description about what this data type is

  • dtype (str or list or RefSpec) – the data type of this column

property doc

Documentation about this component

property name

The name of this component

property dtype

The data type of this component

static assertValidDtype(dtype)
static check_valid_dtype(dtype)
static is_ref(spec)
Parameters:

spec (str or dict) – the spec object to check

classmethod build_const_args(spec_dict)

Build constructor arguments for this Spec class from a dictionary

class hdmf.spec.spec.DatasetSpec(doc, dtype=None, name=None, default_name=None, shape=None, dims=None, attributes=[], linkable=True, quantity=1, default_value=None, data_type_def=None, data_type_inc=None)

Bases: BaseStorageSpec

Specification for datasets

To specify a table-like dataset i.e. a compound data type.

Parameters:

  • doc (str) – a description about what this specification represents

  • dtype (str or list or RefSpec) – The data type of this attribute. Use a list of DtypeSpecs to specify a compound data type.

  • name (str) – The name of this dataset

  • default_name (str) – The default name of this dataset

  • shape (list or tuple) – the shape of this dataset

  • dims (list or tuple) – the dimensions of this dataset

  • attributes (list) – the attributes on this group

  • linkable (bool) – whether or not this group can be linked

  • quantity (str or int) – the required number of allowed instance

  • default_value (None) – a default value for this dataset

  • data_type_def (str) – the data type this specification represents

  • data_type_inc (str or DatasetSpec) – the data type this specification extends

resolve_spec(inc_spec)
Parameters:

inc_spec (DatasetSpec) – the data type this specification represents

property dims

The dimensions of this Dataset

property dtype

The data type of the Dataset

property shape

The shape of the dataset

property default_value

The default value of the dataset or None if not specified

classmethod dtype_spec_cls()

The class to use when constructing DtypeSpec objects

Override this if extending to use a class other than DtypeSpec to build dataset specifications

classmethod build_const_args(spec_dict)

Build constructor arguments for this Spec class from a dictionary

class hdmf.spec.spec.LinkSpec(doc, target_type, quantity=1, name=None)

Bases: Spec

Parameters:

  • doc (str) – a description about what this link represents

  • target_type (str or BaseStorageSpec) – the target type GroupSpec or DatasetSpec

  • quantity (str or int) – the required number of allowed instance

  • name (str) – the name of this link

property target_type

The data type of target specification

property data_type_inc

The data type of target specification

is_many()
property quantity

The number of times the object being specified should be present

property required

Whether or not the this spec represents a required field

class hdmf.spec.spec.GroupSpec(doc, name=None, default_name=None, groups=[], datasets=[], attributes=[], links=[], linkable=True, quantity=1, data_type_def=None, data_type_inc=None)

Bases: BaseStorageSpec

Specification for groups

Parameters:

  • doc (str) – a description about what this specification represents

  • name (str) – the name of the Group that is written to the file. If this argument is omitted, users will be required to enter a name field when creating instances of this data type in the API. Another option is to specify default_name, in which case this name will be used as the name of the Group if no other name is provided.

  • default_name (str) – The default name of this group

  • groups (list) – the subgroups in this group

  • datasets (list) – the datasets in this group

  • attributes (list) – the attributes on this group

  • links (list) – the links in this group

  • linkable (bool) – whether or not this group can be linked

  • quantity (str or int) – the allowable number of instance of this group in a certain location. See table of options here. Note that if youspecify name, quantity cannot be '*', '+', or an integer greater that 1, because you cannot have more than one group of the same name in the same parent group.

  • data_type_def (str) – the data type this specification represents

  • data_type_inc (str or GroupSpec) – the data type this specification data_type_inc

resolve_spec(inc_spec)
Parameters:

inc_spec (GroupSpec) – the data type this specification represents

is_inherited_dataset(name)

Return true if a dataset with the given name was inherited

Parameters:

name (str) – the name of the dataset

is_overridden_dataset(name)

Return true if a dataset with the given name overrides a specification from the parent type

Parameters:

name (str) – the name of the dataset

is_inherited_group(name)

Return true if a group with the given name was inherited

Parameters:

name (str) – the name of the group

is_overridden_group(name)

Return true if a group with the given name overrides a specification from the parent type

Parameters:

name (str) – the name of the group

Return true if a link with the given name was inherited

Parameters:

name (str) – the name of the link

Return true if a link with the given name overrides a specification from the parent type

Parameters:

name (str) – the name of the link

is_inherited_spec(spec)

Returns ‘True’ if specification was inherited from a parent type

Parameters:

spec (Spec or str) – the specification to check

is_overridden_spec(spec)

Returns ‘True’ if specification overrides a specification from the parent type

Parameters:

spec (Spec or str) – the specification to check

is_inherited_type(spec)

Returns True if spec represents a data type that was inherited

Parameters:

spec (BaseStorageSpec or str) – the specification to check

is_overridden_type(spec)

Returns True if spec represents a data type that overrides a specification from a parent type

Parameters:

spec (BaseStorageSpec or str) – the specification to check

is_inherited_target_type(spec)

Returns True if spec represents a target type that was inherited

Parameters:

spec (LinkSpec or str) – the specification to check

is_overridden_target_type(spec)

Returns True if spec represents a target type that overrides a specification from a parent type

Parameters:

spec (LinkSpec or str) – the specification to check

get_data_type(data_type)

Get a specification by “data_type”

NOTE: If there is only one spec for a given data type, then it is returned. If there are multiple specs for a given data type and they are all named, then they are returned in a list. If there are multiple specs for a given data type and only one is unnamed, then the unnamed spec is returned. The other named specs can be returned using get_group or get_dataset.

NOTE: this method looks for an exact match of the data type and does not consider the type hierarchy.

Parameters:

data_type (str) – the data_type to retrieve

get_target_type(target_type)

Get a specification by “target_type”

NOTE: If there is only one spec for a given target type, then it is returned. If there are multiple specs for a given target type and they are all named, then they are returned in a list. If there are multiple specs for a given target type and only one is unnamed, then the unnamed spec is returned. The other named specs can be returned using get_link.

NOTE: this method looks for an exact match of the target type and does not consider the type hierarchy.

Parameters:

target_type (str) – the target_type to retrieve

property groups

The groups specified in this GroupSpec

property datasets

The datasets specified in this GroupSpec

The links specified in this GroupSpec

add_group(doc, name=None, default_name=None, groups=[], datasets=[], attributes=[], links=[], linkable=True, quantity=1, data_type_def=None, data_type_inc=None)

Add a new specification for a subgroup to this group specification

Parameters:

  • doc (str) – a description about what this specification represents

  • name (str) – the name of the Group that is written to the file. If this argument is omitted, users will be required to enter a name field when creating instances of this data type in the API. Another option is to specify default_name, in which case this name will be used as the name of the Group if no other name is provided.

  • default_name (str) – The default name of this group

  • groups (list) – the subgroups in this group

  • datasets (list) – the datasets in this group

  • attributes (list) – the attributes on this group

  • links (list) – the links in this group

  • linkable (bool) – whether or not this group can be linked

  • quantity (str or int) –

    the allowable number of instance of this group in a certain location. See table of options here. Note that if youspecify name, quantity cannot be '*', '+', or an integer greater that 1, because you cannot have more than one group of the same name in the same parent group.

  • data_type_def (str) – the data type this specification represents

  • data_type_inc (str or GroupSpec) – the data type this specification data_type_inc

set_group(spec)

Add the given specification for a subgroup to this group specification

Parameters:

spec (GroupSpec) – the specification for the subgroup

get_group(name)

Get a specification for a subgroup to this group specification

Parameters:

name (str) – the name of the group to the Spec for

add_dataset(doc, dtype=None, name=None, default_name=None, shape=None, dims=None, attributes=[], linkable=True, quantity=1, default_value=None, data_type_def=None, data_type_inc=None)

Add a new specification for a dataset to this group specification

Parameters:

  • doc (str) – a description about what this specification represents

  • dtype (str or list or RefSpec) – The data type of this attribute. Use a list of DtypeSpecs to specify a compound data type.

  • name (str) – The name of this dataset

  • default_name (str) – The default name of this dataset

  • shape (list or tuple) – the shape of this dataset

  • dims (list or tuple) – the dimensions of this dataset

  • attributes (list) – the attributes on this group

  • linkable (bool) – whether or not this group can be linked

  • quantity (str or int) – the required number of allowed instance

  • default_value (None) – a default value for this dataset

  • data_type_def (str) – the data type this specification represents

  • data_type_inc (str or DatasetSpec) – the data type this specification extends

set_dataset(spec)

Add the given specification for a dataset to this group specification

Parameters:

spec (DatasetSpec) – the specification for the dataset

get_dataset(name)

Get a specification for a dataset to this group specification

Parameters:

name (str) – the name of the dataset to the Spec for

Add a new specification for a link to this group specification

Parameters:

  • doc (str) – a description about what this link represents

  • target_type (str or BaseStorageSpec) – the target type GroupSpec or DatasetSpec

  • quantity (str or int) – the required number of allowed instance

  • name (str) – the name of this link

Add a given specification for a link to this group specification

Parameters:

spec (LinkSpec) – the specification for the object to link to

Get a specification for a link to this group specification

Parameters:

name (str) – the name of the link to the Spec for

classmethod dataset_spec_cls()

The class to use when constructing DatasetSpec objects

Override this if extending to use a class other than DatasetSpec to build dataset specifications

The class to use when constructing LinkSpec objects

Override this if extending to use a class other than LinkSpec to build link specifications

classmethod build_const_args(spec_dict)

Build constructor arguments for this Spec class from a dictionary