fioh5: h5py-like API to FIO file

This module provides a h5py-like API to access FioFile data.

API description

Fiofile data structure exposed by this API:

/
    n.1/
        title = "…"
        start_time = "…"
        instrument/
            fiofile/
                comments = "…"
                parameter = "…"
            comment = "…"
            parameter/
                parameter_name = value

        measurement/
            colname0 = …
            colname1 = …
            …

The top level scan number n.1 is determined from the filename as in prefix_n.fio. (e.g. eh1_sixc_00045.fio would give 45.1) If no number is available, will use the filename instead.

comments and parameter in group fiofile are the raw headers as they appear in the original file, as a string of lines separated by newline (\n) characters. comment are the remaining comments, which were not parsed.

The title is the content of the first comment header line (e.g "ascan  ss1vo -4.55687 -0.556875  40 0.2"). The start_time is parsed from the second comment line.

Datasets are stored in the data format specified in the fio file header.

Scan data (e.g. /1.1/measurement/colname0) is accessed by column, the dataset name colname0 being the column label as defined in the Col header line.

If a / character is present in a column label or in a motor name in the original FIO file, it will be substituted with a % character in the corresponding dataset name.

MCA data is not yet supported.

This reader requires a fio file as defined in src/sardana/macroserver/recorders/storage.py of the Sardana project (https://github.com/sardana-org/sardana).

Accessing data

Data and groups are accessed in h5py fashion:

from silx.io.fioh5 import FioH5

# Open a FioFile
fiofh5 = FioH5("test_00056.fio")

# using FioH5 as a regular group to access scans
scan1group = fiofh5["56.1"]
instrument_group = scan1group["instrument"]

# alternative: full path access
measurement_group = fiofh5["/56.1/measurement"]

# accessing a scan data column by name as a 1D numpy array
data_array = measurement_group["Pslit HGap"]

FioH5 files and groups provide a keys() method:

>>> fiofh5.keys()
['96.1', '97.1', '98.1']
>>> fiofh5['96.1'].keys()
['title', 'start_time', 'instrument', 'measurement']

They can also be treated as iterators:

from silx.io import is_dataset

for scan_group in FioH5("test_00056.fio"):
    dataset_names = [item.name in scan_group["measurement"] if
                     is_dataset(item)]
    print("Found data columns in scan " + scan_group.name)
    print(", ".join(dataset_names))

You can test for existence of data or groups:

>>> "/1.1/measurement/Pslit HGap" in fiofh5
True
>>> "positioners" in fiofh5["/2.1/instrument"]
True
>>> "spam" in fiofh5["1.1"]
False

Classes

class FioH5(filename, order=1)[source]

Bases: silx.io.commonh5.File

This class reads a FIO file and exposes it as a h5py.File.

It inherits silx.io.commonh5.Group (via commonh5.File), which implements most of its API.

__contains__(name)

Returns true if name is an existing child of this group.

Return type:bool
__enter__()
__exit__(exc_type, exc_val, exc_tb)
__getitem__(name)

Return a child from his name.

Parameters:name (str) – name of a member or a path throug members using ‘/’ separator. A ‘/’ as a prefix access to the root item of the tree.
Return type:Node
__iter__()

Iterate over member names

__len__()

Returns the number of children contained in this group.

Return type:int
attrs

Returns HDF5 attributes of this node.

Return type:dict
basename

Returns the HDF5 basename of this node.

close()

Close the object, and free up associated resources.

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

Create and return a sub dataset.

Parameters:
  • name (str) – Name of the dataset.
  • shape – Dataset shape. Use “()” for scalar datasets. Required if “data” isn’t provided.
  • dtype – Numpy dtype or string. If omitted, dtype(‘f’) will be used. Required if “data” isn’t provided; otherwise, overrides data array’s dtype.
  • data (numpy.ndarray) – Provide data to initialize the dataset. If used, you can omit shape and dtype arguments.
  • kwds – Extra arguments. Nothing yet supported.
create_group(name)

Create and return a new subgroup.

Name may be absolute or relative. Fails if the target name already exists.

Parameters:name (str) – Name of the new group
file

Returns the file node of this node.

Return type:Node
filename
get(name, default=None, getclass=False, getlink=False)

Retrieve an item or other information.

If getlink only is true, the returned value is always h5py.HardLink, because this implementation do not use links. Like the original implementation.

Parameters:
  • name (str) – name of the item
  • default (object) – default value returned if the name is not found
  • getclass (bool) – if true, the returned object is the class of the object found
  • getlink (bool) – if true, links object are returned instead of the target
Returns:

An object, else None

Return type:

object

h5_class

Returns the h5py.File class

h5py_class

Returns the h5py classes which is mimicked by this class. It can be one of h5py.File, h5py.Group or h5py.Dataset

This should not be used anymore. Prefer using h5_class

Return type:Class
items()

Returns items iterator containing name-node mapping.

Return type:iterator
keys()

Returns an iterator over the children’s names in a group.

mode
name

Returns the HDF5 name of this node.

parent

Returns the parent of the node.

Return type:Node
values()

Returns an iterator over the children nodes (groups and datasets) in a group.

New in version 0.6.

visit(func, visit_links=False)

Recursively visit all names in this group and subgroups. See the documentation for h5py.Group.visit for more help.

Parameters:func (callable) – Callable (function, method or callable object)
visititems(func, visit_links=False)

Recursively visit names and objects in this group. See the documentation for h5py.Group.visititems for more help.

Parameters:
  • func (callable) – Callable (function, method or callable object)
  • visit_links (bool) – If False, ignore links. If True, call func(name) for links and recurse into target groups.
class FioFile(filepath)[source]

This class opens a FIO file and reads the data.

class Group(name, parent=None, attrs=None)[source]

Bases: silx.io.commonh5.Node

This class mimics a h5py.Group.

get(name, default=None, getclass=False, getlink=False)[source]

Retrieve an item or other information.

If getlink only is true, the returned value is always h5py.HardLink, because this implementation do not use links. Like the original implementation.

Parameters:
  • name (str) – name of the item
  • default (object) – default value returned if the name is not found
  • getclass (bool) – if true, the returned object is the class of the object found
  • getlink (bool) – if true, links object are returned instead of the target
Returns:

An object, else None

Return type:

object

__getitem__(name)[source]

Return a child from his name.

Parameters:name (str) – name of a member or a path throug members using ‘/’ separator. A ‘/’ as a prefix access to the root item of the tree.
Return type:Node
__contains__(name)[source]

Returns true if name is an existing child of this group.

Return type:bool
__len__()[source]

Returns the number of children contained in this group.

Return type:int
__iter__()[source]

Iterate over member names

keys()[source]

Returns an iterator over the children’s names in a group.

values()[source]

Returns an iterator over the children nodes (groups and datasets) in a group.

New in version 0.6.

items()[source]

Returns items iterator containing name-node mapping.

Return type:iterator
visit(func, visit_links=False)[source]

Recursively visit all names in this group and subgroups. See the documentation for h5py.Group.visit for more help.

Parameters:func (callable) – Callable (function, method or callable object)
visititems(func, visit_links=False)[source]

Recursively visit names and objects in this group. See the documentation for h5py.Group.visititems for more help.

Parameters:
  • func (callable) – Callable (function, method or callable object)
  • visit_links (bool) – If False, ignore links. If True, call func(name) for links and recurse into target groups.
attrs

Returns HDF5 attributes of this node.

Return type:dict
basename

Returns the HDF5 basename of this node.

file

Returns the file node of this node.

Return type:Node
h5py_class

Returns the h5py classes which is mimicked by this class. It can be one of h5py.File, h5py.Group or h5py.Dataset

This should not be used anymore. Prefer using h5_class

Return type:Class
name

Returns the HDF5 name of this node.

parent

Returns the parent of the node.

Return type:Node
is_fiofile(filename)[source]

Test if a file is a FIO file, by checking if three consecutive lines start with !. Tests up to ABORTLINENO lines at the start of the file.

Parameters:filename (str) – File path
Returns:True if file is a FIO file, False if it is not a FIO file
Return type:bool