[NeXus-committee] Example of links

[Osborn, Raymond]

HI everyone,
At yesterday’s Telco, someone asked if I could share the file I showed in NeXpy. If you already have NeXpy installed (‘pip install nexpy’), then you already have the file. Just open NeXpy and click on “Open Example File” in the Help menu. It was the one called “chopper.nxs”. Since there was some confusion even about the existence of links, I thought some notes might be helpful.

The reason the “target” attribute doesn’t appear in the NXDL files is roughly the same reason that “NX_class” attribute doesn’t appear. It’s part of the standard that is documented elsewhere (https://manual.nexusformat.org/design.html#design-links). In fact, at one point, it was considered best practice (or even required) for everything in a NXdata group to be a link to an object elsewhere. If you look at the latest NeXus publication [M. Koennecke, et al, Physica B 385–86, 1343–1345 (2006)], it states that “The NXdata group holds links to all the variables varied or collected during the scan.” It later softens this requirement, but the tree structure of chopper.nxs illustrates this idea:

>>> print(chopper['entry/data'].tree)
data:NXdata
  @axes = ['polar_angle', 'time_of_flight']
  @signal = 'data'
  data = int32(148x750)
  polar_angle -> /entry/instrument/detector/polar_angle
  time_of_flight -> /entry/instrument/detector/time_of_flight

In the absolutist version of NXdata, the data array should also have been linked to the corresponding NXdetector group.

In the nexusformat API, I can add a link to a NXdata group (or anywhere) by typing:

chopper[‘entry/data/polar_angle’] = NXlink(‘/entry/instrument/detector/polar_angle’)

This automatically makes this a hard link, although you can add “soft=True” to make it a soft link. It then adds the “target” attribute to chopper[‘(‘/entry/instrument/detector/polar_angle’]. To do the same in h5py, you would have to type:

with h5open(‘chopper.nxs’, ‘r+’) as f:
    f[‘/entry/data/polar_angle’] = f[‘/entry/instrument/detector/polar_angle’]
    f[‘/entry/data/polar_angle’].attrs[‘target’] = ‘/entry/instrument/detector/polar_angle’

This would add the ‘target’ attribute to object in both groups, since it’s the same object.

Personally, I think in the base classes, we should still only refer to fields, not links. In principle, any object, whether group or field, can be a link. In application definitions, if a field is contained within one group but also used in another, such as a NXdata group, it should be explicitly listed as a link. Whether the documentation needs improving is another debate.

With best regards,
Ray
--
Ray Osborn, Senior Scientist
Materials Science Division
Argonne National Laboratory
Lemont, IL 60439, USA
Phone: +1 (630) 252-9011
Email: ROsborn at anl.gov


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.nexusformat.org/pipermail/nexus-committee/attachments/20250128/e10f3983/attachment.htm>