Full documentation of NXdetector and related classes

[eugenwintersberger]

We have currently no reasonable documentation for NXdetector and related classes. In addition some fields in the NXdetector documentation cannot be described properly within the NXDL file as sketches would be required to make the text unambiguous.

I will start working on this in a new branch related to this issue.

[zjttoefs]

Sketches would help.

But the branch is stale. Is it worth keeping?

[zjttoefs]

Dropping this for now. A more visual explanation is still a good idea, if someone wants to volunteer.

[prjemian]

I will recover the drawings that were provided in hopes that they can be used. And then close the associated branch.

[prjemian]

@eugenwintersberger : Added your drawings and documentation into master but have not merged the changes into design.rst yet. Would you like to complete this work?

[prjemian]

Any volunteers?

[phyy-nx]

Proposal is for @yayahjb and myself to review NXdetector from the context of the HDRMX and Gold Standard paper

[yayahjb]

We will be working in
(https://github.com/nexusformat/definitions/blob/412-ff-NXdetector-documentation/manual/source/_static/412-detector-docs/detectors.txt)

for which I have created the new branch 412-ff-NXdetector-documentation to continue the work begun by Eugen and Pete. We need to add in all the relevant information from the Gold Standard paper into detectors.txt. Then that file will need to be added into design.rst. For the 2020 code camp we should make enough of a start on updating detectors,txt so that others from outside of the synchrotron and XFEL worlds can comment and extend the work. This is a big job, which will need a lot more drawings. There will be HDRMX e-meetings between now and summer 2021. If at all possible, we should try to have an agreed text in time for the summer 2021 ACA and IUCr XXV meetings.
Regards,
Herbert

[phyy-nx]

Feature request: add depends_on as field in NXdetector_module. See nexusformat/cnxvalidate#27 (comment)

[phyy-nx]

Another thing to consider. gain_setting is available as enumeration in NXdetector:

  <field name="gain_setting" type="NX_CHAR">
    <doc>The gain setting of the detector. This influences background etc.</doc>
    <enumeration>
      <item value="high"/>
      <item value="standard"/>
      <item value="fast"/>
      <item value="auto"/>
    </enumeration>
  </field>

This does not cover these use cases:

• Known gain value as a single floating point number
• Known gain map, with per-pixel gain
• Multiple gain maps, selected using automatic gain switching

Further pedestals aren't specified as option, which can follow the same pattern of use cases as the gain.

Resolving this is a precondition of #711

[phyy-nx]

Possibly include documentation from NXmx Gold Standard paper:

https://journals.iucr.org/m/issues/2020/05/00/ti5018/index.html

(Here are the copyright details from IUCr https://journals.iucr.org/services/termsofuse.html)

[prjemian]

Related to

• Clarify NXdetector gain_setting and remove enumeration. #896

[prjemian]

No work on this issue at 2022-06 Code Camp. Is it necessary to resolve this for release of NXDL now?

[prjemian]

Apparently, the branch cannot be found and this work seems lost now.

@eugenwintersberger Can you find the branch or the content you were proposing? Otherwise I suggest closing as Won't fix.

[eugenwintersberger]

I am currently not at home but I will have a look on that during the weekend. However, since this is a 7 year old issue and I am no longer working for DESY and in the synchrotron business since 2018 I cannot make any promises if I can find the branch in my working copies. If you do not get any response until Sunday evening do me a favor and send me a short reminder :D

[eugenwintersberger]

Could not find the branch during a swift search through my working copies yesterday. There is still a change that it is in one of thw working copies in the offline archives. I have no idea when I have time to check this. I would thus suggest to put this to Won´t fix for now.

[prjemian]

@eugenwintersberger Thanks!