HDF5 File Utilities (ryhdf5)

Overview

This module provides functions for file input/output. These are all wrapper functions, based on existing functions in other Python classes. Functions are provided to save a two-dimensional array to a text file, load selected columns of data from a text file, load a column header line, compact strings to include only legal filename characters, and a function from the Python Cookbook to recursively match filename patterns.

See the __main__ function for examples of use.

This package was partly developed to provide additional material in support of students and readers of the book Electro-Optical System Analysis and Design: A Radiometry Perspective, Cornelius J. Willers, ISBN 9780819495693, SPIE Monograph Volume PM236, SPIE Press, 2013. http://spie.org/x648.html?product_id=2021423&origin_id=x646

Module functions

open_HDF(filename, mode='r')

Open and return an HDF5 file with the given filename.

See https://github.com/NelisW/pyradi/blob/master/pyradi/hdf5-as-data-format.md for more information on using HDF5 as a data structure.

Default open mode is read, cam be overridden by any of these: ‘r’, ‘r+’, ‘w’, ‘w-‘/’x’, ‘a’ https://h5py.readthedocs.io/en/stable/quick.html https://h5py.readthedocs.io/en/stable/high/file.html#opening-creating-files

Parameters:

filename (|) – name of the file to be opened

Returns:

HDF5 file.

Raises:

| No exception is raised. –

Author: CJ Willers

erase_create_HDF(filename)

Create and return a new HDS5 file with the given filename, erase the file if existing.

See https://github.com/NelisW/pyradi/blob/master/pyradi/hdf5-as-data-format.md for more information on using HDF5 as a data structure.

open for writing, truncate if exists https://h5py.readthedocs.io/en/stable/high/file.html#opening-creating-files

Parameters:

filename (|) – name of the file to be created

Returns:

HDF5 file.

Raises:

| No exception is raised. –

Author: CJ Willers

get_HDF_DS(hdf5File, path)

Check to see if a path is present in an HDF5 file and then return the dataset.

Parameters:

• hdf5File (|) – HDF5 file to be read

• path (|) – path to the dataset

Returns:

HDF5 contents along the path, or None.

Raises:

| No exception is raised. –

Author: CJ Willers

print_HDF5_text(vartext)

Prints text in visiting algorithm in HDF5 file.

See https://github.com/NelisW/pyradi/blob/master/pyradi/hdf5-as-data-format.md for more information on using HDF5 as a data structure.

Parameters:

vartext (|) – string to be printed

Returns:

None.

Raises:

| No exception is raised. –

Author: CJ Willers

print_HDF5_dataset_value(var, obj)

Prints a data set in visiting algorithm in HDF5 file.

See https://github.com/NelisW/pyradi/blob/master/pyradi/hdf5-as-data-format.md for more information on using HDF5 as a data structure.

Parameters:

• var (|) – path to a dataset

• obj (|) – dataset to be printed

Returns:

None.

Raises:

| No exception is raised. –

Author: CJ Willers

get_HDF_branches(hdf5File)

Print list of all the branches in the file.

See https://github.com/NelisW/pyradi/blob/master/pyradi/hdf5-as-data-format.md for more information on using HDF5 as a data structure.

Note: this function passes itself as the h5py visitor callback. h5py then calls get_HDF_branches(name_string) for each item in the hierarchy. Since a string has no .visit() method this raises AttributeError for any non-empty file. The behaviour is preserved unchanged (calling on an empty file returns None safely).

Parameters:

hdf5File (|) – the open HDF5 file to inspect

Returns:

None (h5py visit() always returns None when the callback never

returns a non-None value).

Raises:

| AttributeError – for any non-empty HDF5 file (see note above).

Author: CJ Willers

plotHDF5Bitmaps(hfd5f, prefix, pformat='png', lstimgs=None, debug=False)

Plot arrays in the HFD5 as scaled bitmap images.

See https://github.com/NelisW/pyradi/blob/master/pyradi/hdf5-as-data-format.md for more information on using HDF5 as a data structure.

Retain zero in the array as black in the image, only scale the max value to 255

Parameters:

• hfd5f (|) – the file to be opened

• prefix (|) – prefix to be prepended to filename

• pformat (|) – type of file to be created png/jpeg

• lstimgs (|) – list of paths to image in the HFD5 file

Returns:

Nothing.

Raises:

| No exception is raised. –

Author: CJ Willers

plotHDF5Images(hfd5f, prefix, colormap=None, cbarshow=True, lstimgs=None, logscale=False, debug=False)

Plot images contained in hfd5f with colour map to show magnitude.

See https://github.com/NelisW/pyradi/blob/master/pyradi/hdf5-as-data-format.md for more information on using HDF5 as a data structure.

https://scipy-cookbook.readthedocs.io/items/Matplotlib_Show_colormaps.html

Parameters:

• hfd5f (|) – the file to be opened

• prefix (|) – prefix to be prepended to filename

• colormap (|) – colour map to be used in plot

• cbarshow (|) – indicate if colour bar must be shown

• lstimgs (|) – list of paths to image in the HFD5 file

• logscale (|) – True if display must be on log scale

Returns:

Nothing.

Raises:

| No exception is raised. –

Author: CJ Willers

plotHDF5Histograms(hfd5f, prefix, format='png', lstimgs=None, bins=50)

Plot histograms of images contained in hfd5f

See https://github.com/NelisW/pyradi/blob/master/pyradi/hdf5-as-data-format.md for more information on using HDF5 as a data structure.

Retain zero in the array as black in the image, only scale the max value to 255

Parameters:

• hfd5f (|) – the file to be opened

• prefix (|) – prefix to be prepended to filename

• format (|) – type of file to be created png/jpeg

• lstimgs (|) – list of paths to image in the HFD5 file

• bins (|) – Number of bins to be used in histogram

Returns:

Nothing.

Raises:

| No exception is raised. –

Author: CJ Willers