Introduce NXemission_line base class

[mretegan]

The PR introduces a new base class to describe an emission line. This base class will be used in the updated XAS definition (see #1352)

Because this may be of broader interest, and to make the review of the forthcoming XAS application definition easier, this base class is being submitted as a separate PR.

A question that came up in our previous discussion (XraySpectroscopy#8) was how to group together multiple emission lines. NXcollection was discarded as it is not validated. Another proposed alternative was NXobject (XraySpectroscopy#8 (comment)) or using a new container class NXemission_lines, which would result in an HDF5 structure looking like this:

/
├── entry:NXentry
│   └── emission_lines:NXemission_lines
│       ├── line_1:NXemission_line
│       │   ├── name = "K-L3"
│       │   └── energy = 5414.72   (units="eV")
│       ├── line_2:NXemission_line
│       │   ├── name = "K-L2"
│       │   └── energy = 5405.5    (units="eV")
│       └── line_3:NXemission_line
│           ├── name = "K-M3"
│           └── energy = 5946.7    (units="eV")

[mretegan]

The PR now adds three two more base classes.

• NXemission_lines which is a container for grouping multiple NXemission_line https://nexus-definitions.readthedocs.io/en/add-nxemission-line-class/classes/contributed_definitions/NXemission_lines.html
• NXauger_line describes non radiative Auger decay https://nexus-definitions.readthedocs.io/en/add-nxemission-line-class/classes/contributed_definitions/NXauger_line.html
  - NXelement defines a chemical element https://nexus-definitions.readthedocs.io/en/add-nxemission-line-class/classes/base_classes/NXelement.html, which is required for a proper description of the emission and Auger lines.

/
├── entry:NXentry
│   └── emission_lines:NXemission_lines
│       ├── line_1:NXemission_line
│       │   ├── element:NXatom
│       │   │   └── symbol = "Cr"
│       │   ├── name = "K-L3"
│       │   └── energy = 5414.72   (units="eV")
│       ├── line_2:NXemission_line
│       │   ├── element:NXatom
│       │   │   └── symbol = "Cr"
│       │   ├── name = "K-L2"
│       │   └── energy = 5405.5    (units="eV")
│       └── line_3:NXemission_line
│           ├── element:NXatom
│           │   └── symbol = "Cr"
│           ├── name = "K-M3"
│           └── energy = 5946.7    (units="eV")

[phyy-nx]

From Telco Apr 29: general approval was received. There were rumblings of linking to external databases instead of having copies of things such as the periodic table, but the consensus was that this could be ok.

There are implications to other base clases, e.g. NXchemical_composition which has an ELEMENT field of type NXatom, and in contributed, NXsubstance. This should be discussed more, such as should we introduce a new base class, NXelement, or should the XAS application definitions use NXatom instead?

[mretegan]

After looking at NXatom, I believe it should be possible to use it instead of creating a NXelement.

[phyy-nx]

Great, @mretegan will you provide a new version then?

[mretegan]

@phyy-nx Here is a version using NXatom for the absorber in NXxas https://nexus-definitions.readthedocs.io/en/xas-using-inheritance/classes/contributed_definitions/NXxas.html

I only use the name field from the base class.

[phyy-nx]

That looks reasonable to me. I see quite a few changes in that version of NXxas compared to the public version. What are your plans for that version of NXxas and for this PR at this point?

[mretegan]

@phyy-nx I apologize for dragging my feet with this PR. It should be ready for review.

I am unsure whether element should be a field inside the NXemission_line and NXauger_line. In the updated NXxas definitions, I only mark the name as required (see https://nexus-definitions.readthedocs.io/en/xas-using-inheritance/classes/contributed_definitions/NXxas_pfy.html), but there might be cases where it might be useful to have it in the base class.

The NXxas_pfy class also illustrates my second point: what can be used to group a bunch of NXemission_line. Here I create a new class NXemission_lines that acts as a container.

[sanbrock]

From Telco:

• It is OK to have an atom in each NXemmission_line even if it duplicates information. Note tha HDF5 supports links to avoid unnecessary copies.
• Let us check for an option, like NXgathering (as a generic container) instead creating a specific class NXemmission_lines. Such generic base class can then be reused in other use cases, too. ( @phyy-nx )

[PeterC-DLS]

Maybe rename element to atom as in NXabsorption_edge

[phyy-nx]

Howdy folks. I looked for precedent for NXemission_lines being a simple container for NXemission_line by first reading through the list of base classes and contributed definitions. Nothing immediately caught my eye.

However, I think it's not needed anyway. Looking at NXxas_mode in #1352, to me it looks simple to move NXemission_line up a level. So instead of this:

<group name="emission_lines" type="NXcollection" optional="true">
    <doc>
      Collection of emission lines detected or used in this measurement.
    </doc>
    <group type="NXemission_line" minOccurs="1" maxOccurs="unbounded"/>
  </group>

You get this:

<group type="NXemission_line" minOccurs="1" maxOccurs="unbounded">
  <doc>
    One of a collection of emission lines detected or used in this measurement.  Include as many as needed.
  </doc>
</group>

And a NeXus file following this pattern could look like:

entry:NXentry definition=NXxas
  mode:NXxas_mode
    hydrogen:NXemission_line
    deuterium:NXemission_line

The default nameType=any is used here, you could also use nameType=partial if you want:

<group name="LINENAME_emission_line" type="NXemission_line" nameType="partial">

I think the first version without the partial names looks cleaner though.

@mretegan Does that make sense? What do you think of this pattern?

[mretegan]

@phyy-nx Using nameType="partial", which would result in the structure below, could also work.

entry/
  ka1_emission_line/    (NXemission_line)
    name = "Ka1"
  kb1_emission_line/    (NXemission_line)
    name = "Kb1"   

If we use NXcollection we do not have validation anymore (even if it looks cleaner).

entry/
  emission_lines/        (NXcollection)
    ka1/                 (NXemission_line)
      name = "Ka1"
    kb1/                 (NXemission_line)
      name = "Kb1"

@PeterC-DLS Using atom instead of element as a field name is not the favored option (see the discussion in the PR mentioned by @woutdenolf). The existing atom field in NXabsorption_edge is a leftover that I will update.

The idea of using NXatom for the element field comes from https://www.nexusformat.org/Telco_20260318.html. My understanding is that with NXelement we would have two base classes expressing very similar things, which could be problematic when NeXus is connected to external ontologies.

Since, in general, the NX class is something that most users will not be aware of, we could go with having element as the field and NXatom as the class. It is not ideal, but this has precedence: https://manual.nexusformat.org/classes/base_classes/NXchemical_composition.html#nxchemical-composition. What do you think? @newville, @maurov

[prjemian]

This is correct. NeXus base classes inside NXcollection are meaningless. The content in a NXcollection is not validated, therefore it cannot be used to define any NeXus standard.

[maurov]

The idea of using NXatom for the element field comes from https://www.nexusformat.org/Telco_20260318.html. My understanding is that with NXelement we would have two base classes expressing very similar things, which could be problematic when NeXus is connected to external ontologies.

Since, in general, the NX class is something that most users will not be aware of, we could go with having element as the field and NXatom as the class. It is not ideal, but this has precedence: https://manual.nexusformat.org/classes/base_classes/NXchemical_composition.html#nxchemical-composition. What do you think? @newville, @maurov

IMHO, NXatom and NXelement are two well distinct classes that should be there both. NXelement is an element of the periodic table. NXatom has an element attribute (NXelement type) plus atomic coordinates. Thus, NXxas should require NXelement, not NXatom for the element attribute.

[newville]

@maurov @mretegan @PeterC-DLS

Strong -1 from me on "atom". That needs to be "element".

[phyy-nx]

Fair enough. I see that NXatom is enough different from NXelement that they could coexist. I'm still not totally on board with a copy of the periodic table in NeXus, as in the original PR. Does <field name="symbol"> need to be an enumeration?

[mretegan]

The enumeration was used for validation purposes. Without it, it would need to happen later. If that is not an issue, then I could implement the following structure:

<field name="symbol" type="NX_CHAR">
    <doc>
        Element symbol, e.g. ``Fe``.
    </doc>
</field>
<field name="atomic_number">
    <doc>
        Number of protons (Z), range 1–118.
    </doc>
</field>
<field name="standard_atomic_weight">
    <doc>
        The weighted arithmetic mean of the relative isotopic masses of all isotopes of that element weighted by each isotope's abundance on Earth.
    </doc>
</field>
...

[phyy-nx]

Personally I like that better. Ideally we want to refer to some other ontology to validate element names against, thought that doesn't really exist yet. Not specifying it here future proofs us for when that is available.

At least those are my musing. Would welcome other opinions.

[newville]

@mretegan @phyy-nx Element seems like the textbook example of an enumeration.

How could a data structure with any string (NX_CHAR) for "symbol" (not limited to one upper case letter followed optionally by one lower case letter), a field (presumably but not clearly a number, let alone a positive integer between 1 and 200) for "atomic number", and a field (presumably but not clearly a number, let alone a positive float less than 5000.) possibly be preferable to an Enumeration for Element?

Baffled.