HDF5 Groups

Groups are the container mechanism by which HDF5 files are organized. From a Python perspective, they operate somewhat like dictionaries. In this case the “keys” are the names of group members, and the “values” are the members themselves (Group and Dataset) objects.

Group objects also contain most of the machinery which makes HDF5 useful. The File object does double duty as the HDF5 root group, and serves as your entry point into the file:

>>> f = h5py.File('foo.hdf5','w')
>>> f.name
u'/'
>>> f.keys()
[]

Names of all objects in the file are all text strings (unicode on Py2, str on Py3). These will be encoded with the HDF5-approved UTF-8 encoding before being passed to the HDF5 C library. Objects may also be retrieved using byte strings, which will be passed on to HDF5 as-is.

Creating groups

New groups are easy to create:

>>> grp = f.create_group("bar")
>>> grp.name
'/bar'
>>> subgrp = grp.create_group("baz")
>>> subgrp.name
'/bar/baz'

Multiple intermediate groups can also be created implicitly:

>>> grp2 = f.create_group("/some/long/path")
>>> grp2.name
'/some/long/path'
>>> grp3 = f['/some/long']
>>> grp3.name
'/some/long'

Reference

class Group(identifier)

Generally Group objects are created by opening objects in the file, or by the method Group.create_group(). Call the constructor with a GroupID instance to create a new Group bound to an existing low-level identifier.

__iter__()

Iterate over the names of objects directly attached to the group. Use Group.visit() or Group.visititems() for recursive access to group members.

__contains__(name)

Dict-like containership testing. name may be a relative or absolute path.

__getitem__(name)

Retrieve an object. name may be a relative or absolute path, or an object or region reference. See Dict interface and links.

__setitem__(name, value)

Create a new link, or automatically create a dataset. See Dict interface and links.

keys()

Get the names of directly attached group members. On Py2, this is a list. On Py3, it’s a set-like object. Use Group.visit() or Group.visititems() for recursive access to group members.

values()

Get the objects contained in the group (Group and Dataset instances). Broken soft or external links show up as None. On Py2, this is a list. On Py3, it’s a collection or bag-like object.

items()

Get (name, value) pairs for object directly attached to this group. Values for broken soft or external links show up as None. On Py2, this is a list. On Py3, it’s a set-like object.

iterkeys()

(Py2 only) Get an iterator over key names. Exactly equivalent to iter(group). Use Group.visit() or Group.visititems() for recursive access to group members.

itervalues()

(Py2 only) Get an iterator over objects attached to the group. Broken soft and external links will show up as None.

iteritems()

(Py2 only) Get an iterator over (name, value) pairs for objects directly attached to the group. Broken soft and external link values show up as None.

get(name, default=None, getclass=False, getlink=False)

Retrieve an item, or information about an item. name and default work like the standard Python dict.get.

Parameters:
  • name – Name of the object to retrieve. May be a relative or absolute path.
  • default – If the object isn’t found, return this instead.
  • getclass – If True, return the class of object instead; Group or Dataset.
  • getlink – If true, return the type of link via a HardLink, SoftLink or ExternalLink instance. If getclass is also True, returns the corresponding Link class without instantiating it.
visit(callable)

Recursively visit all objects in this group and subgroups. You supply a callable with the signature:

callable(name) -> None or return value

name will be the name of the object relative to the current group. Return None to continue visiting until all objects are exhausted. Returning anything else will immediately stop visiting and return that value from visit:

>>> def find_foo(name):
...     """ Find first object with 'foo' anywhere in the name """
...     if 'foo' in name:
...         return name
>>> group.visit(find_foo)
u'some/subgroup/foo'
visititems(callable)

Recursively visit all objects in this group and subgroups. Like Group.visit(), except your callable should have the signature:

callable(name, object) -> None or return value

In this case object will be a Group or Dataset instance.

move(source, dest)

Move an object or link in the file. If source is a hard link, this effectively renames the object. If a soft or external link, the link itself is moved.

Parameters:
  • source (String) – Name of object or link to move.
  • dest (String) – New location for object or link.
copy(source, dest, name=None, shallow=False, expand_soft=False, expand_external=False, expand_refs=False, without_attrs=False)

Copy an object or group. The source and destination need not be in the same file. If the source is a Group object, by default all objects within that group will be copied recursively.

Parameters:
  • source – What to copy. May be a path in the file or a Group/Dataset object.
  • dest – Where to copy it. May be a path or Group object.
  • name – If the destination is a Group object, use this for the name of the copied object (default is basename).
  • shallow – Only copy immediate members of a group.
  • expand_soft – Expand soft links into new objects.
  • expand_external – Expand external links into new objects.
  • expand_refs – Copy objects which are pointed to by references.
  • without_attrs – Copy object(s) without copying HDF5 attributes.
create_group(name)

Create and return a new group in the file.

Parameters:name (String or None) – Name of group to create. May be an absolute or relative path. Provide None to create an anonymous group, to be linked into the file later.
Returns:The new Group object.
require_group(name)

Open a group in the file, creating it if it doesn’t exist. TypeError is raised if a conflicting object already exists. Parameters as in Group.create_group().

create_dataset(name, shape=None, dtype=None, data=None, **kwds)

Create a new dataset. Options are explained in Creating datasets.

Parameters:
  • name – Name of dataset to create. May be an absolute or relative path. Provide None to create an anonymous dataset, to be linked into the file later.
  • shape – Shape of new dataset (Tuple).
  • dtype – Data type for new dataset
  • data – Initialize dataset to this (NumPy array).
  • chunks – Chunk shape, or True to enable auto-chunking.
  • maxshape – Dataset will be resizable up to this shape (Tuple). Automatically enables chunking. Use None for the axes you want to be unlimited.
  • compression – Compression strategy. See Filter pipeline.
  • compression_opts – Parameters for compression filter.
  • scaleoffset – See Scale-Offset filter.
  • shuffle – Enable shuffle filter (T/F). See Shuffle filter.
  • fletcher32 – Enable Fletcher32 checksum (T/F). See Fletcher32 filter.
  • fillvalue – This value will be used when reading uninitialized parts of the dataset.
  • track_times – Enable dataset creation timestamps (T/F).
require_dataset(name, shape=None, dtype=None, exact=None, **kwds)

Open a dataset, creating it if it doesn’t exist.

If keyword “exact” is False (default), an existing dataset must have the same shape and a conversion-compatible dtype to be returned. If True, the shape and dtype must match exactly.

Other dataset keywords (see create_dataset) may be provided, but are only used if a new dataset is to be created.

Raises TypeError if an incompatible object already exists, or if the shape or dtype don’t match according to the above rules.

Parameters:exact – Require shape and type to match exactly (T/F)
attrs

HDF5 Attributes for this group.

id

The groups’s low-level identifer; an instance of GroupID.

ref

An HDF5 object reference pointing to this group. See Using object references.

regionref

A proxy object allowing you to interrogate region references. See Using region references.

name

String giving the full path to this group.

file

File instance in which this group resides.

parent

Group instance containing this group.