How to specify per-shot wavelength

[phyy-nx]

At XFELs, each shot has a different wavelength. How can we specify this in NeXus? Looking the DIALS code that reads NeXus data, we are assuming that if incident_wavelength is an array, than each entry in that array is a wavelength for a different shot. However, I think we are mis-interpreting incident_wavelength:
http://download.nexusformat.org/doc/html/classes/applications/NXmx.html
"In the case of a polychromatic beam this is an array of the wavelengths with the relative weights in incident_wavelength_weight."

So what's the right way to do this?

Current problems in the documentation:

1. NXmx/beam is a base class NXbeam, but its documentation does not match the base class NXbeam documentation. Compare:
   http://download.nexusformat.org/doc/html/classes/applications/NXmx.html
   http://download.nexusformat.org/doc/html/classes/base_classes/NXbeam.html
2. incident_wavelength_spectrum, an NXdata field defined in NXmx in its beam group, has no doc string, and is not included in the base class NXbeam documentation.
3. The base class NXbeam has a NXdata field with this docstring: "Distribution of beam with respect to relevant variable e.g. wavelength. This is mainly useful for simulations which need to store plottable information at each beamline component." I don't understand what this means, can someone clarify it for me?

I think I could specify per-shot wavelength using the NXdata field of NXbeam or using incident_wavelength_spectrum, but the latter seems wrong since I'm not recording a spectrum.

Thoughts?

[vasole]

On 24/05/2019 18:36, Aaron S. Brewster wrote: At XFELs, each shot has a different wavelength. How can we specify this in NeXus? Looking the DIALS code that reads NeXus data, we are assuming that if incident_wavelength is an array, than each entry in that array is a wavelength for a different shot. However, I think we are mis-interpreting incident_wavelength: http://download.nexusformat.org/doc/html/classes/applications/NXmx.html "In the case of a polychromatic beam this is an array of the wavelengths with the relative weights in incident_wavelength_weight." So what's the right way to do this?

Nice question. I would assume that one can always play the [n_points, whatever] trick and treat a shape [1, n_wavelengths] as identical to a shape [n_wavelengths]. In your case incident_wavelength could have the shape [n_shots, n_wavelengths] however if each shot has different number of wavelengths I'm lost. This is my point of view and not an authoritative answer. Other opinions welcome.

[prjemian]

Follow the example of NXcanSAS. Look at I_axes in http://download.nexusformat.org/doc/html/classes/applications/NXcanSAS.html#nxcansas

[phyy-nx]

Existing keys in NXmx:

incident_wavelength: In the case of a monchromatic beam this is the scalar wavelength. In the case of a polychromatic beam this is an array of the wavelengths with the relative weights in incident_wavelength_weight.
incident_wavelength_weight:
In the case of a polychromatic beam this is an array of the relative weights of the corresponding wavelengths in incident_wavelength.

CodeCamp proposal: Modify these to have extra dimensionality to support per-shot wavelength. 4 use cases (n: number of shots, m: number of wavelengths in a spectrum):

1. One wavelength only. incident_wavelength is a scalar and incident_wavelength_weight is not set.
2. One wavelength per shot. incident_wavelength is an array of length n and incident_wavelength_weight is not set.
3. One spectrum only. incident_wavelength is an array of length m and incident_wavelength_weight is an array of length m.
4. One spectrum per shot. incident_wavelength is an array of dimension n,m and incident_wavelength_weight is an array of dimension n,m.

Additional proposal: deprecate incident_wavelength_spectrum. This field was part of the original NXmx spec, but has no doc string and it's unclear if it's been used before.

[phyy-nx]

From further discussion at CodeCamp 2020, the above proposal is replaced with the incoming pull request that insteads adds extra dimensionality to incident_wavelength, deprecates incident_wavelength_weight and incident_wavelength_spectrum, and adds incident_wavelength_axes to specify the axes names for incident_wavelength.

[yayahjb]

There is no reason to deprecate incident_wavelength_weight or incident_wavelength_spectrum at this time. First we need the agreed new presentation with worked examples. Then we need to put it in use for a while. Once it is successfully in use and we are sure mapping from old use cases to the new one is working well, then we should consider deprecating the use cases that are no longer being used. I suspect the simple synchrotron case of a few discrete wavelengths with stable relative weights would continue to best be served by an incident_wavelength array and incident_wavelength_weight array, but time will tell.

…

On Wed, Jan 22, 2020 at 12:34 PM Aaron S. Brewster ***@***.***> wrote: From further discussion at CodeCamp 2020, the above proposal is replaced with the incoming pull request that insteads adds extra dimensionality to incident_wavelength, deprecates incident_wavelength_weight and incident_wavelength_spectrum, and adds incident_wavelength_axes to specify the axes names for incident_wavelength. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#667?email_source=notifications&email_token=ABB6EAKSXQT5OUMQI3BNDJ3Q7B7T5A5CNFSM4HPRBGD2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEJUOHVY#issuecomment-577299415>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABB6EALVTZGOICJPHARK4NLQ7B7T5ANCNFSM4HPRBGDQ> .

[phyy-nx]

Thanks Herbert, I un-deprecated them, but I noted incident_wavelength_weight limited to 1D (single spectrum only) and clarified the language around the rest of the spec. #706 is ready for review again.

[phyy-nx]

New pull request (better!) in #717.