From 3b160c537dbdb13e8448e874f3c50443fd1772cb Mon Sep 17 00:00:00 2001 From: Aaron Brewster Date: Mon, 22 Mar 2021 15:24:12 -0700 Subject: [PATCH 1/6] Clarify NXdetector gain_setting and remove enumeration. Fixes #894 --- applications/NXmx.nxdl.xml | 4 +++- base_classes/NXdetector.nxdl.xml | 12 +++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/applications/NXmx.nxdl.xml b/applications/NXmx.nxdl.xml index 402b2c952..cc3045914 100644 --- a/applications/NXmx.nxdl.xml +++ b/applications/NXmx.nxdl.xml @@ -654,7 +654,9 @@ - The gain setting of the detector. This influences background. + The gain setting of the detector. This is a detector-specific value + meant to document the gain setting of the detector during data + collection, for detectors with multiple available gain settings. diff --git a/base_classes/NXdetector.nxdl.xml b/base_classes/NXdetector.nxdl.xml index 4ce4343bb..8d20604a7 100644 --- a/base_classes/NXdetector.nxdl.xml +++ b/base_classes/NXdetector.nxdl.xml @@ -705,13 +705,11 @@ - The gain setting of the detector. This influences background etc. - - - - - - + + The gain setting of the detector. This is a detector-specific value + meant to document the gain setting of the detector during data + collection, for detectors with multiple available gain settings. + From d28e0aa58959fde96b1d748b748229528cf9e670 Mon Sep 17 00:00:00 2001 From: Aaron Brewster Date: Sat, 12 Mar 2022 10:38:07 -0800 Subject: [PATCH 2/6] Include list of known terms for gain modes --- applications/NXmx.nxdl.xml | 5 +++++ base_classes/NXdetector.nxdl.xml | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/applications/NXmx.nxdl.xml b/applications/NXmx.nxdl.xml index cc3045914..7fb737fe3 100644 --- a/applications/NXmx.nxdl.xml +++ b/applications/NXmx.nxdl.xml @@ -657,6 +657,11 @@ The gain setting of the detector. This is a detector-specific value meant to document the gain setting of the detector during data collection, for detectors with multiple available gain settings. + + Examples of gain settings include: standard, fast, auto, high, + medium, low, mixed high/medium, and mixed medium/low. Developers are + encouraged to use one of these terms, or to submit additional terms + to add to the list. diff --git a/base_classes/NXdetector.nxdl.xml b/base_classes/NXdetector.nxdl.xml index 8d20604a7..c490e746b 100644 --- a/base_classes/NXdetector.nxdl.xml +++ b/base_classes/NXdetector.nxdl.xml @@ -709,6 +709,11 @@ The gain setting of the detector. This is a detector-specific value meant to document the gain setting of the detector during data collection, for detectors with multiple available gain settings. + + Examples of gain settings include: standard, fast, auto, high, + medium, low, mixed high/medium, and mixed medium/low. Developers are + encouraged to use one of these terms, or to submit additional terms + to add to the list. From a4861b5a157b984ff45b9466e718b034908fb594 Mon Sep 17 00:00:00 2001 From: Ben Watts Date: Mon, 13 Jun 2022 16:28:33 +0200 Subject: [PATCH 3/6] improve list --- base_classes/NXdetector.nxdl.xml | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/base_classes/NXdetector.nxdl.xml b/base_classes/NXdetector.nxdl.xml index c490e746b..05bd8f260 100644 --- a/base_classes/NXdetector.nxdl.xml +++ b/base_classes/NXdetector.nxdl.xml @@ -710,9 +710,18 @@ meant to document the gain setting of the detector during data collection, for detectors with multiple available gain settings. - Examples of gain settings include: standard, fast, auto, high, - medium, low, mixed high/medium, and mixed medium/low. Developers are - encouraged to use one of these terms, or to submit additional terms + Examples of gain settings include: + + * "standard" + * "fast" + * auto" + * "high" + * "medium" + * "low" + * "mixed high-medium" + * "mixed medium-low" + + Developers are encouraged to use one of these terms, or to submit additional terms to add to the list. From 691c10b086f5df1039abbfbcbce2b8bc2aaa883e Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Mon, 13 Jun 2022 09:29:59 -0500 Subject: [PATCH 4/6] DOC #896 per review --- applications/NXmx.nxdl.xml | 1715 +++++++++++++++--------------- base_classes/NXdetector.nxdl.xml | 17 +- 2 files changed, 875 insertions(+), 857 deletions(-) diff --git a/applications/NXmx.nxdl.xml b/applications/NXmx.nxdl.xml index 7fb737fe3..e631ed66e 100644 --- a/applications/NXmx.nxdl.xml +++ b/applications/NXmx.nxdl.xml @@ -22,857 +22,866 @@ # For further information, see http://www.nexusformat.org --> - - - - These symbols will be used below to coordinate datasets - with the same shape. Most MX x-ray detectors will produce - two-dimensional images. Some will produce three-dimensional - images, using one of the indices to select a detector module. - - - Rank of the ``data`` field - - - Number of scan points - - - Number of detector pixels in the slowest direction - - - Number of detector pixels in the second slowest direction - - - Number of detector pixels in the third slowest direction - - - Number of channels in the incident beam spectrum, if known - - - - An array of the hierarchical levels of the parents of detector - elements or groupings of detector elements. - A top-level element or grouping has parent level -1. - - - - - - functional application definition for macromolecular crystallography - - - - - - Note, it is recommended that ``file_name`` and ``file_time`` are included - as attributes at the root of a file that includes :ref:`NXmx`. See - :ref:`NXroot`. - - - - - Describes the version of the NXmx definition used to write this data. - This must be a text (not numerical) representation. Such as:: - - @version="1.0" - - - - - - - - - - - ISO 8601 time/date of the first data point collected in UTC, - using the Z suffix to avoid confusion with local time. - Note that the time zone of the beamline should be provided in - NXentry/NXinstrument/time_zone. - - - - - - ISO 8601 time/date of the last data point collected in UTC, - using the Z suffix to avoid confusion with local time. - Note that the time zone of the beamline should be provided in - NXentry/NXinstrument/time_zone. This field should only be - filled when the value is accurately observed. If the data - collection aborts or otherwise prevents accurate recording of - the end_time, this field should be omitted. - - - - - - ISO 8601 time/date of the last data point collected in UTC, - using the Z suffix to avoid confusion with local time. - Note that the time zone of the beamline should be provided in - NXentry/NXinstrument/time_zone. This field may be filled - with a value estimated before an observed value is available. - - - - - NeXus NXDL schema to which this file conforms - - - - - - - - - - For a dimension-2 detector, the rank of the data array will be 3. - For a dimension-3 detector, the rank of the data array will be 4. - This allows for the introduction of the frame number as the - first index. - - - - - - - - - - - - - Descriptive name of sample - - - - - - This is a requirement to describe for any scan experiment. - - The axis on which the sample position depends may be stored - anywhere, but is normally stored in the NXtransformations - group within the NXsample group. - - If there is no goniometer, e.g. with a jet, depends_on - should be set to "." - - - - - - This is the recommended location for sample goniometer - and other related axes. - - This is a requirement to describe for any scan experiment. - The reason it is optional is mainly to accommodate XFEL - single shot exposures. - - Use of the depends_on field and the NXtransformations group is - strongly recommended. As noted above this should be an absolute - requirement to have for any scan experiment. - - The reason it is optional is mainly to accommodate XFEL - single shot exposures. - - - - - - - - - - - - - Name of instrument. Consistency with the controlled - vocabulary beamline naming in - https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_beamline.html - and - https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.type.html - is highly recommended. - - - Short name for instrument, perhaps the acronym. - - - - - - ISO 8601 time_zone offset from UTC. - - - - - - - - - - Optional logical grouping of detectors. - - Each detector is represented as an NXdetector - with its own detector data array. Each detector data array - may be further decomposed into array sections by use of - NXdetector_module groups. Detectors can be grouped logically - together using NXdetector_group. Groups can be further grouped - hierarchically in a single NXdetector_group (for example, if - there are multiple detectors at an endstation or multiple - endstations at a facility). Alternatively, multiple - NXdetector_groups can be provided. - - The groups are defined hierarchically, with names given - in the group_names field, unique identifying indices given - in the field group_index, and the level in the hierarchy - given in the group_parent field. For example if an x-ray - detector group, DET, consists of four detectors in a - rectangular array:: - - DTL DTR - DLL DLR - - We could have:: - - group_names: ["DET", "DTL", "DTR", "DLL", "DLR"] - group_index: [1, 2, 3, 4, 5] - group_parent: [-1, 1, 1, 1, 1] - - - - - - An array of the names of the detectors or the names of - hierarchical groupings of detectors. - - - - - - An array of unique identifiers for detectors or groupings - of detectors. - - Each ID is a unique ID for the corresponding detector or group - named in the field group_names. The IDs are positive integers - starting with 1. - - - - - - - An array of the hierarchical levels of the parents of detectors - or groupings of detectors. - - A top-level grouping has parent level -1. - - - - - - - Normally the detector group will have the name ``detector``. - However, in the case of multiple detectors, each detector - needs a uniquely named NXdetector. - - - - - NeXus path to the detector positioner axis that most directly - supports the detector. In the case of a single-module - detector, the detector axis chain may start here. - - - - - - Location for axes (transformations) to do with the - detector. In the case of a single-module detector, the - axes of the detector axis chain may be stored here. - - - - - - Suggested container for detailed non-standard detector - information like corrections applied automatically or - performance settings. - - - - - - For a dimension-2 detector, the rank of the data array will be 3. - For a dimension-3 detector, the rank of the data array will be 4. - This allows for the introduction of the frame number as the - first index. - - - - - - - - - - - - name/manufacturer/model/etc. information. - - - - - - For a time-of-flight detector this is the scaling - factor to convert from the numeric value reported to - the flight time for a given measurement. - - - - - - Many detectors consist of multiple smaller modules that are - operated in sync and store their data in a common dataset. - To allow consistent parsing of the experimental geometry, - this application definiton requires all detectors to - define a detector module, even if there is only one. - - This group specifies the hyperslab of data in the data - array associated with the detector that contains the - data for this module. If the module is associated with - a full data array, rather than with a hyperslab within - a larger array, then a single module should be defined, - spanning the entire array. - - - - A dimension-2 or dimension-3 field which gives the indices - of the origin of the hyperslab of data for this module in the - main area detector image in the parent NXdetector module. - - The data_origin is 0-based. - - The frame number dimension (nP) is omitted. Thus the - data_origin field for a dimension-2 dataset with indices (nP, i, j) - will be an array with indices (i, j), and for a dimension-3 - dataset with indices (nP, i, j, k) will be an array with indices - (i, j, k). - - The :ref:`order <Design-ArrayStorageOrder>` of indices (i, j - or i, j, k) is slow to fast. - - - - - Two or three values for the size of the module in pixels in - each direction. Dimensionality and order of indices is the - same as for data_origin. - - - - - Two or three values for the stride of the module in pixels in - each direction. By default the stride is [1,1] or [1,1,1], - and this is the most likely case. This optional field is - included for completeness. - - - - - - Offset of the module in regards to the origin of the detector in an - arbitrary direction. - - - - - - - - - - - - - - - - Values along the direction of :ref:`fastest varying <Design-ArrayStorageOrder>` - pixel direction. The direction itself is given through the vector - attribute. - - - - - - - - - - - - - - - - Values along the direction of :ref:`slowest varying <Design-ArrayStorageOrder>` - pixel direction. The direction itself is given through the vector - attribute. - - - - - - - - - - - - - - - - - - Distance from the sample to the beam center. - Normally this value is for guidance only, the proper - geometry can be found following the depends_on axis chain, - But in appropriate cases where the dectector distance - to the sample is observable independent of the axis - chain, that may take precedence over the axis chain - calculation. - - - - - - Boolean to indicate if the distance is a derived, rather than - a primary observation. If distance_derived true or is not specified, - the distance is assumed to be derived from delector axis - specifications. - - - - - - Detector dead time. - - - - - - Elapsed actual counting time. - - - - - - Boolean to indicate if the distance is a derived, rather than - a primary observation. If true or not provided, that value of - beam_center_derived is assumed to be true. - - - - - - - - This is the x position where the direct beam would hit the - detector. This is a length and can be outside of the actual - detector. The length can be in physical units or pixels as - documented by the units attribute. Normally, this should - be derived from the axis chain, but the direct specification - may take precedence if it is not a derived quantity. - - - - - - This is the y position where the direct beam would hit the - detector. This is a length and can be outside of the actual - detector. The length can be in physical units or pixels as - documented by the units attribute. Normally, this should - be derived from the axis chain, but the direct specification - may take precedence if it is not a derived quantity. - - - - - - True when the angular calibration has been applied in the - electronics, false otherwise. - - - - - Angular calibration data. - - - - - - - - - - True when the flat field correction has been applied in the - electronics, false otherwise. - - - - - - Flat field correction data. If provided, it is recommended - that it be compressed. - - - - - - - - - - - - *** Deprecated form. Use plural form *** - Errors of the flat field correction data. If provided, it is recommended - that it be compressed. - - - - - - - - - - - Errors of the flat field correction data. If provided, it is recommended - that it be compressed. - - - - - - - - - - - True when the pixel mask correction has been applied in the - electronics, false otherwise. - - - - - - The 32-bit pixel mask for the detector. Can be either one mask - for the whole dataset (i.e. an array with indices i, j) or - each frame can have its own mask (in which case it would be - an array with indices nP, i, j). - - Contains a bit field for each pixel to signal dead, - blind, high or otherwise unwanted or undesirable pixels. - They have the following meaning: - - * bit 0: gap (pixel with no sensor) - * bit 1: dead - * bit 2: under-responding - * bit 3: over-responding - * bit 4: noisy - * bit 5: -undefined- - * bit 6: pixel is part of a cluster of problematic pixels (bit set in addition to others) - * bit 7: -undefined- - * bit 8: user defined mask (e.g. around beamstop) - * bits 9-30: -undefined- - * bit 31: virtual pixel (corner pixel with interpolated value) - - Normal data analysis software would not take pixels into account - when a bit in (mask & 0x0000FFFF) is set. Tag bit in the upper - two bytes would indicate special pixel properties that normally - would not be a sole reason to reject the intensity value (unless - lower bits are set. - - If the full bit depths is not required, providing a - mask with fewer bits is permissible. - - If needed, additional pixel masks can be specified by - including additional entries named pixel_mask_N, where - N is an integer. For example, a general bad pixel mask - could be specified in pixel_mask that indicates noisy - and dead pixels, and an additional pixel mask from - experiment-specific shadowing could be specified in - pixel_mask_2. The cumulative mask is the bitwise OR - of pixel_mask and any pixel_mask_N entries. - - If provided, it is recommended that it be compressed. - - - - - - - - - True when a count-rate correction has already been applied in - the data recorded here, false otherwise. - - - - - - How many bits the electronics record per pixel. - - - - - - Time it takes to read the detector (typically milliseconds). - This is important to know for time resolved experiments. - - - - - - This is time for each frame. This is exposure_time + readout - time. - - - - - - The gain setting of the detector. This is a detector-specific value - meant to document the gain setting of the detector during data - collection, for detectors with multiple available gain settings. - - Examples of gain settings include: standard, fast, auto, high, - medium, low, mixed high/medium, and mixed medium/low. Developers are - encouraged to use one of these terms, or to submit additional terms - to add to the list. - - - - - - The value at which the detector goes into saturation. - Data above this value is known to be invalid. - - For example, given a saturation_value and an underload_value, - the valid pixels are those less than or equal to the - saturation_value and greater than or equal to the underload_value. - - - - - - The lowest value at which pixels for this detector - would be reasonably be measured. - - For example, given a saturation_value and an underload_value, - the valid pixels are those less than or equal to the - saturation_value and greater than or equal to the underload_value. - - - - - - At times, radiation is not directly sensed by the detector. - Rather, the detector might sense the output from some - converter like a scintillator. - This is the name of this converter material. - - - - - - At times, radiation is not directly sensed by the detector. - Rather, the detector might sense the output from some - converter like a scintillator. This is the thickness of this - converter material. - - - - - - Single photon counter detectors can be adjusted for a certain - energy range in which they work optimally. This is the energy - setting for this. If the detector supports multiple thresholds, - this is an array. - - - - - - Description of type such as scintillator, - ccd, pixel, image - plate, CMOS, ... - - - - - - - In the case of a monchromatic beam this is the scalar - wavelength. - - Several other use cases are permitted, depending on the - presence or absence of other incident_wavelength_X - fields. - - In the case of a polychromatic beam this is an array of - length **m** of wavelengths, with the relative weights - in ``incident_wavelength_weights``. - - In the case of a monochromatic beam that varies shot- - to-shot, this is an array of wavelengths, one for each - recorded shot. Here, ``incident_wavelength_weights`` and - incident_wavelength_spread are not set. - - In the case of a polychromatic beam that varies shot-to- - shot, this is an array of length **m** with the relative - weights in ``incident_wavelength_weights`` as a 2D array. - - In the case of a polychromatic beam that varies shot-to- - shot and where the channels also vary, this is a 2D array - of dimensions **nP** by **m** (slow to fast) with the - relative weights in ``incident_wavelength_weights`` as a 2D - array. - - Note, :ref:`variants <Design-Variants>` are a good way - to represent several of these use cases in a single dataset, - e.g. if a calibrated, single-value wavelength value is - available along with the original spectrum from which it - was calibrated. - - - - - - In the case of a polychromatic beam this is an array of - length **m** of the relative weights of the corresponding - wavelengths in incident_wavelength. - - In the case of a polychromatic beam that varies shot-to- - shot, this is a 2D array of dimensions **nP** by **m** - (slow to fast) of the relative weights of the - corresponding wavelengths in incident_wavelength. - - - - - In the case of a polychromatic beam this is an array of - length **m** of the relative weights of the corresponding - wavelengths in ``incident_wavelength``. - - In the case of a polychromatic beam that varies shot-to- - shot, this is a 2D array of dimensions **np** by **m** - (slow to fast) of the relative weights of the - corresponding wavelengths in ``incident_wavelength``. - - - - - - The wavelength spread FWHM for the corresponding - wavelength(s) in incident_wavelength. - - In the case of shot-to-shot variation in the wavelength - spread, this is a 2D array of dimension **nP** by - **m** (slow to fast) of the spreads of the - corresponding wavelengths in incident_wavelength. - - - - - - - - Flux density incident on beam plane area in photons - per second per unit area. - - In the case of a beam that varies in flux shot-to-shot, - this is an array of values, one for each recorded shot. - - - - - - Flux incident on beam plane in photons per second. - - In the case of a beam that varies in total flux shot-to-shot, - this is an array of values, one for each recorded shot. - - - - - - Two-element array of FWHM (if Gaussian or Airy function) or - diameters (if top hat) or widths (if rectangular) of the beam - in the order x, y - - - - - - - - - The beam profile, Gaussian, Airy function, top-hat or - rectangular. The profile is given in the plane of - incidence of the beam on the sample. - - - - - - - - - - - - - - - - - - - - - - The neutron or x-ray storage ring/facility. Note, the NXsource base class - has many more fields available, but at present we only require the name. - - - - Name of source. Consistency with the naming in - https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_site.html - controlled vocabulary is highly recommended. - - - short name for source, perhaps the acronym - - - - + category="application" + xmlns="http://definition.nexusformat.org/nxdl/3.1" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd" + > + + + + These symbols will be used below to coordinate datasets + with the same shape. Most MX x-ray detectors will produce + two-dimensional images. Some will produce three-dimensional + images, using one of the indices to select a detector module. + + + Rank of the ``data`` field + + + Number of scan points + + + Number of detector pixels in the slowest direction + + + Number of detector pixels in the second slowest direction + + + Number of detector pixels in the third slowest direction + + + Number of channels in the incident beam spectrum, if known + + + + An array of the hierarchical levels of the parents of detector + elements or groupings of detector elements. + A top-level element or grouping has parent level -1. + + + + + + functional application definition for macromolecular crystallography + + + + + + Note, it is recommended that ``file_name`` and ``file_time`` are included + as attributes at the root of a file that includes :ref:`NXmx`. See + :ref:`NXroot`. + + + + + Describes the version of the NXmx definition used to write this data. + This must be a text (not numerical) representation. Such as:: + + @version="1.0" + + + + + + + + + + + ISO 8601 time/date of the first data point collected in UTC, + using the Z suffix to avoid confusion with local time. + Note that the time zone of the beamline should be provided in + NXentry/NXinstrument/time_zone. + + + + + + ISO 8601 time/date of the last data point collected in UTC, + using the Z suffix to avoid confusion with local time. + Note that the time zone of the beamline should be provided in + NXentry/NXinstrument/time_zone. This field should only be + filled when the value is accurately observed. If the data + collection aborts or otherwise prevents accurate recording of + the end_time, this field should be omitted. + + + + + + ISO 8601 time/date of the last data point collected in UTC, + using the Z suffix to avoid confusion with local time. + Note that the time zone of the beamline should be provided in + NXentry/NXinstrument/time_zone. This field may be filled + with a value estimated before an observed value is available. + + + + + NeXus NXDL schema to which this file conforms + + + + + + + + + + For a dimension-2 detector, the rank of the data array will be 3. + For a dimension-3 detector, the rank of the data array will be 4. + This allows for the introduction of the frame number as the + first index. + + + + + + + + + + + + + Descriptive name of sample + + + + + + This is a requirement to describe for any scan experiment. + + The axis on which the sample position depends may be stored + anywhere, but is normally stored in the NXtransformations + group within the NXsample group. + + If there is no goniometer, e.g. with a jet, depends_on + should be set to "." + + + + + + This is the recommended location for sample goniometer + and other related axes. + + This is a requirement to describe for any scan experiment. + The reason it is optional is mainly to accommodate XFEL + single shot exposures. + + Use of the depends_on field and the NXtransformations group is + strongly recommended. As noted above this should be an absolute + requirement to have for any scan experiment. + + The reason it is optional is mainly to accommodate XFEL + single shot exposures. + + + + + + + + + + + + + Name of instrument. Consistency with the controlled + vocabulary beamline naming in + https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_beamline.html + and + https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.type.html + is highly recommended. + + + Short name for instrument, perhaps the acronym. + + + + + + ISO 8601 time_zone offset from UTC. + + + + + + + + + + Optional logical grouping of detectors. + + Each detector is represented as an NXdetector + with its own detector data array. Each detector data array + may be further decomposed into array sections by use of + NXdetector_module groups. Detectors can be grouped logically + together using NXdetector_group. Groups can be further grouped + hierarchically in a single NXdetector_group (for example, if + there are multiple detectors at an endstation or multiple + endstations at a facility). Alternatively, multiple + NXdetector_groups can be provided. + + The groups are defined hierarchically, with names given + in the group_names field, unique identifying indices given + in the field group_index, and the level in the hierarchy + given in the group_parent field. For example if an x-ray + detector group, DET, consists of four detectors in a + rectangular array:: + + DTL DTR + DLL DLR + + We could have:: + + group_names: ["DET", "DTL", "DTR", "DLL", "DLR"] + group_index: [1, 2, 3, 4, 5] + group_parent: [-1, 1, 1, 1, 1] + + + + + + An array of the names of the detectors or the names of + hierarchical groupings of detectors. + + + + + + An array of unique identifiers for detectors or groupings + of detectors. + + Each ID is a unique ID for the corresponding detector or group + named in the field group_names. The IDs are positive integers + starting with 1. + + + + + + + An array of the hierarchical levels of the parents of detectors + or groupings of detectors. + + A top-level grouping has parent level -1. + + + + + + + Normally the detector group will have the name ``detector``. + However, in the case of multiple detectors, each detector + needs a uniquely named NXdetector. + + + + + NeXus path to the detector positioner axis that most directly + supports the detector. In the case of a single-module + detector, the detector axis chain may start here. + + + + + + Location for axes (transformations) to do with the + detector. In the case of a single-module detector, the + axes of the detector axis chain may be stored here. + + + + + + Suggested container for detailed non-standard detector + information like corrections applied automatically or + performance settings. + + + + + + For a dimension-2 detector, the rank of the data array will be 3. + For a dimension-3 detector, the rank of the data array will be 4. + This allows for the introduction of the frame number as the + first index. + + + + + + + + + + + + name/manufacturer/model/etc. information. + + + + + + For a time-of-flight detector this is the scaling + factor to convert from the numeric value reported to + the flight time for a given measurement. + + + + + + Many detectors consist of multiple smaller modules that are + operated in sync and store their data in a common dataset. + To allow consistent parsing of the experimental geometry, + this application definiton requires all detectors to + define a detector module, even if there is only one. + + This group specifies the hyperslab of data in the data + array associated with the detector that contains the + data for this module. If the module is associated with + a full data array, rather than with a hyperslab within + a larger array, then a single module should be defined, + spanning the entire array. + + + + A dimension-2 or dimension-3 field which gives the indices + of the origin of the hyperslab of data for this module in the + main area detector image in the parent NXdetector module. + + The data_origin is 0-based. + + The frame number dimension (nP) is omitted. Thus the + data_origin field for a dimension-2 dataset with indices (nP, i, j) + will be an array with indices (i, j), and for a dimension-3 + dataset with indices (nP, i, j, k) will be an array with indices + (i, j, k). + + The :ref:`order <Design-ArrayStorageOrder>` of indices (i, j + or i, j, k) is slow to fast. + + + + + Two or three values for the size of the module in pixels in + each direction. Dimensionality and order of indices is the + same as for data_origin. + + + + + Two or three values for the stride of the module in pixels in + each direction. By default the stride is [1,1] or [1,1,1], + and this is the most likely case. This optional field is + included for completeness. + + + + + + Offset of the module in regards to the origin of the detector in an + arbitrary direction. + + + + + + + + + + + + + + + + Values along the direction of :ref:`fastest varying <Design-ArrayStorageOrder>` + pixel direction. The direction itself is given through the vector + attribute. + + + + + + + + + + + + + + + + Values along the direction of :ref:`slowest varying <Design-ArrayStorageOrder>` + pixel direction. The direction itself is given through the vector + attribute. + + + + + + + + + + + + + + + + + + Distance from the sample to the beam center. + Normally this value is for guidance only, the proper + geometry can be found following the depends_on axis chain, + But in appropriate cases where the dectector distance + to the sample is observable independent of the axis + chain, that may take precedence over the axis chain + calculation. + + + + + + Boolean to indicate if the distance is a derived, rather than + a primary observation. If distance_derived true or is not specified, + the distance is assumed to be derived from delector axis + specifications. + + + + + + Detector dead time. + + + + + + Elapsed actual counting time. + + + + + + Boolean to indicate if the distance is a derived, rather than + a primary observation. If true or not provided, that value of + beam_center_derived is assumed to be true. + + + + + + + + This is the x position where the direct beam would hit the + detector. This is a length and can be outside of the actual + detector. The length can be in physical units or pixels as + documented by the units attribute. Normally, this should + be derived from the axis chain, but the direct specification + may take precedence if it is not a derived quantity. + + + + + + This is the y position where the direct beam would hit the + detector. This is a length and can be outside of the actual + detector. The length can be in physical units or pixels as + documented by the units attribute. Normally, this should + be derived from the axis chain, but the direct specification + may take precedence if it is not a derived quantity. + + + + + + True when the angular calibration has been applied in the + electronics, false otherwise. + + + + + Angular calibration data. + + + + + + + + + + True when the flat field correction has been applied in the + electronics, false otherwise. + + + + + + Flat field correction data. If provided, it is recommended + that it be compressed. + + + + + + + + + + + + *** Deprecated form. Use plural form *** + Errors of the flat field correction data. If provided, it is recommended + that it be compressed. + + + + + + + + + + + Errors of the flat field correction data. If provided, it is recommended + that it be compressed. + + + + + + + + + + + True when the pixel mask correction has been applied in the + electronics, false otherwise. + + + + + + The 32-bit pixel mask for the detector. Can be either one mask + for the whole dataset (i.e. an array with indices i, j) or + each frame can have its own mask (in which case it would be + an array with indices nP, i, j). + + Contains a bit field for each pixel to signal dead, + blind, high or otherwise unwanted or undesirable pixels. + They have the following meaning: + + * bit 0: gap (pixel with no sensor) + * bit 1: dead + * bit 2: under-responding + * bit 3: over-responding + * bit 4: noisy + * bit 5: -undefined- + * bit 6: pixel is part of a cluster of problematic pixels (bit set in addition to others) + * bit 7: -undefined- + * bit 8: user defined mask (e.g. around beamstop) + * bits 9-30: -undefined- + * bit 31: virtual pixel (corner pixel with interpolated value) + + Normal data analysis software would not take pixels into account + when a bit in (mask & 0x0000FFFF) is set. Tag bit in the upper + two bytes would indicate special pixel properties that normally + would not be a sole reason to reject the intensity value (unless + lower bits are set. + + If the full bit depths is not required, providing a + mask with fewer bits is permissible. + + If needed, additional pixel masks can be specified by + including additional entries named pixel_mask_N, where + N is an integer. For example, a general bad pixel mask + could be specified in pixel_mask that indicates noisy + and dead pixels, and an additional pixel mask from + experiment-specific shadowing could be specified in + pixel_mask_2. The cumulative mask is the bitwise OR + of pixel_mask and any pixel_mask_N entries. + + If provided, it is recommended that it be compressed. + + + + + + + + + True when a count-rate correction has already been applied in + the data recorded here, false otherwise. + + + + + + How many bits the electronics record per pixel. + + + + + + Time it takes to read the detector (typically milliseconds). + This is important to know for time resolved experiments. + + + + + + This is time for each frame. This is exposure_time + readout + time. + + + + + + The gain setting of the detector. This is a detector-specific value + meant to document the gain setting of the detector during data + collection, for detectors with multiple available gain settings. + + Examples of gain settings include: + + * ``standard`` + * ``fast`` + * ``auto`` + * ``high`` + * ``medium`` + * ``low`` + * ``mixed high to medium`` + * ``mixed medium to low``. + + Developers are encouraged to use one of these terms, or to submit + additional terms to add to the list. + + + + + + The value at which the detector goes into saturation. + Data above this value is known to be invalid. + + For example, given a saturation_value and an underload_value, + the valid pixels are those less than or equal to the + saturation_value and greater than or equal to the underload_value. + + + + + + The lowest value at which pixels for this detector + would be reasonably be measured. + + For example, given a saturation_value and an underload_value, + the valid pixels are those less than or equal to the + saturation_value and greater than or equal to the underload_value. + + + + + + At times, radiation is not directly sensed by the detector. + Rather, the detector might sense the output from some + converter like a scintillator. + This is the name of this converter material. + + + + + + At times, radiation is not directly sensed by the detector. + Rather, the detector might sense the output from some + converter like a scintillator. This is the thickness of this + converter material. + + + + + + Single photon counter detectors can be adjusted for a certain + energy range in which they work optimally. This is the energy + setting for this. If the detector supports multiple thresholds, + this is an array. + + + + + + Description of type such as scintillator, + ccd, pixel, image + plate, CMOS, ... + + + + + + + In the case of a monchromatic beam this is the scalar + wavelength. + + Several other use cases are permitted, depending on the + presence or absence of other incident_wavelength_X + fields. + + In the case of a polychromatic beam this is an array of + length **m** of wavelengths, with the relative weights + in ``incident_wavelength_weights``. + + In the case of a monochromatic beam that varies shot- + to-shot, this is an array of wavelengths, one for each + recorded shot. Here, ``incident_wavelength_weights`` and + incident_wavelength_spread are not set. + + In the case of a polychromatic beam that varies shot-to- + shot, this is an array of length **m** with the relative + weights in ``incident_wavelength_weights`` as a 2D array. + + In the case of a polychromatic beam that varies shot-to- + shot and where the channels also vary, this is a 2D array + of dimensions **nP** by **m** (slow to fast) with the + relative weights in ``incident_wavelength_weights`` as a 2D + array. + + Note, :ref:`variants <Design-Variants>` are a good way + to represent several of these use cases in a single dataset, + e.g. if a calibrated, single-value wavelength value is + available along with the original spectrum from which it + was calibrated. + + + + + + In the case of a polychromatic beam this is an array of + length **m** of the relative weights of the corresponding + wavelengths in incident_wavelength. + + In the case of a polychromatic beam that varies shot-to- + shot, this is a 2D array of dimensions **nP** by **m** + (slow to fast) of the relative weights of the + corresponding wavelengths in incident_wavelength. + + + + + In the case of a polychromatic beam this is an array of + length **m** of the relative weights of the corresponding + wavelengths in ``incident_wavelength``. + + In the case of a polychromatic beam that varies shot-to- + shot, this is a 2D array of dimensions **np** by **m** + (slow to fast) of the relative weights of the + corresponding wavelengths in ``incident_wavelength``. + + + + + + The wavelength spread FWHM for the corresponding + wavelength(s) in incident_wavelength. + + In the case of shot-to-shot variation in the wavelength + spread, this is a 2D array of dimension **nP** by + **m** (slow to fast) of the spreads of the + corresponding wavelengths in incident_wavelength. + + + + + + + + Flux density incident on beam plane area in photons + per second per unit area. + + In the case of a beam that varies in flux shot-to-shot, + this is an array of values, one for each recorded shot. + + + + + + Flux incident on beam plane in photons per second. + + In the case of a beam that varies in total flux shot-to-shot, + this is an array of values, one for each recorded shot. + + + + + + Two-element array of FWHM (if Gaussian or Airy function) or + diameters (if top hat) or widths (if rectangular) of the beam + in the order x, y + + + + + + + + + The beam profile, Gaussian, Airy function, top-hat or + rectangular. The profile is given in the plane of + incidence of the beam on the sample. + + + + + + + + + + + + + + + + + + + + + + The neutron or x-ray storage ring/facility. Note, the NXsource base class + has many more fields available, but at present we only require the name. + + + + Name of source. Consistency with the naming in + https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_site.html + controlled vocabulary is highly recommended. + + + short name for source, perhaps the acronym + + + + diff --git a/base_classes/NXdetector.nxdl.xml b/base_classes/NXdetector.nxdl.xml index c490e746b..69ba006a4 100644 --- a/base_classes/NXdetector.nxdl.xml +++ b/base_classes/NXdetector.nxdl.xml @@ -710,10 +710,19 @@ meant to document the gain setting of the detector during data collection, for detectors with multiple available gain settings. - Examples of gain settings include: standard, fast, auto, high, - medium, low, mixed high/medium, and mixed medium/low. Developers are - encouraged to use one of these terms, or to submit additional terms - to add to the list. + Examples of gain settings include: + + * ``standard`` + * ``fast`` + * ``auto`` + * ``high`` + * ``medium`` + * ``low`` + * ``mixed high to medium`` + * ``mixed medium to low``. + + Developers are encouraged to use one of these terms, or to submit + additional terms to add to the list. From c8fc32682b6a0bc19adc58719e339efe980ed08f Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Mon, 13 Jun 2022 09:37:04 -0500 Subject: [PATCH 5/6] DOC #896 remove period here --- applications/NXmx.nxdl.xml | 2 +- base_classes/NXdetector.nxdl.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/applications/NXmx.nxdl.xml b/applications/NXmx.nxdl.xml index e631ed66e..320b20ac9 100644 --- a/applications/NXmx.nxdl.xml +++ b/applications/NXmx.nxdl.xml @@ -667,7 +667,7 @@ * ``medium`` * ``low`` * ``mixed high to medium`` - * ``mixed medium to low``. + * ``mixed medium to low`` Developers are encouraged to use one of these terms, or to submit additional terms to add to the list. diff --git a/base_classes/NXdetector.nxdl.xml b/base_classes/NXdetector.nxdl.xml index 69ba006a4..2894228ac 100644 --- a/base_classes/NXdetector.nxdl.xml +++ b/base_classes/NXdetector.nxdl.xml @@ -719,7 +719,7 @@ * ``medium`` * ``low`` * ``mixed high to medium`` - * ``mixed medium to low``. + * ``mixed medium to low`` Developers are encouraged to use one of these terms, or to submit additional terms to add to the list. From c5f714734975b94ae3841487b302e39aa3e1db61 Mon Sep 17 00:00:00 2001 From: Pete R Jemian Date: Mon, 13 Jun 2022 09:43:23 -0500 Subject: [PATCH 6/6] DOC #894 additional from merge conflict --- applications/NXmx.nxdl.xml | 1710 ++++++++++++++++++------------------ 1 file changed, 864 insertions(+), 846 deletions(-) diff --git a/applications/NXmx.nxdl.xml b/applications/NXmx.nxdl.xml index 2d062106f..3ba4dac72 100644 --- a/applications/NXmx.nxdl.xml +++ b/applications/NXmx.nxdl.xml @@ -22,850 +22,868 @@ # For further information, see http://www.nexusformat.org --> - - - - These symbols will be used below to coordinate datasets - with the same shape. Most MX x-ray detectors will produce - two-dimensional images. Some will produce three-dimensional - images, using one of the indices to select a detector module. - - - Rank of the ``data`` field - - - Number of scan points - - - Number of detector pixels in the slowest direction - - - Number of detector pixels in the second slowest direction - - - Number of detector pixels in the third slowest direction - - - Number of channels in the incident beam spectrum, if known - - - - An array of the hierarchical levels of the parents of detector - elements or groupings of detector elements. - A top-level element or grouping has parent level -1. - - - - - - functional application definition for macromolecular crystallography - - - - - - Note, it is recommended that ``file_name`` and ``file_time`` are included - as attributes at the root of a file that includes :ref:`NXmx`. See - :ref:`NXroot`. - - - - - Describes the version of the NXmx definition used to write this data. - This must be a text (not numerical) representation. Such as:: - - @version="1.0" - - - - - - - - - - - ISO 8601 time/date of the first data point collected in UTC, - using the Z suffix to avoid confusion with local time. - Note that the time zone of the beamline should be provided in - NXentry/NXinstrument/time_zone. - - - - - - ISO 8601 time/date of the last data point collected in UTC, - using the Z suffix to avoid confusion with local time. - Note that the time zone of the beamline should be provided in - NXentry/NXinstrument/time_zone. This field should only be - filled when the value is accurately observed. If the data - collection aborts or otherwise prevents accurate recording of - the end_time, this field should be omitted. - - - - - - ISO 8601 time/date of the last data point collected in UTC, - using the Z suffix to avoid confusion with local time. - Note that the time zone of the beamline should be provided in - NXentry/NXinstrument/time_zone. This field may be filled - with a value estimated before an observed value is available. - - - - - NeXus NXDL schema to which this file conforms - - - - - - - - - - For a dimension-2 detector, the rank of the data array will be 3. - For a dimension-3 detector, the rank of the data array will be 4. - This allows for the introduction of the frame number as the - first index. - - - - - - - - - - - - - Descriptive name of sample - - - - - - This is a requirement to describe for any scan experiment. - - The axis on which the sample position depends may be stored - anywhere, but is normally stored in the NXtransformations - group within the NXsample group. - - If there is no goniometer, e.g. with a jet, depends_on - should be set to "." - - - - - - This is the recommended location for sample goniometer - and other related axes. - - This is a requirement to describe for any scan experiment. - The reason it is optional is mainly to accommodate XFEL - single shot exposures. - - Use of the depends_on field and the NXtransformations group is - strongly recommended. As noted above this should be an absolute - requirement to have for any scan experiment. - - The reason it is optional is mainly to accommodate XFEL - single shot exposures. - - - - - - - - - - - - - Name of instrument. Consistency with the controlled - vocabulary beamline naming in - https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_beamline.html - and - https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.type.html - is highly recommended. - - - Short name for instrument, perhaps the acronym. - - - - - - ISO 8601 time_zone offset from UTC. - - - - - - - - - - Optional logical grouping of detectors. - - Each detector is represented as an NXdetector - with its own detector data array. Each detector data array - may be further decomposed into array sections by use of - NXdetector_module groups. Detectors can be grouped logically - together using NXdetector_group. Groups can be further grouped - hierarchically in a single NXdetector_group (for example, if - there are multiple detectors at an endstation or multiple - endstations at a facility). Alternatively, multiple - NXdetector_groups can be provided. - - The groups are defined hierarchically, with names given - in the group_names field, unique identifying indices given - in the field group_index, and the level in the hierarchy - given in the group_parent field. For example if an x-ray - detector group, DET, consists of four detectors in a - rectangular array:: - - DTL DTR - DLL DLR - - We could have:: - - group_names: ["DET", "DTL", "DTR", "DLL", "DLR"] - group_index: [1, 2, 3, 4, 5] - group_parent: [-1, 1, 1, 1, 1] - - - - - - An array of the names of the detectors or the names of - hierarchical groupings of detectors. - - - - - - An array of unique identifiers for detectors or groupings - of detectors. - - Each ID is a unique ID for the corresponding detector or group - named in the field group_names. The IDs are positive integers - starting with 1. - - - - - - - An array of the hierarchical levels of the parents of detectors - or groupings of detectors. - - A top-level grouping has parent level -1. - - - - - - - Normally the detector group will have the name ``detector``. - However, in the case of multiple detectors, each detector - needs a uniquely named NXdetector. - - - - - NeXus path to the detector positioner axis that most directly - supports the detector. In the case of a single-module - detector, the detector axis chain may start here. - - - - - - Location for axes (transformations) to do with the - detector. In the case of a single-module detector, the - axes of the detector axis chain may be stored here. - - - - - - Suggested container for detailed non-standard detector - information like corrections applied automatically or - performance settings. - - - - - - For a dimension-2 detector, the rank of the data array will be 3. - For a dimension-3 detector, the rank of the data array will be 4. - This allows for the introduction of the frame number as the - first index. - - - - - - - - - - - - name/manufacturer/model/etc. information. - - - - - - For a time-of-flight detector this is the scaling - factor to convert from the numeric value reported to - the flight time for a given measurement. - - - - - - Many detectors consist of multiple smaller modules that are - operated in sync and store their data in a common dataset. - To allow consistent parsing of the experimental geometry, - this application definiton requires all detectors to - define a detector module, even if there is only one. - - This group specifies the hyperslab of data in the data - array associated with the detector that contains the - data for this module. If the module is associated with - a full data array, rather than with a hyperslab within - a larger array, then a single module should be defined, - spanning the entire array. - - - - A dimension-2 or dimension-3 field which gives the indices - of the origin of the hyperslab of data for this module in the - main area detector image in the parent NXdetector module. - - The data_origin is 0-based. - - The frame number dimension (nP) is omitted. Thus the - data_origin field for a dimension-2 dataset with indices (nP, i, j) - will be an array with indices (i, j), and for a dimension-3 - dataset with indices (nP, i, j, k) will be an array with indices - (i, j, k). - - The :ref:`order <Design-ArrayStorageOrder>` of indices (i, j - or i, j, k) is slow to fast. - - - - - Two or three values for the size of the module in pixels in - each direction. Dimensionality and order of indices is the - same as for data_origin. - - - - - Two or three values for the stride of the module in pixels in - each direction. By default the stride is [1,1] or [1,1,1], - and this is the most likely case. This optional field is - included for completeness. - - - - - - Offset of the module in regards to the origin of the detector in an - arbitrary direction. - - - - - - - - - - - - - - - - Values along the direction of :ref:`fastest varying <Design-ArrayStorageOrder>` - pixel direction. The direction itself is given through the vector - attribute. - - - - - - - - - - - - - - - - Values along the direction of :ref:`slowest varying <Design-ArrayStorageOrder>` - pixel direction. The direction itself is given through the vector - attribute. - - - - - - - - - - - - - - - - - - Distance from the sample to the beam center. - Normally this value is for guidance only, the proper - geometry can be found following the depends_on axis chain, - But in appropriate cases where the dectector distance - to the sample is observable independent of the axis - chain, that may take precedence over the axis chain - calculation. - - - - - - Boolean to indicate if the distance is a derived, rather than - a primary observation. If distance_derived true or is not specified, - the distance is assumed to be derived from delector axis - specifications. - - - - - - Detector dead time. - - - - - - Elapsed actual counting time. - - - - - - Boolean to indicate if the distance is a derived, rather than - a primary observation. If true or not provided, that value of - beam_center_derived is assumed to be true. - - - - - - - - This is the x position where the direct beam would hit the - detector. This is a length and can be outside of the actual - detector. The length can be in physical units or pixels as - documented by the units attribute. Normally, this should - be derived from the axis chain, but the direct specification - may take precedence if it is not a derived quantity. - - - - - - This is the y position where the direct beam would hit the - detector. This is a length and can be outside of the actual - detector. The length can be in physical units or pixels as - documented by the units attribute. Normally, this should - be derived from the axis chain, but the direct specification - may take precedence if it is not a derived quantity. - - - - - - True when the angular calibration has been applied in the - electronics, false otherwise. - - - - - Angular calibration data. - - - - - - - - - - True when the flat field correction has been applied in the - electronics, false otherwise. - - - - - - Flat field correction data. If provided, it is recommended - that it be compressed. - - - - - - - - - - - - *** Deprecated form. Use plural form *** - Errors of the flat field correction data. If provided, it is recommended - that it be compressed. - - - - - - - - - - - Errors of the flat field correction data. If provided, it is recommended - that it be compressed. - - - - - - - - - - - True when the pixel mask correction has been applied in the - electronics, false otherwise. - - - - - - The 32-bit pixel mask for the detector. Can be either one mask - for the whole dataset (i.e. an array with indices i, j) or - each frame can have its own mask (in which case it would be - an array with indices nP, i, j). - - Contains a bit field for each pixel to signal dead, - blind, high or otherwise unwanted or undesirable pixels. - They have the following meaning: - - * bit 0: gap (pixel with no sensor) - * bit 1: dead - * bit 2: under-responding - * bit 3: over-responding - * bit 4: noisy - * bit 5: -undefined- - * bit 6: pixel is part of a cluster of problematic pixels (bit set in addition to others) - * bit 7: -undefined- - * bit 8: user defined mask (e.g. around beamstop) - * bits 9-30: -undefined- - * bit 31: virtual pixel (corner pixel with interpolated value) - - Normal data analysis software would not take pixels into account - when a bit in (mask & 0x0000FFFF) is set. Tag bit in the upper - two bytes would indicate special pixel properties that normally - would not be a sole reason to reject the intensity value (unless - lower bits are set. - - If the full bit depths is not required, providing a - mask with fewer bits is permissible. - - If needed, additional pixel masks can be specified by - including additional entries named pixel_mask_N, where - N is an integer. For example, a general bad pixel mask - could be specified in pixel_mask that indicates noisy - and dead pixels, and an additional pixel mask from - experiment-specific shadowing could be specified in - pixel_mask_2. The cumulative mask is the bitwise OR - of pixel_mask and any pixel_mask_N entries. - - If provided, it is recommended that it be compressed. - - - - - - - - - True when a count-rate correction has already been applied in - the data recorded here, false otherwise. - - - - - - How many bits the electronics record per pixel. - - - - - - Time it takes to read the detector (typically milliseconds). - This is important to know for time resolved experiments. - - - - - - This is time for each frame. This is exposure_time + readout - time. - - - - - - The gain setting of the detector. This influences background. - - - - - - The value at which the detector goes into saturation. - Data above this value is known to be invalid. - - For example, given a saturation_value and an underload_value, - the valid pixels are those less than or equal to the - saturation_value and greater than or equal to the underload_value. - - - - - - The lowest value at which pixels for this detector - would be reasonably be measured. - - For example, given a saturation_value and an underload_value, - the valid pixels are those less than or equal to the - saturation_value and greater than or equal to the underload_value. - - - - - - At times, radiation is not directly sensed by the detector. - Rather, the detector might sense the output from some - converter like a scintillator. - This is the name of this converter material. - - - - - - At times, radiation is not directly sensed by the detector. - Rather, the detector might sense the output from some - converter like a scintillator. This is the thickness of this - converter material. - - - - - - Single photon counter detectors can be adjusted for a certain - energy range in which they work optimally. This is the energy - setting for this. If the detector supports multiple thresholds, - this is an array. - - - - - - Description of type such as scintillator, - ccd, pixel, image - plate, CMOS, ... - - - - - - - In the case of a monchromatic beam this is the scalar - wavelength. - - Several other use cases are permitted, depending on the - presence or absence of other incident_wavelength_X - fields. - - In the case of a polychromatic beam this is an array of - length **m** of wavelengths, with the relative weights - in ``incident_wavelength_weights``. - - In the case of a monochromatic beam that varies shot- - to-shot, this is an array of wavelengths, one for each - recorded shot. Here, ``incident_wavelength_weights`` and - incident_wavelength_spread are not set. - - In the case of a polychromatic beam that varies shot-to- - shot, this is an array of length **m** with the relative - weights in ``incident_wavelength_weights`` as a 2D array. - - In the case of a polychromatic beam that varies shot-to- - shot and where the channels also vary, this is a 2D array - of dimensions **nP** by **m** (slow to fast) with the - relative weights in ``incident_wavelength_weights`` as a 2D - array. - - Note, :ref:`variants <Design-Variants>` are a good way - to represent several of these use cases in a single dataset, - e.g. if a calibrated, single-value wavelength value is - available along with the original spectrum from which it - was calibrated. - - - - - - In the case of a polychromatic beam this is an array of - length **m** of the relative weights of the corresponding - wavelengths in incident_wavelength. - - In the case of a polychromatic beam that varies shot-to- - shot, this is a 2D array of dimensions **nP** by **m** - (slow to fast) of the relative weights of the - corresponding wavelengths in incident_wavelength. - - - - - In the case of a polychromatic beam this is an array of - length **m** of the relative weights of the corresponding - wavelengths in ``incident_wavelength``. - - In the case of a polychromatic beam that varies shot-to- - shot, this is a 2D array of dimensions **np** by **m** - (slow to fast) of the relative weights of the - corresponding wavelengths in ``incident_wavelength``. - - - - - - The wavelength spread FWHM for the corresponding - wavelength(s) in incident_wavelength. - - In the case of shot-to-shot variation in the wavelength - spread, this is a 2D array of dimension **nP** by - **m** (slow to fast) of the spreads of the - corresponding wavelengths in incident_wavelength. - - - - - - - - Flux density incident on beam plane area in photons - per second per unit area. - - In the case of a beam that varies in flux shot-to-shot, - this is an array of values, one for each recorded shot. - - - - - - Flux incident on beam plane in photons per second. - - In the case of a beam that varies in total flux shot-to-shot, - this is an array of values, one for each recorded shot. - - - - - - Two-element array of FWHM (if Gaussian or Airy function) or - diameters (if top hat) or widths (if rectangular) of the beam - in the order x, y - - - - - - - - - The beam profile, Gaussian, Airy function, top-hat or - rectangular. The profile is given in the plane of - incidence of the beam on the sample. - - - - - - - - - - - - - - - - - - - - - - The neutron or x-ray storage ring/facility. Note, the NXsource base class - has many more fields available, but at present we only require the name. - - - - Name of source. Consistency with the naming in - https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_site.html - controlled vocabulary is highly recommended. - - - short name for source, perhaps the acronym - - - - + category="application" + xmlns="http://definition.nexusformat.org/nxdl/3.1" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd" + > + + + + These symbols will be used below to coordinate datasets + with the same shape. Most MX x-ray detectors will produce + two-dimensional images. Some will produce three-dimensional + images, using one of the indices to select a detector module. + + + Rank of the ``data`` field + + + Number of scan points + + + Number of detector pixels in the slowest direction + + + Number of detector pixels in the second slowest direction + + + Number of detector pixels in the third slowest direction + + + Number of channels in the incident beam spectrum, if known + + + + An array of the hierarchical levels of the parents of detector + elements or groupings of detector elements. + A top-level element or grouping has parent level -1. + + + + + + functional application definition for macromolecular crystallography + + + + + + Note, it is recommended that ``file_name`` and ``file_time`` are included + as attributes at the root of a file that includes :ref:`NXmx`. See + :ref:`NXroot`. + + + + + Describes the version of the NXmx definition used to write this data. + This must be a text (not numerical) representation. Such as:: + + @version="1.0" + + + + + + + + + + + ISO 8601 time/date of the first data point collected in UTC, + using the Z suffix to avoid confusion with local time. + Note that the time zone of the beamline should be provided in + NXentry/NXinstrument/time_zone. + + + + + + ISO 8601 time/date of the last data point collected in UTC, + using the Z suffix to avoid confusion with local time. + Note that the time zone of the beamline should be provided in + NXentry/NXinstrument/time_zone. This field should only be + filled when the value is accurately observed. If the data + collection aborts or otherwise prevents accurate recording of + the end_time, this field should be omitted. + + + + + + ISO 8601 time/date of the last data point collected in UTC, + using the Z suffix to avoid confusion with local time. + Note that the time zone of the beamline should be provided in + NXentry/NXinstrument/time_zone. This field may be filled + with a value estimated before an observed value is available. + + + + + NeXus NXDL schema to which this file conforms + + + + + + + + + + For a dimension-2 detector, the rank of the data array will be 3. + For a dimension-3 detector, the rank of the data array will be 4. + This allows for the introduction of the frame number as the + first index. + + + + + + + + + + + + + Descriptive name of sample + + + + + + This is a requirement to describe for any scan experiment. + + The axis on which the sample position depends may be stored + anywhere, but is normally stored in the NXtransformations + group within the NXsample group. + + If there is no goniometer, e.g. with a jet, depends_on + should be set to "." + + + + + + This is the recommended location for sample goniometer + and other related axes. + + This is a requirement to describe for any scan experiment. + The reason it is optional is mainly to accommodate XFEL + single shot exposures. + + Use of the depends_on field and the NXtransformations group is + strongly recommended. As noted above this should be an absolute + requirement to have for any scan experiment. + + The reason it is optional is mainly to accommodate XFEL + single shot exposures. + + + + + + + + + + + + + Name of instrument. Consistency with the controlled + vocabulary beamline naming in + https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_beamline.html + and + https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.type.html + is highly recommended. + + + Short name for instrument, perhaps the acronym. + + + + + + ISO 8601 time_zone offset from UTC. + + + + + + + + + + Optional logical grouping of detectors. + + Each detector is represented as an NXdetector + with its own detector data array. Each detector data array + may be further decomposed into array sections by use of + NXdetector_module groups. Detectors can be grouped logically + together using NXdetector_group. Groups can be further grouped + hierarchically in a single NXdetector_group (for example, if + there are multiple detectors at an endstation or multiple + endstations at a facility). Alternatively, multiple + NXdetector_groups can be provided. + + The groups are defined hierarchically, with names given + in the group_names field, unique identifying indices given + in the field group_index, and the level in the hierarchy + given in the group_parent field. For example if an x-ray + detector group, DET, consists of four detectors in a + rectangular array:: + + DTL DTR + DLL DLR + + We could have:: + + group_names: ["DET", "DTL", "DTR", "DLL", "DLR"] + group_index: [1, 2, 3, 4, 5] + group_parent: [-1, 1, 1, 1, 1] + + + + + + An array of the names of the detectors or the names of + hierarchical groupings of detectors. + + + + + + An array of unique identifiers for detectors or groupings + of detectors. + + Each ID is a unique ID for the corresponding detector or group + named in the field group_names. The IDs are positive integers + starting with 1. + + + + + + + An array of the hierarchical levels of the parents of detectors + or groupings of detectors. + + A top-level grouping has parent level -1. + + + + + + + Normally the detector group will have the name ``detector``. + However, in the case of multiple detectors, each detector + needs a uniquely named NXdetector. + + + + + NeXus path to the detector positioner axis that most directly + supports the detector. In the case of a single-module + detector, the detector axis chain may start here. + + + + + + Location for axes (transformations) to do with the + detector. In the case of a single-module detector, the + axes of the detector axis chain may be stored here. + + + + + + Suggested container for detailed non-standard detector + information like corrections applied automatically or + performance settings. + + + + + + For a dimension-2 detector, the rank of the data array will be 3. + For a dimension-3 detector, the rank of the data array will be 4. + This allows for the introduction of the frame number as the + first index. + + + + + + + + + + + + name/manufacturer/model/etc. information. + + + + + + For a time-of-flight detector this is the scaling + factor to convert from the numeric value reported to + the flight time for a given measurement. + + + + + + Many detectors consist of multiple smaller modules that are + operated in sync and store their data in a common dataset. + To allow consistent parsing of the experimental geometry, + this application definiton requires all detectors to + define a detector module, even if there is only one. + + This group specifies the hyperslab of data in the data + array associated with the detector that contains the + data for this module. If the module is associated with + a full data array, rather than with a hyperslab within + a larger array, then a single module should be defined, + spanning the entire array. + + + + A dimension-2 or dimension-3 field which gives the indices + of the origin of the hyperslab of data for this module in the + main area detector image in the parent NXdetector module. + + The data_origin is 0-based. + + The frame number dimension (nP) is omitted. Thus the + data_origin field for a dimension-2 dataset with indices (nP, i, j) + will be an array with indices (i, j), and for a dimension-3 + dataset with indices (nP, i, j, k) will be an array with indices + (i, j, k). + + The :ref:`order <Design-ArrayStorageOrder>` of indices (i, j + or i, j, k) is slow to fast. + + + + + Two or three values for the size of the module in pixels in + each direction. Dimensionality and order of indices is the + same as for data_origin. + + + + + Two or three values for the stride of the module in pixels in + each direction. By default the stride is [1,1] or [1,1,1], + and this is the most likely case. This optional field is + included for completeness. + + + + + + Offset of the module in regards to the origin of the detector in an + arbitrary direction. + + + + + + + + + + + + + + + + Values along the direction of :ref:`fastest varying <Design-ArrayStorageOrder>` + pixel direction. The direction itself is given through the vector + attribute. + + + + + + + + + + + + + + + + Values along the direction of :ref:`slowest varying <Design-ArrayStorageOrder>` + pixel direction. The direction itself is given through the vector + attribute. + + + + + + + + + + + + + + + + + + Distance from the sample to the beam center. + Normally this value is for guidance only, the proper + geometry can be found following the depends_on axis chain, + But in appropriate cases where the dectector distance + to the sample is observable independent of the axis + chain, that may take precedence over the axis chain + calculation. + + + + + + Boolean to indicate if the distance is a derived, rather than + a primary observation. If distance_derived true or is not specified, + the distance is assumed to be derived from delector axis + specifications. + + + + + + Detector dead time. + + + + + + Elapsed actual counting time. + + + + + + Boolean to indicate if the distance is a derived, rather than + a primary observation. If true or not provided, that value of + beam_center_derived is assumed to be true. + + + + + + + + This is the x position where the direct beam would hit the + detector. This is a length and can be outside of the actual + detector. The length can be in physical units or pixels as + documented by the units attribute. Normally, this should + be derived from the axis chain, but the direct specification + may take precedence if it is not a derived quantity. + + + + + + This is the y position where the direct beam would hit the + detector. This is a length and can be outside of the actual + detector. The length can be in physical units or pixels as + documented by the units attribute. Normally, this should + be derived from the axis chain, but the direct specification + may take precedence if it is not a derived quantity. + + + + + + True when the angular calibration has been applied in the + electronics, false otherwise. + + + + + Angular calibration data. + + + + + + + + + + True when the flat field correction has been applied in the + electronics, false otherwise. + + + + + + Flat field correction data. If provided, it is recommended + that it be compressed. + + + + + + + + + + + + *** Deprecated form. Use plural form *** + Errors of the flat field correction data. If provided, it is recommended + that it be compressed. + + + + + + + + + + + Errors of the flat field correction data. If provided, it is recommended + that it be compressed. + + + + + + + + + + + True when the pixel mask correction has been applied in the + electronics, false otherwise. + + + + + + The 32-bit pixel mask for the detector. Can be either one mask + for the whole dataset (i.e. an array with indices i, j) or + each frame can have its own mask (in which case it would be + an array with indices nP, i, j). + + Contains a bit field for each pixel to signal dead, + blind, high or otherwise unwanted or undesirable pixels. + They have the following meaning: + + * bit 0: gap (pixel with no sensor) + * bit 1: dead + * bit 2: under-responding + * bit 3: over-responding + * bit 4: noisy + * bit 5: -undefined- + * bit 6: pixel is part of a cluster of problematic pixels (bit set in addition to others) + * bit 7: -undefined- + * bit 8: user defined mask (e.g. around beamstop) + * bits 9-30: -undefined- + * bit 31: virtual pixel (corner pixel with interpolated value) + + Normal data analysis software would not take pixels into account + when a bit in (mask & 0x0000FFFF) is set. Tag bit in the upper + two bytes would indicate special pixel properties that normally + would not be a sole reason to reject the intensity value (unless + lower bits are set. + + If the full bit depths is not required, providing a + mask with fewer bits is permissible. + + If needed, additional pixel masks can be specified by + including additional entries named pixel_mask_N, where + N is an integer. For example, a general bad pixel mask + could be specified in pixel_mask that indicates noisy + and dead pixels, and an additional pixel mask from + experiment-specific shadowing could be specified in + pixel_mask_2. The cumulative mask is the bitwise OR + of pixel_mask and any pixel_mask_N entries. + + If provided, it is recommended that it be compressed. + + + + + + + + + True when a count-rate correction has already been applied in + the data recorded here, false otherwise. + + + + + + How many bits the electronics record per pixel. + + + + + + Time it takes to read the detector (typically milliseconds). + This is important to know for time resolved experiments. + + + + + + This is time for each frame. This is exposure_time + readout + time. + + + + + + The gain setting of the detector. This influences + background. This is a detector-specific value meant + to document the gain setting of the detector during + data collection, for detectors with multiple + available gain settings. + + Examples of gain settings include: + + * ``standard`` + * ``fast`` + * ``auto`` + * ``high`` + * ``medium`` + * ``low`` + * ``mixed high to medium`` + * ``mixed medium to low`` + + Developers are encouraged to use one of these terms, or to submit + additional terms to add to the list. + + + + + + The value at which the detector goes into saturation. + Data above this value is known to be invalid. + + For example, given a saturation_value and an underload_value, + the valid pixels are those less than or equal to the + saturation_value and greater than or equal to the underload_value. + + + + + + The lowest value at which pixels for this detector + would be reasonably be measured. + + For example, given a saturation_value and an underload_value, + the valid pixels are those less than or equal to the + saturation_value and greater than or equal to the underload_value. + + + + + + At times, radiation is not directly sensed by the detector. + Rather, the detector might sense the output from some + converter like a scintillator. + This is the name of this converter material. + + + + + + At times, radiation is not directly sensed by the detector. + Rather, the detector might sense the output from some + converter like a scintillator. This is the thickness of this + converter material. + + + + + + Single photon counter detectors can be adjusted for a certain + energy range in which they work optimally. This is the energy + setting for this. If the detector supports multiple thresholds, + this is an array. + + + + + + Description of type such as scintillator, + ccd, pixel, image + plate, CMOS, ... + + + + + + + In the case of a monchromatic beam this is the scalar + wavelength. + + Several other use cases are permitted, depending on the + presence or absence of other incident_wavelength_X + fields. + + In the case of a polychromatic beam this is an array of + length **m** of wavelengths, with the relative weights + in ``incident_wavelength_weights``. + + In the case of a monochromatic beam that varies shot- + to-shot, this is an array of wavelengths, one for each + recorded shot. Here, ``incident_wavelength_weights`` and + incident_wavelength_spread are not set. + + In the case of a polychromatic beam that varies shot-to- + shot, this is an array of length **m** with the relative + weights in ``incident_wavelength_weights`` as a 2D array. + + In the case of a polychromatic beam that varies shot-to- + shot and where the channels also vary, this is a 2D array + of dimensions **nP** by **m** (slow to fast) with the + relative weights in ``incident_wavelength_weights`` as a 2D + array. + + Note, :ref:`variants <Design-Variants>` are a good way + to represent several of these use cases in a single dataset, + e.g. if a calibrated, single-value wavelength value is + available along with the original spectrum from which it + was calibrated. + + + + + + In the case of a polychromatic beam this is an array of + length **m** of the relative weights of the corresponding + wavelengths in incident_wavelength. + + In the case of a polychromatic beam that varies shot-to- + shot, this is a 2D array of dimensions **nP** by **m** + (slow to fast) of the relative weights of the + corresponding wavelengths in incident_wavelength. + + + + + In the case of a polychromatic beam this is an array of + length **m** of the relative weights of the corresponding + wavelengths in ``incident_wavelength``. + + In the case of a polychromatic beam that varies shot-to- + shot, this is a 2D array of dimensions **np** by **m** + (slow to fast) of the relative weights of the + corresponding wavelengths in ``incident_wavelength``. + + + + + + The wavelength spread FWHM for the corresponding + wavelength(s) in incident_wavelength. + + In the case of shot-to-shot variation in the wavelength + spread, this is a 2D array of dimension **nP** by + **m** (slow to fast) of the spreads of the + corresponding wavelengths in incident_wavelength. + + + + + + + + Flux density incident on beam plane area in photons + per second per unit area. + + In the case of a beam that varies in flux shot-to-shot, + this is an array of values, one for each recorded shot. + + + + + + Flux incident on beam plane in photons per second. + + In the case of a beam that varies in total flux shot-to-shot, + this is an array of values, one for each recorded shot. + + + + + + Two-element array of FWHM (if Gaussian or Airy function) or + diameters (if top hat) or widths (if rectangular) of the beam + in the order x, y + + + + + + + + + The beam profile, Gaussian, Airy function, top-hat or + rectangular. The profile is given in the plane of + incidence of the beam on the sample. + + + + + + + + + + + + + + + + + + + + + + The neutron or x-ray storage ring/facility. Note, the NXsource base class + has many more fields available, but at present we only require the name. + + + + Name of source. Consistency with the naming in + https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Items/_diffrn_source.pdbx_synchrotron_site.html + controlled vocabulary is highly recommended. + + + short name for source, perhaps the acronym + + + +