Metadata

All Group and Dataset items contain Metadata. A Metadata item is a dict that can be made read only and it allows for accessing the keys of the dict as class attributes (see Accessing Keys as Class Attributes for more information).

For example, suppose that a file is read that has the following Metadata

>>> root.metadata
<Metadata '/' {'voltage': 1.2, 'voltage_unit': 'V'}>

A value can be accessed by key

>>> root.metadata["voltage"]
1.2

or as a class attribute

>>> root.metadata.voltage
1.2

Read/Write mode

When a file is read, the returned object is in read-only mode so you cannot modify the metadata

>>> root.metadata.voltage = 7.64
Traceback (most recent call last):
    ...
ValueError: Cannot modify <Metadata '/' {'voltage': 1.2, 'voltage_unit': 'V'}>. It is accessed in read-only mode.

However, you can allow metadata to be modified by setting the read_only property to be False

>>> root.metadata.read_only = False

and then you can modify the values

>>> root.metadata.voltage = 7.64
>>> root.add_metadata(current=10.3, current_unit="mA")
>>> root.metadata
<Metadata '/' {'voltage': 7.64, 'voltage_unit': 'V', 'current': 10.3, 'current_unit': 'mA'}>

Lists, tuples and arrays

When the metadata value is a list, tuple or array, it will automatically be converted to a numpy ndarray. The dtype for a list, tuple will be object

>>> root.metadata.temperatures = [20.1, 20.4, 19.8, 19.9]
>>> root.metadata.temperatures
array([20.1, 20.4, 19.8, 19.9], dtype=object)

>>> root.metadata.humidities = (45.6, 46.1, 46.3, 44.7)
>>> root.metadata.humidities
array([45.6, 46.1, 46.3, 44.7], dtype=object)

and the data type used by the array will be preserved

>>> root.metadata.unsigned_integers = array.array("I", [1, 2, 3, 4])
>>> root.metadata.unsigned_integers
array([1, 2, 3, 4], dtype=uint32)

Setting the value to a numpy ndarray remains unchanged

>>> root.metadata.eye = np.eye(2)
>>> root.metadata.eye
array([[1., 0.],
       [0., 1.]])

Dictionaries

When the metadata value is a dict it will be converted to a Metadata instance

>>> root.metadata.nested = {"one": 1, "two": 2, "three": 3}
>>> root.metadata.nested
<Metadata '/' {'one': 1, 'two': 2, 'three': 3}>
>>> root.metadata.nested.two
2