nxdata: NXdata group parsing

This module provides a collection of functions to work with h5py-like groups following the NeXus NXdata specification.

See http://download.nexusformat.org/sphinx/classes/base_classes/NXdata.html

silx.io.nxdata.get_attr_as_string(item, attr_name, default=None)

Return item.attrs[attr_name]. If it is a byte-string or an array of byte-strings, return it as a default python string.

For Python 3, this involves a coercion from bytes into unicode. For Python 2, there is nothing special to do, as strings are bytes.

Parameters:

• item – Group or dataset
• attr_name – Attribute name

Returns:

item.attrs[attr_name]

silx.io.nxdata.is_valid_nxdata(group)

Check if a h5py group is a valid NX_data group.

If the group does not have attribute @NX_class=NXdata, this function simply returns False.

Else, warning messages are logged to troubleshoot malformed NXdata groups prior to returning False.

Parameters:group – h5py-like group Returns:True if this NXdata group is valid. Raise:TypeError if group is not a h5py group, a spech5 group, or a fabioh5 group

class silx.io.nxdata.NXdata(group)

Parameters:group – h5py-like group following the NeXus NXdata specification.

group = None

h5py-like group object compliant with NeXus NXdata specification.

signal = None

Signal dataset in this NXdata group.

axes_names = None

List of axes names in a NXdata group.

This attribute is similar to axes_dataset_names except that if an axis dataset has a “@long_name” attribute, it will be used instead of the dataset name.

interpretation

@interpretation attribute associated with the signal dataset of the NXdata group. None if no interpretation attribute is present.

The interpretation attribute provides information about the last dimensions of the signal. The allowed values are:

• “scalar”: 0-D data to be plotted
• “spectrum”: 1-D data to be plotted
• “image”: 2-D data to be plotted
• “vertex”: 3-D data to be plotted

For example, a 3-D signal with interpretation “spectrum” should be considered to be a 2-D array of 1-D data. A 3-D signal with interpretation “image” should be interpreted as a 1-D array (a list) of 2-D images. An n-D array with interpretation “image” should be interpreted as an (n-2)-D array of images.

A warning message is logged if the returned interpretation is not one of the allowed values, but no error is raised and the unknown interpretation is returned anyway.

axes

List of the axes datasets.

The list typically has as many elements as there are dimensions in the signal dataset, the exception being scatter plots which typically use a 1D signal and several 1D axes of the same size.

If an axis dataset applies to several dimensions of the signal, it will be repeated in the list.

If a dimension of the signal has no dimension scale (i.e. there is a ”.” in that position in the @axes array), None is inserted in the output list in its position.

Note

In theory, the @axes attribute defines as many entries as there are dimensions in the signal. In such a case, there is no ambiguity. If this is not the case, this implementation relies on the existence of an @interpretation (spectrum or image) attribute in the signal dataset.

Note

If an axis dataset defines attributes @first_good or @last_good, the output will be a numpy array resulting from slicing that axis to keep only the good index range: axis[first_good:last_good + 1]

Return type:list[Dataset or 1D array or None]

axes_dataset_names

If an axis dataset applies to several dimensions of the signal, its name will be repeated in the list.

If a dimension of the signal has no dimension scale (i.e. there is a ”.” in that position in the @axes array), None is inserted in the output list in its position.

get_axis_errors(axis_name)

Return errors (uncertainties) associated with an axis.

If the axis has attributes @first_good or @last_good, the output is trimmed accordingly (a numpy array will be returned rather than a dataset).

Parameters:axis_name (str) – Name of axis dataset. This dataset must exist. Returns:Dataset with axis errors, or None Raise:KeyError if this group does not contain a dataset named axis_name

errors

Return errors (uncertainties) associated with the signal values.

Returns:Dataset with errors, or None

is_scatter

True if the signal is 1D and all the axes have the same size as the signal.

is_x_y_value_scatter

True if this is a scatter with a signal and two axes.

is_unsupported_scatter

True if this is a scatter with a signal and more than 2 axes.