erlab.io.nexusutils

Utilities for reading NeXus files into xarray objects.

This module provides functions that can be used to extract coordinates and data from NeXus files and convert them into xarray DataArrays conveniently. All functions in this module require the nexusformat package to be installed.

Functions

get_coord_dict(group)

Generate a dictionary of coordinates from a NeXus group.

get_entry(filename[, entry])

Get an NXentry object from a NeXus file.

get_non_primary_coords(group)

Get all non-primary coordinates in a group.

get_primary_coord_dict(fields)

Generate a dictionary of primary coordinates from a list of NXfields.

get_primary_coords(group)

Get all primary coordinates in a group.

nexus_group_to_dict(group, exclude[, ...])

Convert a NeXus group to a dictionary.

nxfield_to_xarray(field[, no_dims])

Convert a coord-like 1D NeXus field to a single xarray.DataArray.

nxgroup_to_xarray(group, data[, without_values])

Convert a NeXus group to an xarray DataArray.

Classes

Callable()

Hashable()

Iterable()

Mapping()

A Mapping is a generic container for associating key/value pairs.

Sequence()

All the operations on a read-only sequence.
erlab.io.nexusutils.get_primary_coords(group)[source]

Get all primary coordinates in a group.

Retrieves all fields with the attribute primary=1 in the group and its subgroups recursively. The output list is sorted by the axis attribute of the fields.

Parameters:

group (NXgroup) – The group to search for the coordinates.

Returns:

fields_primary (list of NXfield)

Return type:

list[NXfield]

erlab.io.nexusutils.get_non_primary_coords(group)[source]

Get all non-primary coordinates in a group.

Retrieves all fields with the attribute axis in the group and its subgroups recursively. The output list is sorted by the order of traversal.

Parameters:

group (NXgroup) – The group to search for the coordinates.

Returns:

fields_non_primary (list of NXfield)

Return type:

list[NXfield]

erlab.io.nexusutils.get_primary_coord_dict(fields)[source]

Generate a dictionary of primary coordinates from a list of NXfields.

The output dictionary contains the absolute NXpath of the field as the key and the value is either a xarray.DataArray or a tuple of the associated dimensions, data, and attributes.

The output arguments can be directly used as arguments for the xarray.DataArray constructor.

If there are multiple fields with the same axis, one of the fields will depend on the other field.

Parameters:

fields (list of NXfield) – The list of primary coordinates to be converted. The list can be obtained from a NXgroup using get_primary_coords().

Returns:

  • dims (tuple of str) – The dimension names of the primary coordinates.

  • coords (dict of str to DataArray or tuple) – The dictionary of primary coordinates in the group.

Return type:

tuple[tuple[str, …], dict[str, DataArray | tuple]]

erlab.io.nexusutils.get_coord_dict(group)[source]

Generate a dictionary of coordinates from a NeXus group.

Parameters:

group (NXgroup) – The NeXus group from which to extract coordinates.

Returns:

  • dims (tuple of str) – The dimension names of the primary coordinates.

  • coords (dict of str to DataArray or tuple) – The dictionary of all coordinates in the group.

Return type:

tuple[tuple[str, …], dict[str, DataArray | tuple]]

erlab.io.nexusutils.nexus_group_to_dict(group, exclude, relative=True, replace_slash=True, parse=False)[source]

Convert a NeXus group to a dictionary.

This function takes a NeXus group and converts it into a dictionary where the keys are the paths of the group’s items relative to the group’s root path, and the values are the corresponding items.

Parameters:

  • group (NXgroup) – The NeXus group to be converted.

  • exclude (Sequence[str] | None) – List of paths to exclude from the output.

  • relative (bool, default: True) – Whether to use the relative or absolute paths of the items. If True, the keys are the paths of the items relative to the path of the group. If False, the keys are the absolute paths of the items relative to the root of the NeXus file.

  • replace_slash (bool, default: True) – Whether to replace the slashes in the paths with dots.

  • parse (bool, default: False) – Whether to coerce the values of NXfields to native Python types.

erlab.io.nexusutils.nxfield_to_xarray(field, no_dims=False)[source]

Convert a coord-like 1D NeXus field to a single xarray.DataArray.

Parameters:

field (NXfield) – The NeXus field to be converted.

Returns:

DataArray

Return type:

DataArray

erlab.io.nexusutils.nxgroup_to_xarray(group, data, without_values=False)[source]

Convert a NeXus group to an xarray DataArray.

Parameters:

  • group (NXgroup) – The NeXus group to be converted.

  • data (str or callable) –

    The location of the data values which can be specified in two ways:

    • If a string, it must be the relative path from group to the NXfield containing the data values.

    • If a callable, it must be a function that takes group as an argument and returns the NXfield containing the data values.

  • without_values (bool, default: False) – If True, the returned DataArray values will be filled with zeros. Use this to check the coords or attrs quickly without loading in the full data.

Returns:

DataArray – The DataArray containing the data. Dimension and coordinate names are the relative paths of the corresponding NXfields, with the slashes replaced by dots.

Return type:

DataArray

erlab.io.nexusutils.get_entry(filename, entry=None)[source]

Get an NXentry object from a NeXus file.

Parameters:

  • filename (str | PathLike) – The path to the NeXus file.

  • entry (str | None, default: None) – The path of the entry to get. If None, the first entry in the file is returned.

Returns:

entry (NXentry) – The NXentry object obtained from the file.

Return type:

NXentry