Skip to main content
`Ctrl`+`K`

# `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 (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

- `FioH5`

- `FioFile`

class FioH5(filename, order=1)

  Bases: `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

  property attrs

    Returns HDF5 attributes of this node.

    Return type:

      dict

  property 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

  property file

    Returns the file node of this node.

    Return type:

      Node

  property 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

  property h5_class

    Returns the `h5py.File` class

  property 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.

  property mode
  property name

    Returns the HDF5 name of this node.

  property parent

    Returns the parent of the node.

    Return type:

      Node

  values()

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

    Added 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)

  This class opens a FIO file and reads the data.

is_fiofile(filename)

  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