[WIP] XAS specialization using subclasses

[mretegan]

Another possibility for having fields that are acquisition mode dependent is to use subclasses as suggested here: nexusformat#1352 (comment)

This is a reasonable alternative, as it is unlikely that we will be able to define acquisition modes that will be reused by other techniques (the alternative option proposed above and implemented here: #6).

The two options were discussed in the NIAC https://www.nexusformat.org/Telco_20260211.html

[maurov]

@mretegan @woutdenolf @newville

My understanding of the NIAC minutes of Telco 20260211 is that both options are OK. As said many times, my position is to go for NeXus base classes representing the experimental data collection modes, as I wrote in the famous shared Google document long time ago. This solution has the strong advantage that then the base classes can be reused by other application definitions, like XMCD and other techniques. I do not understand why we are still hesitating on this. Please, let's move on.

As a first start, I propose implementing the basic modes that represent most of the XAS and other techniques' data:

• NXtrans: transmission, valid for any technique and any wavelength measuring sample absorption;
• NXtfy: total fluorescence yield;
• NXpfy: partial fluorescence yield;
• NXherfd: particular case of partial fluorescence yield with a high resolution spectrometer;

As an alternative, for the fluorescence yield (in view of the electron yield or the optical yield), we may adopt the subclass approach:

• NXfy base class:
  • NXfy_total
  • NXfy_partial
  • NXfy_herfd

But I think this is just a complication and I would just go for the first approach of base classes for each experimental collection mode.

[newville]

@maurov @mretegan Thanks (and sorry for the delay). I'm OK with either approach. I see the modes as mostly informative, as they suggest (but do not necessarily require) changes in the processing and analysis. But those steps are not really fixed anyway, so mode is mostly a "type hint".

[mretegan]

Thank you both for your input. I think that to have a complete picture, it will make sense to finish both in parallel and to create a few HDF5 examples. I will start working on this tomorrow.

[maurov]

@maurov @mretegan Thanks (and sorry for the delay). I'm OK with either approach. I see the modes as mostly informative, as they suggest (but do not necessarily require) changes in the processing and analysis. But those steps are not really fixed anyway, so mode is mostly a "type hint".

Hi @newville thanks for your feedback. To me, the modes are more than just informative. They tell exactly what is "mu" and how it was measured. For example, Fe K-edge XAS "mu" of Fe2O3 measured in transmission is a different thing than Fe K-edge XAS "mu" of Fe2O3 measured in HERFD. Furthermore, the "minimum required metadata" for transmission are not the same as HERFD.

[maurov]

Thank you both for your input. I think that to have a complete picture, it will make sense to finish both in parallel and to create a few HDF5 examples. I will start working on this tomorrow.

@mretegan for me it is very difficult to read the .nxdl.xml files directly. Would it be possible to have an automatic build of the documentation on the ESRF gitlab server? Or link here two HDF5 files generated following the two approaches. By the way, I do not think that our decision should be based on HDF5 readability, as most likely are our software tools that will read the HDF5 file, not humans.

[newville]

@maurov I would be cautious about being overly strict here.

Yes, data measured in different modes are different, and processing/analysis may want to do different steps based on the mode. And the mode should be stated.

And, yes, HERFD really ought to state energy analyzed (but that is also a trusted value), but is NeXuS going to say that a file is invalid if it states mode="HERFD" but does not correctly spell "analyzed energy" in every group?

[mretegan]

Thank you both for your input. I think that to have a complete picture, it will make sense to finish both in parallel and to create a few HDF5 examples. I will start working on this tomorrow.

@mretegan for me it is very difficult to read the .nxdl.xml files directly. Would it be possible to have an automatic build of the documentation on the ESRF gitlab server? Or link here two HDF5 files generated following the two approaches. By the way, I do not think that our decision should be based on HDF5 readability, as most likely are our software tools that will read the HDF5 file, not humans.

We have something set up, but it builds the main branch, and every time we want to switch, we need to update the CI file https://gitlab.esrf.fr/hdf5/nexus/nxxas.

You can also build locally. Go to the nexus_definitions folder and run (I use uv, but vanilla pip should work):

uv venv --python 3.12
source .venv/bin/activate
uv pip install -r requirements.txt 
make clean; make local
firefox build/manual/build/html/classes/applications/NXxas_new.html