HDF5 tables

Note

The Hierarchical Data Format (HDF) is a format that can be used to store, transmit, and manipulate datasets (n-dimensional arrays or tables). Datasets can be collected into groups, which can be collected into larger groups. Datasets and groups can contain meta-data, in the form of attributes.

HDF5 tables are supported thanks to the h5py module. Reading HDF5 tables is straightforward:

>>> t = atpy.Table('table.hdf5')

If more than one table is present in the file, ATpy will give a list of available tables, identified by a path. The specific table to read can then be specified with the table= argument:

>>> t = atpy.Table('table.hdf5', table='Measurements')

In the case where a table is inside a group, or a hierarchy of groups, the table name may be a full path inside the file:

>>> t = atpy.Table('table.hdf5', table='Group1/Measurements')

To read in all tables in an HDF5 file, use the TableSet class:

>>> t = atpy.TableSet('table.hdf5')

When writing out an HDF5 table, the default is to write the uncompressed, but it is possible to turn on compression using the compression argument:

>>> t.write('table.hdf5', compression=True)

To write the table to a specific group within the file, use the group argument:

>>> t.write('table.hdf5', group='Group4')

Finally, it is possible to append tables to existing files, using the append argument. For example, the following two commands write out two tables to the same existing file:

>>> t1.write('existing_table.hdf', append=True)
>>> t2.write('existing_table.hdf', append=True)

In the event that ATpy does not recognize an HDF5 table (for example if the file extension is obscure), the type can be explicitly given:

>>> t = atpy.Table('table', type='hdf5')

Note

As for all file formats, the verbose argument can be specified to control whether warning messages are shown when reading (the default is verbose=True), and the overwrite argument can be used when writing to overwrite a file (the default is overwrite=False).

Full API for advanced users

Note

The following functions should not be called directly - the arguments should be passed to Table()/Table.read(), Table.write(), TableSet()/TableSet.read(), and TableSet.write() respectively.

atpy.hdf5table.read(self, filename, table=None, verbose=True)

Read a table from an HDF5 file

Required Arguments:

filename: [ string ]

The HDF5 file to read the table from

OR

file or group handle: [ h5py.highlevel.File | h5py.highlevel.Group ]

The HDF5 file handle or group handle to read the table from

Optional Keyword Arguments:

table: [ string ]

The name of the table to read from the HDF5 file (this is only required if there are more than one table in the file)

atpy.hdf5table.write(self, filename, compression=False, group='', append=False, overwrite=False, ignore_groups=False)

Write the table to an HDF5 file

Required Arguments:

filename: [ string ]

The HDF5 file to write the table to

OR

file or group handle: [ h5py.highlevel.File | h5py.highlevel.Group ]

The HDF5 file handle or group handle to write the table to

Optional Keyword Arguments:

compression: [ True | False ]

Whether to compress the table inside the HDF5 file

group: [ string ]

The group to write the table to inside the HDF5 file

append: [ True | False ]

Whether to append the table to an existing HDF5 file

overwrite: [ True | False ]

Whether to overwrite any existing file without warning

ignore_groups: [ True | False ]

With this option set to True, groups are removed from table names. With this option set to False, tables are placed in groups that are present in the table name, and the groups are created if necessary.

atpy.hdf5table.read_set(self, filename, pedantic=False, verbose=True)

Read all tables from an HDF5 file

Required Arguments:

filename: [ string ]

The HDF5 file to read the tables from

atpy.hdf5table.write_set(self, filename, compression=False, group='', append=False, overwrite=False, ignore_groups=False, **kwargs)

Write the tables to an HDF5 file

Required Arguments:

filename: [ string ]

The HDF5 file to write the tables to

OR

file or group handle: [ h5py.highlevel.File | h5py.highlevel.Group ]

The HDF5 file handle or group handle to write the tables to

Optional Keyword Arguments:

compression: [ True | False ]

Whether to compress the tables inside the HDF5 file

group: [ string ]

The group to write the table to inside the HDF5 file

append: [ True | False ]

Whether to append the tables to an existing HDF5 file

overwrite: [ True | False ]

Whether to overwrite any existing file without warning

ignore_groups: [ True | False ]

With this option set to True, groups are removed from table names. With this option set to False, tables are placed in groups that are present in the table name, and the groups are created if necessary.