diff --git a/base_classes/NXaperture.nxdl.xml b/base_classes/NXaperture.nxdl.xml index e18b2a5f0e..0fe4ec6d76 100644 --- a/base_classes/NXaperture.nxdl.xml +++ b/base_classes/NXaperture.nxdl.xml @@ -1,9 +1,9 @@ - + - - - A beamline aperture. This group is deprecated, use NXslit instead. - - + + + A beamline aperture. This group is deprecated, use NXslit instead. + + - - NeXus positions components by applying a set of translations and rotations - to apply to the component starting from 0, 0, 0. The order of these operations - is critical and forms what NeXus calls a dependency chain. The depends_on - field defines the path to the top most operation of the dependency chain or the - string "." if located in the origin. Usually these operations are stored in a - NXtransformations group. But NeXus allows them to be stored anywhere. - - The reference point of the aperture is its center in the x and y axis. The reference point on the z axis is the - surface of the aperture pointing towards the source. - - In complex (asymmetic) geometries an NXoff_geometry group can be used to provide an unambiguous reference. - - .. image:: aperture/aperture.png - :width: 40% - + + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the aperture is its center in the x and y axis. The reference point on the z axis is the + surface of the aperture pointing towards the source. + + In complex (asymmetric) geometries an NXoff_geometry group can be used to provide an unambiguous reference. + + .. image:: aperture/aperture.png + :width: 40% + - - This is the group recommended for holding the chain of translation - and rotation operations necessary to position the component within - the instrument. The dependency chain may however traverse similar groups in - other component groups. - + + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + + + + + Stores the raw positions of aperture motors. + - location and shape of aperture - - .. TODO: documentation needs improvement, contributions welcome - - * description of terms is poor and leaves much to interpretation - * Describe what is meant by translation _here_ and ... - * Similar throughout base classes - * Some base classes do this much better - * Such as where is the gap written? - + location and shape of aperture + + .. TODO: documentation needs improvement, contributions welcome + + * description of terms is poor and leaves much to interpretation + * Describe what is meant by translation _here_ and ... + * Similar throughout base classes + * Some base classes do this much better + * Such as where is the gap written? - location and shape of each blade + + location and shape of each blade + - - Absorbing material of the aperture + + + + Absorbing material of the aperture + - Description of aperture + + Description of aperture + + + + + Shape of the aperture. + + + + + + + + + + + + + - describe any additional information in a note* + + + The relevant dimension for the aperture, i.e. slit width, pinhole and iris + diameter + + + + + describe any additional information in a note* + + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. diff --git a/base_classes/NXbeam.nxdl.xml b/base_classes/NXbeam.nxdl.xml index c60e570acb..9bf36c06be 100644 --- a/base_classes/NXbeam.nxdl.xml +++ b/base_classes/NXbeam.nxdl.xml @@ -1,9 +1,9 @@ - + - + - These symbols coordinate datasets with the same shape. + These symbols coordinate datasets with the same shape. - Number of scan points. + + Number of scan points. + - Number of channels in the incident beam spectrum, if known + + Number of channels in the incident beam spectrum, if known + - Number of moments representing beam divergence (x, y, xy, etc.) + + Number of moments representing beam divergence (x, y, xy, etc.) + - Properties of the neutron or X-ray beam at a given location. - - This group is intended to be referenced - by beamline component groups within the :ref:`NXinstrument` group or by the :ref:`NXsample` group. This group is - especially valuable in storing the results of instrument simulations in which it is useful - to specify the beam profile, time distribution etc. at each beamline component. Otherwise, - its most likely use is in the :ref:`NXsample` group in which it defines the results of the neutron - scattering by the sample, e.g., energy transfer, polarizations. Finally, There are cases where the beam is - considered as a beamline component and this group may be defined as a subgroup directly inside - :ref:`NXinstrument`, in which case it is recommended that the position of the beam is specified by an - :ref:`NXtransformations` group, unless the beam is at the origin (which is the sample). - - Note that incident_wavelength and related fields can be a scalar values or arrays, depending on the use case. - To support these use cases, the explicit dimensionality of these fields is not specified, but it can be inferred - by the presense of and shape of accompanying fields, such as incident_wavelength_weights for a polychromatic beam. - + Properties of the neutron or X-ray beam at a given location. + + This group is intended to be referenced + by beamline component groups within the :ref:`NXinstrument` group or by the :ref:`NXsample` group. This group is + especially valuable in storing the results of instrument simulations in which it is useful + to specify the beam profile, time distribution etc. at each beamline component. Otherwise, + its most likely use is in the :ref:`NXsample` group in which it defines the results of the neutron + scattering by the sample, e.g., energy transfer, polarizations. Finally, There are cases where the beam is + considered as a beamline component and this group may be defined as a subgroup directly inside + :ref:`NXinstrument`, in which case it is recommended that the position of the beam is specified by an + :ref:`NXtransformations` group, unless the beam is at the origin (which is the sample). + + Note that incident_wavelength and related fields can be a scalar values or arrays, depending on the use case. + To support these use cases, the explicit dimensionality of these fields is not specified, but it can be inferred + by the presense of and shape of accompanying fields, such as incident_wavelength_weights for a polychromatic beam. + - Distance from sample. Note, it is recommended to use NXtransformations instead. + + Distance from sample. Note, it is recommended to use NXtransformations instead. + - Energy carried by each particle of the beam on entering the beamline component + + Energy carried by each particle of the beam on entering the beamline component. + + In the case of a monochromatic beam this is the scalar energy. + Several other use cases are permitted, depending on the + presence of other incident_energy_X fields. + + * In the case of a polychromatic beam this is an array of length m of energies, with the relative weights in incident_energy_weights. + * In the case of a monochromatic beam that varies shot-to-shot, this is an array of energies, one for each recorded shot. + Here, incident_energy_weights and incident_energy_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_energy_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_energy_weights as a 2D array. + + Note, variants are a good way to represent several of these use cases in a single dataset, + e.g. if a calibrated, single-value energy value is available along with the original spectrum from which it was calibrated. + + + + The energy spread FWHM for the corresponding energy(ies) in incident_energy. In the case of shot-to-shot variation in + the energy spread, this is a 2D array of dimension nP by m + (slow to fast) of the spreads of the corresponding + wavelength in incident_wavelength. + + + + + In the case of a polychromatic beam this is an array of length m of the relative + weights of the corresponding energies in incident_energy. 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 energies in + incident_energy. + + - Energy carried by each particle of the beam on leaving the beamline component + + Energy carried by each particle of the beam on leaving the beamline component + - Change in particle energy caused by the beamline component + + Change in particle energy caused by the beamline component + - In the case of a monochromatic 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. - Wavelength on entering beamline component + In the case of a monochromatic 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. + Wavelength on entering beamline component - 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. + 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. @@ -142,15 +184,15 @@ - Beam crossfire in degrees parallel to the laboratory X axis - - The dimension **c** is a series of moments of that represent - the standard uncertainty (e.s.d.) of the directions of - of the beam. The first and second moments are in the XZ and YZ - planes around the mean source beam direction, respectively. - - Further moments in **c** characterize co-variance terms, so - the next moment is the product of the first two, and so on. + Beam crossfire in degrees parallel to the laboratory X axis + + The dimension **c** is a series of moments of that represent + the standard uncertainty (e.s.d.) of the directions of + of the beam. The first and second moments are in the XZ and YZ + planes around the mean source beam direction, respectively. + + Further moments in **c** characterize co-variance terms, so + the next moment is the product of the first two, and so on. @@ -159,8 +201,8 @@ - Size of the beam entering this component. Note this represents - a rectangular beam aperture, and values represent FWHM + Size of the beam entering this component. Note this represents + a rectangular beam aperture, and values represent FWHM @@ -168,47 +210,90 @@ - Wavelength on leaving beamline component + + Wavelength on leaving beamline component + - Polarization vector on entering beamline component + + Incident polarization as a Stokes vector + on entering beamline component + + + + The units for this observable are not included in the NIAC list. + Responsibility on correct formatting and parsing is handed to the user + by using `NX_ANY`. Correct parsing can still be implemented by using + this attribute. + + | Fill with: + + * The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla). + * The unit unidata name if the unit has a name (Example: farad for capacitance). + * A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and + does not have a name. + + Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2). + Here: SI units are V2/m2. + + - Polarization vector on leaving beamline component + + Polarization as Stokes vector on leaving beamline component + + + + The units for this observable are not included in the NIAC list. + Responsibility on correct formatting and parsing is handed to the user + by using `NX_ANY`. Correct parsing can still be implemented by using + this attribute. + + | Fill with: + + * The unit unidata symbol if the unit has one (Example: T for the unit of magnetic flux density tesla). + * The unit unidata name if the unit has a name (Example: farad for capacitance). + * A string describing the units according to unidata unit operation notation, if the unit is a complex combination of named units and + does not have a name. + + Example: for lightsource brilliance (SI) 1/(s.mm2.mrad2). + Here: SI units are V2/m2. + + Polarization vector on entering beamline component using Stokes notation - + The Stokes parameters are four components labelled I,Q,U,V or S_0,S_1,S_2,S_3. These are defined with the standard Nexus coordinate frame unless it is overridden by an NXtransformations field pointed to by a depends_on attribute. The last component, describing the circular polarization state, is positive for a right-hand circular state - that is the electric field vector rotates clockwise at the sample and over time when observed from the source. - - I (S_0) is the beam intensity (often normalized to 1). Q, U, and V scale + + I (S_0) is the beam intensity (often normalized to 1). Q, U, and V scale linearly with the total degree of polarization, and indicate the relative magnitudes of the pure linear and circular orientation contributions. Q (S_1) is linearly polarized along the x axis (Q > 0) or y axis (Q < 0). U (S_2) is linearly polarized along the x==y axis (U > 0) or the - -x==y axis (U < 0). - + -x==y axis (U < 0). + V (S_3) is circularly polarized. V > 0 when the electric field vector rotates - clockwise at the sample with respect to time when observed from the source; + clockwise at the sample with respect to time when observed from the source; V < 0 indicates the opposite rotation. @@ -227,112 +312,177 @@ - Wavelength spread FWHM of beam leaving this component + + Wavelength spread FWHM of beam leaving this component + - Divergence FWHM of beam leaving this component + + Divergence FWHM of beam leaving this component + - flux incident on beam plane area + + flux incident on beam plane area + + + + Energy of a single pulse at the diagnostic point + + + + + Average power at the diagnostic point + + + + + Incident fluence at the diagnostic point + + + + Here: SI units are 'J/m2', customary 'mJ/cm2'. + + + + + + FWHM duration of the pulses at the diagnostic point + + + + + FROG trace of the pulse. + + + + + + + + + Horizontal axis of a FROG trace, i.e. delay. + + + + + + + + Vertical axis of a FROG trace, i.e. frequency. + + + + + + + + The type of chirp implemented + + + + + Group delay dispersion of the pulse for linear chirp + + - 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. + 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. + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. - - + - The NeXus coordinate system defines the Z axis to be along the nominal beam - direction. This is the same as the McStas coordinate system (see :ref:`Design-CoordinateSystem`). - However, the additional transformations needed to represent an altered beam - direction can be provided using this depends_on field that contains the path - to a NXtransformations group. This could represent redirection of the beam, - or a refined beam direction. + The NeXus coordinate system defines the Z axis to be along the nominal beam + direction. This is the same as the McStas coordinate system (see :ref:`Design-CoordinateSystem`). + However, the additional transformations needed to represent an altered beam + direction can be provided using this depends_on field that contains the path + to a NXtransformations group. This could represent redirection of the beam, + or a refined beam direction. - - Direction (and location) for the beam. The location of the beam can be given by - any point which it passes through as its offset attribute. + Direction (and location) for the beam. The location of the beam can be given by + any point which it passes through as its offset attribute. - + - Direction of beam vector, its value is ignored. If missing, then the beam direction is defined as [0,0,1] - and passes through the origin + Direction of beam vector, its value is ignored. If missing, then the beam direction is defined as [0,0,1] + and passes through the origin - + - Three values that define the direction of beam vector + Three values that define the direction of beam vector - Three values that define the location of a point through which the beam passes + Three values that define the location of a point through which the beam passes - Points to the path to a field defining the location on which this - depends or the string "." for origin. + Points to the path to a field defining the location on which this + depends or the string "." for origin. - + - Direction of normal to reference plane used to measure azimuth relative to the beam, its value is ignored. - This also defines the parallel and perpendicular components of the beam's polarization. - If missing, then the reference plane normal is defined as [0,1,0] and passes through the origin + Direction of normal to reference plane used to measure azimuth relative to the beam, its value is ignored. + This also defines the parallel and perpendicular components of the beam's polarization. + If missing, then the reference plane normal is defined as [0,1,0] and passes through the origin - + - Three values that define the direction of reference plane normal + Three values that define the direction of reference plane normal - Not required as beam direction offset locates the plane + Not required as beam direction offset locates the plane - Points to the path to a field defining the location on which this - depends or the string "." for origin. + Points to the path to a field defining the location on which this + depends or the string "." for origin. diff --git a/base_classes/NXdetector.nxdl.xml b/base_classes/NXdetector.nxdl.xml index a6bb0b8c68..523f0916f1 100644 --- a/base_classes/NXdetector.nxdl.xml +++ b/base_classes/NXdetector.nxdl.xml @@ -1,14 +1,14 @@ - + - - - - - These symbols will be used below to illustrate the coordination of the rank and sizes of datasets and the - preferred ordering of the dimensions. Each of these are optional (so the rank of the datasets - will vary according to the situation) and the general ordering principle is slowest to fastest. - The type of each dimension should follow the order of scan points, detector output (e.g. pixels), - then time-of-flight (i.e. spectroscopy, spectrometry). Note that the output of a detector is not limited - to single values (0D), lists (1D) and images (2), but three or higher dimensional arrays can be produced - by a detector at each trigger. - - - number of scan points (only present in scanning measurements) - number of detector pixels in the first (slowest) direction - number of detector pixels in the second (faster) direction - number of bins in the time-of-flight histogram - - - - A detector, detector bank, or multidetector. - - - - Total time of flight - - - - - - - - - - - - - - - - - - - Total time of flight - - - - - In DAQ clock pulses - - - - - - - Clock frequency in Hz - - - - - - Identifier for detector (pixels) - Can be multidimensional, if needed - - - - - - Data values from the detector. The rank and dimension ordering should follow a principle of - slowest to fastest measurement axes and may be explicitly specified in application definitions. - - Mechanical scanning of objects (e.g. sample position/angle, incident beam energy, etc) tends to be - the slowest part of an experiment and so any such scan axes should be allocated to the first dimensions - of the array. Note that in some cases it may be useful to represent a 2D set of scan points as a single - scan-axis in the data array, especially if the scan pattern doesn't fit a rectangular array nicely. - Repetition of an experiment in a time series tends to be used similar to a slow scan axis - and so will often be in the first dimension of the data array. - - The next fastest axes are typically the readout of the detector. A point detector will not add any dimensions - (as it is just a single value per scan point) to the data array, a strip detector will add one dimension, an - imaging detector will add two dimensions (e.g. X, Y axes) and detectors outputting higher dimensional data - will add the corresponding number of dimensions. Note that the detector dimensions don't necessarily have to - be written in order of the actual readout speeds - the slowest to fastest rule principle is only a guide. - - Finally, detectors that operate in a time-of-flight mode, such as a neutron spectrometer or a silicon drift - detector (used for X-ray fluorescence) tend to have their dimension(s) added to the last dimensions in the data array. - - The type of each dimension should should follow the order of scan points, detector pixels, - then time-of-flight (i.e. spectroscopy, spectrometry). The rank and dimension sizes (see symbol list) - shown here are merely illustrative of coordination between related datasets. - - - - - - - - - - - Title of measurement - - - - Integral of data as check of data integrity - - - - - - - The best estimate of the uncertainty in the data value (array size should match the data field). Where - possible, this should be the standard deviation, which has the same units - as the data. The form data_error is deprecated. - - - - - - - - - - - - - - Offset from the detector center in x-direction. - Can be multidimensional when needed. - - - - - - - - - - - - - - - - - - - - - x-axis offset from detector center - - - - - - Offset from the detector center in the y-direction. - Can be multidimensional when different values are required for each pixel. - - - - - - - - - - - - - - - - - - - - - y-axis offset from detector center - - - - - - - Offset from the detector center in the z-direction. - Can be multidimensional when different values are required for each pixel. - - - - - - - - - - - - - - - - - - - - - y-axis offset from detector center - - - - - - This is the distance to the previous component in the - instrument; most often the sample. The usage depends on the - nature of the detector: Most often it is the distance of the - detector assembly. But there are irregular detectors. In this - case the distance must be specified for each detector pixel. - - Note, it is recommended to use NXtransformations instead. - - - - - - - - - - - - This is the polar angle of the detector towards the previous - component in the instrument; most often the sample. - The usage depends on the - nature of the detector. - Most often it is the polar_angle of the detector assembly. - But there are irregular detectors. - In this - case, the polar_angle must be specified for each detector pixel. - - Note, it is recommended to use NXtransformations instead. - - - - - - - - - - - - This is the azimuthal angle angle of the detector towards - the previous component in the instrument; most often the sample. - The usage depends on the - nature of the detector. - Most often it is the azimuthal_angle of the detector assembly. - But there are irregular detectors. - In this - case, the azimuthal_angle must be specified for each detector pixel. - - Note, it is recommended to use NXtransformations instead. - - - - - - - - - - - name/manufacturer/model/etc. information - - - - Serial number for the detector - - - - Local name for the detector - - - - Position and orientation of detector - - - - Solid angle subtended by the detector at the sample - - - - - - - - - - Size of each detector pixel. If it is scalar all pixels are the same size. - - - - - - - - - - Size of each detector pixel. If it is scalar all pixels are the same size - - - - - - - - - Detector dead time - - - - - - - - - - Detector gas pressure - - - - - - - - - maximum drift space dimension - - - - Crate number of detector - - - - - - - - Equivalent local term - - - - - Slot number of detector - - - - - - - - Equivalent local term - - - - - Input number of detector - - - - - - - - Equivalent local term - - - - - - Description of type such as He3 gas cylinder, He3 PSD, scintillator, - fission chamber, proportion counter, ion chamber, ccd, pixel, image plate, - CMOS, ... - - - - - Spectral efficiency of detector with respect to e.g. wavelength - - - - - - - - - - - - - - - - - - - - - - - - efficiency of the detector - - - - - - - - - - This field can be two things: - - #. For a pixel detector it provides the nominal wavelength - for which the detector has been calibrated. - - #. For other detectors this field has to be seen together with - the efficiency field above. - For some detectors, the efficiency is wavelength dependent. - Thus this field provides the wavelength axis for the efficiency field. - In this use case, the efficiency and wavelength arrays must - have the same dimensionality. - - - - - - - - - - - - Real-time of the exposure (use this if exposure time varies for - each array element, otherwise use ``count_time`` field). - - Most often there is a single real time value that is constant across - an entire image frame. In such cases, only a 1-D array is needed. - But there are detectors in which the real time - changes per pixel. In that case, more than one dimension is needed. Therefore - the rank of this field should be less than or equal to (detector rank + 1). - - - - - - - - - - start time for each frame, with the ``start`` attribute as absolute reference - - - - - - - stop time for each frame, with the ``start`` attribute as absolute reference - - - - - - - - - date of last calibration (geometry and/or efficiency) measurements - - - - - - summary of conversion of array data to pixels (e.g. polynomial - approximations) and location of details of the calibrations - - - - - How the detector is represented - - - - - - - - - - Elapsed actual counting time - - - - - - - - - - - Use this group to provide other data related to this NXdetector group. - - - - - - In order to properly sort the order of the images taken in (for - example) a tomography experiment, a sequence number is stored with each - image. - - - - - - - - - - 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. - - - - - - 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. - - - - - - This is the start number of the first frame of a scan. In protein crystallography measurements one - often scans a couple of frames on a give sample, then does something else, - then returns to the same sample and scans some more frames. Each time with - a new data file. This number helps concatenating such measurements. - - - - - The diameter of a cylindrical detector - - - - The acquisition mode of the detector. - - - - - - - - - - - - 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. - - - - - - - - Errors of the flat field correction data. - The form flatfield_error is deprecated. - - - - - - - - - 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 or high or otherwise unwanted or undesirable pixels. - They have the following meaning: - - .. can't make a table here, a bullet list will have to do for now - - * 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. - - - - - - - - - - This field allow to distinguish different types of exposure to the same detector "data" field. - Some techniques require frequent (re-)calibration inbetween measuremnts and this way of - recording the different measurements preserves the chronological order with is important for - correct processing. - - This is used for example in tomography (`:ref:`NXtomo`) sample projections, - dark and flat images, a magic number is recorded per frame. - - The key is as follows: - - * projection (sample) = 0 - * flat field = 1 - * dark field = 2 - * invalid = 3 - * background (no sample, but buffer where applicable) = 4 - - In cases where the data is of type :ref:`NXlog` this can also be an NXlog. - - - - - - - - - Counting detectors usually are not able to measure all incoming particles, - especially at higher count-rates. Count-rate correction is applied to - account for these errors. - - True when count-rate correction has been applied, false otherwise. - - - - - The countrate_correction_lookup_table defines the LUT used for count-rate - correction. It maps a measured count :math:`c` to its corrected value - :math:`countrate\_correction\_lookup\_table[c]`. - - :math:`m` denotes the length of the table. - - - - - - - - True when virtual pixel interpolation has been applied, false otherwise. - - When virtual pixel interpolation is applied, values of some pixels may - contain interpolated values. For example, to account for space between - readout chips on a module, physical pixels on edges and corners between - chips may have larger sensor areas and counts may be distributed between - their logical pixels. - - - - - How many bits the electronics reads per pixel. - With CCD's and single photon counting detectors, - this must not align with traditional integer sizes. - This can be 4, 8, 12, 14, 16, ... - - - - - Time it takes to read the detector (typically milliseconds). - This is important to know for time resolved experiments. - - - - - Time it takes to start exposure after a trigger signal has been received. - This is the reaction time of the detector firmware after receiving the trigger signal - to when the detector starts to acquire the exposure, including any user set delay.. - This is important to know for time resolved experiments. - - - - - User-specified trigger delay. - - - - - Time it takes to start exposure after a trigger signal has been received. - This is the reaction time of the detector hardware after receiving the - trigger signal to when the detector starts to acquire the exposure. - It forms the lower boundary of the trigger_delay_time when the user - does not request an additional delay. - - - - - Time during which no new trigger signal can be accepted. - Typically this is the - trigger_delay_time + exposure_time + readout_time. - 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. - Especially common to CCD detectors, the data - is known to be invalid above this value. - - 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 precise type should match the type of the data. - - - - - The lowest value at which pixels for this detector would be reasonably - measured. The data is known to be invalid below this value. - - 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 precise type should match the type of the data. - - - - - CCD images are sometimes constructed by summing - together multiple short exposures in the - electronics. This reduces background etc. - This is the number of short exposures used to sum - images for an image. - - - - - 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. - - - - - For use in special cases where the data in NXdetector - is represented in several parts, each with a separate geometry. - - - - - - Shape description of each pixel. Use only if all pixels in the detector - are of uniform shape. - + + + + These symbols will be used below to illustrate the coordination of the + rank and sizes of datasets and the preferred ordering of the + dimensions. Each of these are optional (so the rank of the datasets + will vary according to the situation) and the general ordering + principle is slowest to fastest. The type of each dimension should + follow the order of scan points, detector output (e.g. pixels), then + time-of-flight (i.e. spectroscopy, spectrometry). Note that the output + of a detector is not limited to single values (0D), lists (1D) and + images (2), but three or higher dimensional arrays can be produced by + a detector at each trigger. + + + + number of scan points (only present in scanning measurements) + + + + + number of detector pixels in the first (slowest) direction + + + + + number of detector pixels in the second (faster) direction + + + + + number of detector pixels in the third (if necessary, fastest) + direction + + + + + number of bins in the time-of-flight histogram + + + + + A detector, detector bank, or multidetector. + + + + Total time of flight + + + + + + + + + + + + + + + + + Total time of flight + + + + + + In DAQ clock pulses + + + + + + + Clock frequency in Hz + + + + + + Identifier for detector (pixels) + Can be multidimensional, if needed + + + + + Data values from the detector. The rank and dimension ordering should follow a principle of + slowest to fastest measurement axes and may be explicitly specified in application definitions. + + Mechanical scanning of objects (e.g. sample position/angle, incident beam energy, etc) tends to be + the slowest part of an experiment and so any such scan axes should be allocated to the first dimensions + of the array. Note that in some cases it may be useful to represent a 2D set of scan points as a single + scan-axis in the data array, especially if the scan pattern doesn't fit a rectangular array nicely. + Repetition of an experiment in a time series tends to be used similar to a slow scan axis + and so will often be in the first dimension of the data array. + + The next fastest axes are typically the readout of the detector. A point detector will not add any dimensions + (as it is just a single value per scan point) to the data array, a strip detector will add one dimension, an + imaging detector will add two dimensions (e.g. X, Y axes) and detectors outputting higher dimensional data + will add the corresponding number of dimensions. Note that the detector dimensions don't necessarily have to + be written in order of the actual readout speeds - the slowest to fastest rule principle is only a guide. + + Finally, detectors that operate in a time-of-flight mode, such as a neutron spectrometer or a silicon drift + detector (used for X-ray fluorescence) tend to have their dimension(s) added to the last dimensions in the data array. + + The type of each dimension should should follow the order of scan points, detector pixels, + then time-of-flight (i.e. spectroscopy, spectrometry). The rank and dimension sizes (see symbol list) + shown here are merely illustrative of coordination between related datasets. + + + + + + + + + + Title of measurement + + + + + Integral of data as check of data integrity + + + + + + The best estimate of the uncertainty in the data value (array size should match the data field). Where + possible, this should be the standard deviation, which has the same units + as the data. The form data_error is deprecated. + + + + + + + + + + + Offset from the detector center in x-direction. + Can be multidimensional when needed. + + + + + + + + + + + + + + + + + + x-axis offset from detector center + + + + + + Offset from the detector center in the y-direction. + Can be multidimensional when different values are required for each pixel. + + + + + + + + + + + + + + + + + + y-axis offset from detector center + + + + + + Offset from the detector center in the z-direction. + Can be multidimensional when different values are required for each pixel. + + + + + + + + + + + + + + + + + + y-axis offset from detector center + + + + + + This is the distance to the previous component in the + instrument; most often the sample. The usage depends on the + nature of the detector: Most often it is the distance of the + detector assembly. But there are irregular detectors. In this + case the distance must be specified for each detector pixel. + + Note, it is recommended to use NXtransformations instead. + + + + + + + + + + This is the polar angle of the detector towards the previous + component in the instrument; most often the sample. + The usage depends on the + nature of the detector. + Most often it is the polar_angle of the detector assembly. + But there are irregular detectors. + In this + case, the polar_angle must be specified for each detector pixel. + + Note, it is recommended to use NXtransformations instead. + + + + + + + + + + This is the azimuthal angle angle of the detector towards + the previous component in the instrument; most often the sample. + The usage depends on the + nature of the detector. + Most often it is the azimuthal_angle of the detector assembly. + But there are irregular detectors. + In this + case, the azimuthal_angle must be specified for each detector pixel. + + Note, it is recommended to use NXtransformations instead. + + + + + + + + + + name/manufacturer/model/etc. information + + + + + Serial number for the detector + + + + + Local name for the detector + + + + + Position and orientation of detector + + + + + Solid angle subtended by the detector at the sample + + + + + + + + + Size of each detector pixel. If it is scalar all pixels are the same size. + + + + + + + + + Size of each detector pixel. If it is scalar all pixels are the same size + + + + + + + + + Detector dead time + + + + + + + + + + Detector gas pressure + + + + + + + + + maximum drift space dimension + + + + + Crate number of detector + + + + + + + + Equivalent local term + + + + + + Slot number of detector + + + + + + + + Equivalent local term + + + + + + Input number of detector + + + + + + + + Equivalent local term + + + + + + Description of type such as He3 gas cylinder, He3 PSD, scintillator, + fission chamber, proportion counter, ion chamber, ccd, pixel, image plate, + CMOS, ... + + + + + Spectral efficiency of detector with respect to e.g. wavelength + + + + + + + + + + + + + + + + + + + + + + + + + efficiency of the detector + + + + + + + + + + This field can be two things: + + 1. For a pixel detector it provides the nominal wavelength + for which the detector has been calibrated. + + 2. For other detectors this field has to be seen together with + the efficiency field above. + For some detectors, the efficiency is wavelength dependent. + Thus this field provides the wavelength axis for the efficiency field. + In this use case, the efficiency and wavelength arrays must + have the same dimensionality. + + + + + + + + + + + Real-time of the exposure (use this if exposure time varies for + each array element, otherwise use ``count_time`` field). + + Most often there is a single real time value that is constant across + an entire image frame. In such cases, only a 1-D array is needed. + But there are detectors in which the real time + changes per pixel. In that case, more than one dimension is needed. Therefore + the rank of this field should be less than or equal to (detector rank + 1). + + + + + + + + + + start time for each frame, with the ``start`` attribute as absolute reference + + + + + + + + + stop time for each frame, with the ``start`` attribute as absolute reference + + + + + + + + + date of last calibration (geometry and/or efficiency) measurements + + + + + summary of conversion of array data to pixels (e.g. polynomial + approximations) and location of details of the calibrations + - - - Shape description of each pixel. Use only if all pixels in the detector - are of uniform shape and require being described by cylinders. - + + + How the detector is represented + + + + + + + + + + Elapsed actual counting time + + + + + + + + + Use this group to provide other data related to this NXdetector group. + - - - - - Shape description of the whole detector. Use only if pixels in the - detector are not of uniform shape. - + + + In order to properly sort the order of the images taken in (for + example) a tomography experiment, a sequence number is stored with each + image. + + + + + + + + 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. + + + + + 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. + + + + + This is the start number of the first frame of a scan. In protein crystallography measurements one + often scans a couple of frames on a give sample, then does something else, + then returns to the same sample and scans some more frames. Each time with + a new data file. This number helps concatenating such measurements. + + + + + The diameter of a cylindrical detector + + + + + The acquisition mode of the detector. + + + + + + + + + + + + + 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. + + + + + + + + + Errors of the flat field correction data. + The form flatfield_error is deprecated. + + + + + + + + + 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 or high or otherwise unwanted or undesirable pixels. + They have the following meaning: + + .. can't make a table here, a bullet list will have to do for now + + * 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. + + + + + + + + + This field allow to distinguish different types of exposure to the same detector "data" field. + Some techniques require frequent (re-)calibration inbetween measuremnts and this way of + recording the different measurements preserves the chronological order with is important for + correct processing. + + This is used for example in tomography (`:ref:`NXtomo`) sample projections, + dark and flat images, a magic number is recorded per frame. + + The key is as follows: + + * projection (sample) = 0 + * flat field = 1 + * dark field = 2 + * invalid = 3 + * background (no sample, but buffer where applicable) = 4 + + In cases where the data is of type :ref:`NXlog` this can also be an NXlog. + + + + + + + + Counting detectors usually are not able to measure all incoming particles, + especially at higher count-rates. Count-rate correction is applied to + account for these errors. + + True when count-rate correction has been applied, false otherwise. + + + + + The countrate_correction_lookup_table defines the LUT used for count-rate + correction. It maps a measured count :math:`c` to its corrected value + :math:`countrate\_correction\_lookup\_table[c]`. + + :math:`m` denotes the length of the table. + + + + + + + + True when virtual pixel interpolation has been applied, false otherwise. + + When virtual pixel interpolation is applied, values of some pixels may + contain interpolated values. For example, to account for space between + readout chips on a module, physical pixels on edges and corners between + chips may have larger sensor areas and counts may be distributed between + their logical pixels. + + + + + How many bits the electronics reads per pixel. + With CCD's and single photon counting detectors, + this must not align with traditional integer sizes. + This can be 4, 8, 12, 14, 16, ... + + + + + Time it takes to read the detector (typically milliseconds). + This is important to know for time resolved experiments. + + + + + Time it takes to start exposure after a trigger signal has been received. + This is the reaction time of the detector firmware after receiving the trigger signal + to when the detector starts to acquire the exposure, including any user set delay.. + This is important to know for time resolved experiments. + + + + + User-specified trigger delay. + + + + + Time it takes to start exposure after a trigger signal has been received. + This is the reaction time of the detector hardware after receiving the + trigger signal to when the detector starts to acquire the exposure. + It forms the lower boundary of the trigger_delay_time when the user + does not request an additional delay. + + + + + Time during which no new trigger signal can be accepted. + Typically this is the + trigger_delay_time + exposure_time + readout_time. + 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. + Especially common to CCD detectors, the data + is known to be invalid above this value. + + 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 precise type should match the type of the data. + + + + + The lowest value at which pixels for this detector would be reasonably + measured. The data is known to be invalid below this value. + + 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 precise type should match the type of the data. + + + + + CCD images are sometimes constructed by summing + together multiple short exposures in the + electronics. This reduces background etc. + This is the number of short exposures used to sum + images for an image. + + + + + 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. + + + + + For use in special cases where the data in NXdetector + is represented in several parts, each with a separate geometry. + + + + + + Shape description of each pixel. Use only if all pixels in the detector + are of uniform shape. + + + + + Shape description of each pixel. Use only if all pixels in the detector + are of uniform shape and require being described by cylinders. + + + + + + + Shape description of the whole detector. Use only if pixels in the + detector are not of uniform shape. + + + + + Shape description of the whole detector. Use only if pixels in the + detector are not of uniform shape and require being described by cylinders. + + + + + + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + + + + + Type of electron amplifier, MCP, channeltron, etc. + + + + + Description of the detector type, DLD, Phosphor+CCD, CMOS. + + + + + Voltage applied to detector. + + + + + Voltage applied to the amplifier. + + + + + The low voltage of the amplifier migh not be the ground. + + + + + Size of each imaging sensor chip on the detector. + + + + + Number of imaging sensor chips on the detector. + + + + + Physical size of the pixels of the imaging chip on the detector. + + + + + Number of raw active elements in each dimension. Important for swept scans. + + + + + raw data output from the detector + - - - Shape description of the whole detector. Use only if pixels in the - detector are not of uniform shape and require being described by cylinders. - + + + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the detector is the center of the first pixel. + In complex geometries the NXoff_geometry groups can be used to provide an unambiguous reference. + + + + + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. + - - - - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. - - - - - NeXus positions components by applying a set of translations and rotations - to apply to the component starting from 0, 0, 0. The order of these operations - is critical and forms what NeXus calls a dependency chain. The depends_on - field defines the path to the top most operation of the dependency chain or the - string "." if located in the origin. Usually these operations are stored in a - NXtransformations group. But NeXus allows them to be stored anywhere. - - The reference point of the detector is the center of the first pixel. - In complex geometries the NXoff_geometry groups can be used to provide an unambiguous reference. - - - - - This is the group recommended for holding the chain of translation - and rotation operations necessary to position the component within - the instrument. The dependency chain may however traverse similar groups in - other component groups. - - diff --git a/base_classes/NXentry.nxdl.xml b/base_classes/NXentry.nxdl.xml index 2bb4ca533e..e5865bd60c 100755 --- a/base_classes/NXentry.nxdl.xml +++ b/base_classes/NXentry.nxdl.xml @@ -1,10 +1,10 @@ - + - - - - - .. index:: find the default plottable data - .. index:: plotting - .. index:: default attribute value - - Declares which :ref:`NXdata` group contains the data - to be shown by default. - It is used to resolve ambiguity when - one :ref:`NXdata` group exists. - The value :ref:`names <validItemName>` a child group. If that group - itself has a ``default`` attribute, continue this chain until an - :ref:`NXdata` group is reached. - - For more information about how NeXus identifies the default - plottable data, see the - :ref:`Find Plottable Data, v3 <Find-Plottable-Data-v3>` - section. - - - - - (**required**) :ref:`NXentry` describes the measurement. - - The top-level NeXus group which contains all the data and associated - information that comprise a single measurement. - It is mandatory that there is at least one - group of this type in the NeXus file. - - - - The data group - - .. note:: Before the NIAC2016 meeting [#]_, at least one - :ref:`NXdata` group was required in each :ref:`NXentry` group. - At the NIAC2016 meeting, it was decided to make :ref:`NXdata` - an optional group in :ref:`NXentry` groups for data files that - do not use an application definition. - It is recommended strongly that all NeXus data files provide - a NXdata group. - It is permissable to omit the NXdata group only when - defining the default plot is not practical or possible - from the available data. - - For example, neutron event data may not have anything that - makes a useful plot without extensive processing. - - Certain application definitions override this decision and - require an :ref:`NXdata` group - in the :ref:`NXentry` group. The ``minOccurs=0`` attribute - in the application definition will indicate the - :ref:`NXdata` group - is optional, otherwise, it is required. - - .. [#] NIAC2016: - https://www.nexusformat.org/NIAC2016.html, - https://github.com/nexusformat/NIAC/issues/16 - - - - - - - ISIS Muon IDF_Version - - - Extended title for entry - - - - Unique identifier for the experiment, - defined by the facility, - possibly linked to the proposals - - - - Brief summary of the experiment, including key objectives. - - - Description of the full experiment (document in pdf, latex, ...) - - - User or Data Acquisition defined group of NeXus files or NXentry - - - Brief summary of the collection, including grouping criteria. - - - unique identifier for the measurement, defined by the facility. - - - UUID identifier for the measurement. - Version of UUID used - - - - Reserved for future use by NIAC. - - See https://github.com/nexusformat/definitions/issues/382 - - - - - (alternate use: see same field in :ref:`NXsubentry` for preferred) - - Official NeXus NXDL schema to which this entry conforms which must be - the name of the NXDL file (case sensitive without the file extension) - that the NXDL schema is defined in. - - For example the ``definition`` field for a file that conformed to the - *NXarpes.nxdl.xml* definition must contain the string **NXarpes**. - - This field is provided so that :ref:`NXentry` can be the overlay position - in a NeXus data file for an application definition and its - set of groups, fields, and attributes. - - *It is advised* to use :ref:`NXsubentry`, instead, as the overlay position. - - NXDL version number - URL of NXDL file - - - - Local NXDL schema extended from the entry - specified in the ``definition`` field. - This contains any locally-defined, - additional fields in the entry. - - NXDL version number - URL of NXDL file - - - Starting time of measurement - - - Ending time of measurement - - - Duration of measurement - - - - Time transpired actually collecting data i.e. taking out time when collection was - suspended due to e.g. temperature out of range - - - - Such as "2007-3". Some user facilities organize their beam time into run cycles. - - - Name of program used to generate this file - Program version number - configuration of the program - - - - Revision id of the file due to re-calibration, reprocessing, new analysis, new - instrument definition format, ... - - - - - - This is the flightpath before the sample position. This can be determined by a chopper, - by the moderator or the source itself. In other words: it the distance to the component - which gives the T0 signal to the detector electronics. If another component in the - NXinstrument hierarchy provides this information, this should be a link. - - - - Notes describing entry - - - - A small image that is representative of the entry. An example of this is a 640x480 - jpeg image automatically produced by a low resolution plot of the NXdata. - - - The mime type should be an ``image/*`` - - - - - - - - - - - - - - + + + (**required**) :ref:`NXentry` describes the measurement. + + The top-level NeXus group which contains all the data and associated + information that comprise a single measurement. + It is mandatory that there is at least one + group of this type in the NeXus file. + + + + .. index:: find the default plottable data + .. index:: plotting + .. index:: default attribute value + + Declares which :ref:`NXdata` group contains the data + to be shown by default. + It is used to resolve ambiguity when + one :ref:`NXdata` group exists. + The value :ref:`names <validItemName>` a child group. If that group + itself has a ``default`` attribute, continue this chain until an + :ref:`NXdata` group is reached. + + For more information about how NeXus identifies the default + plottable data, see the + :ref:`Find Plottable Data, v3 <Find-Plottable-Data-v3>` + section. + + + + + The data group + + .. note:: Before the NIAC2016 meeting [#]_, at least one + :ref:`NXdata` group was required in each :ref:`NXentry` group. + At the NIAC2016 meeting, it was decided to make :ref:`NXdata` + an optional group in :ref:`NXentry` groups for data files that + do not use an application definition. + It is recommended strongly that all NeXus data files provide + a NXdata group. + It is permissable to omit the NXdata group only when + defining the default plot is not practical or possible + from the available data. + + For example, neutron event data may not have anything that + makes a useful plot without extensive processing. + + Certain application definitions override this decision and + require an :ref:`NXdata` group + in the :ref:`NXentry` group. The ``minOccurs=0`` attribute + in the application definition will indicate the + :ref:`NXdata` group + is optional, otherwise, it is required. + + .. [#] NIAC2016: + https://www.nexusformat.org/NIAC2016.html, + https://github.com/nexusformat/NIAC/issues/16 + + + + + + ISIS Muon IDF_Version + + + + + Extended title for entry + + + + + Unique identifier for the experiment, + defined by the facility, + possibly linked to the proposals + + + + + Brief summary of the experiment, including key objectives. + + + + + Description of the full experiment (document in pdf, latex, ...) + + + + + User or Data Acquisition defined group of NeXus files or NXentry + + + + + Brief summary of the collection, including grouping criteria. + + + + + unique identifier for the measurement, defined by the facility. + + + + + UUID identifier for the measurement. + + + + Version of UUID used + + + + + + Reserved for future use by NIAC. + + See https://github.com/nexusformat/definitions/issues/382 + + + + + (alternate use: see same field in :ref:`NXsubentry` for preferred) + + Official NeXus NXDL schema to which this entry conforms which must be + the name of the NXDL file (case sensitive without the file extension) + that the NXDL schema is defined in. + + For example the ``definition`` field for a file that conformed to the + *NXarpes.nxdl.xml* definition must contain the string **NXarpes**. + + This field is provided so that :ref:`NXentry` can be the overlay position + in a NeXus data file for an application definition and its + set of groups, fields, and attributes. + + *It is advised* to use :ref:`NXsubentry`, instead, as the overlay position. + + + + NXDL version number + + + + + URL of NXDL file + + + + + + Local NXDL schema extended from the entry + specified in the ``definition`` field. + This contains any locally-defined, + additional fields in the entry. + + + + NXDL version number + + + + + URL of NXDL file + + + + + + Starting time of measurement + + + + + Ending time of measurement + + + + + Duration of measurement + + + + + Time transpired actually collecting data i.e. taking out time when collection was + suspended due to e.g. temperature out of range + + + + + Such as "2007-3". Some user facilities organize their beam time into run cycles. + + + + + Name of program used to generate this file + + + + Program version number + + + + + configuration of the program + + + + + + Revision id of the file due to re-calibration, reprocessing, new analysis, new + instrument definition format, ... + + + + + + This is the flightpath before the sample position. This can be determined by a chopper, + by the moderator or the source itself. In other words: it the distance to the component + which gives the T0 signal to the detector electronics. If another component in the + NXinstrument hierarchy provides this information, this should be a link. + + + + + Notes describing entry + + + + + A small image that is representative of the entry. An example of this is a 640x480 + jpeg image automatically produced by a low resolution plot of the NXdata. + + + + The mime type should be an ``image/*`` + + + + + + + + + + City and country where the experiment took place + + + + + Start time of experimental run that includes the current + measurement, for example a beam time. + + + + + End time of experimental run that includes the current + measurement, for example a beam time. + + + + + Name of the institution hosting the facility + + + + + Name of the experimental facility + + + + + Name of the laboratory or beamline + + + + + + + + + + diff --git a/base_classes/NXinstrument.nxdl.xml b/base_classes/NXinstrument.nxdl.xml index e385f3671d..7fb369f97d 100644 --- a/base_classes/NXinstrument.nxdl.xml +++ b/base_classes/NXinstrument.nxdl.xml @@ -1,9 +1,9 @@ - + - - - Collection of the components of the instrument or beamline. - - Template of instrument descriptions comprising various beamline components. - Each component will also be a NeXus group defined by its distance from the - sample. Negative distances represent beamline components that are before the - sample while positive distances represent components that are after the sample. - This device allows the unique identification of beamline components in a way - that is valid for both reactor and pulsed instrumentation. - - - Name of instrument - - short name for instrument, perhaps the acronym - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + Collection of the components of the instrument or beamline. + + Template of instrument descriptions comprising various beamline components. + Each component will also be a NeXus group defined by its distance from the + sample. Negative distances represent beamline components that are before the + sample while positive distances represent components that are after the sample. + This device allows the unique identification of beamline components in a way + that is valid for both reactor and pulsed instrumentation. + + + + Name of instrument + + + + short name for instrument, perhaps the acronym + + + + + + Energy resolution of the experiment (FWHM or gaussian broadening) + + + + + Momentum resolution of the experiment (FWHM) + + + + + Angular resolution of the experiment (FWHM) + + + + + Spatial resolution of the experiment (Airy disk radius) + + + + + Temporal resolution of the experiment (FWHM) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. diff --git a/base_classes/NXprocess.nxdl.xml b/base_classes/NXprocess.nxdl.xml index d6a3346af1..ac5a8b81de 100644 --- a/base_classes/NXprocess.nxdl.xml +++ b/base_classes/NXprocess.nxdl.xml @@ -1,9 +1,9 @@ - + - - Document an event of data processing, reconstruction, or analysis for this data. + + + Document an event of data processing, reconstruction, or analysis for this data. + - Name of the program used + + Name of the program used + - Sequence index of processing, - for determining the order of multiple **NXprocess** steps. - Starts with 1. + Sequence index of processing, + for determining the order of multiple **NXprocess** steps. + Starts with 1. - Version of the program used + + Version of the program used + - Date and time of processing. + + Date and time of processing. + + + + Describes the operations of image registration + + + + + Describes the operations of image distortion correction + + + + + Describes the operations of calibration procedures, e.g. axis calibrations. + + - The note will contain information about how the data was processed - or anything about the data provenance. - The contents of the note can be anything that the processing code - can understand, or simple text. - - The name will be numbered to allow for ordering of steps. + The note will contain information about how the data was processed + or anything about the data provenance. + The contents of the note can be anything that the processing code + can understand, or simple text. + + The name will be numbered to allow for ordering of steps. - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. - diff --git a/base_classes/NXsource.nxdl.xml b/base_classes/NXsource.nxdl.xml index 85900d3f03..3fd1f983c7 100644 --- a/base_classes/NXsource.nxdl.xml +++ b/base_classes/NXsource.nxdl.xml @@ -1,9 +1,9 @@ - + - - The neutron or x-ray storage ring/facility. - - - Effective distance from sample - Distance as seen by radiation from sample. This number should be negative - to signify that it is upstream of the sample. - - - - Name of source - - short name for source, perhaps the acronym - - - - type of radiation source (pick one from the enumerated list and spell exactly) - - - - - - - - - - - - - - - - - - type of radiation probe (pick one from the enumerated list and spell exactly) - - - - - - - - - - - - - Source power - - - Source emittance (nm-rad) in X (horizontal) direction. - - - Source emittance (nm-rad) in Y (horizontal) direction. - - - particle beam size in x - - - particle beam size in y - - - Source intensity/area (example: s-1 cm-2) - - - - Source energy. - For storage rings, this would be the particle beam energy. - For X-ray tubes, this would be the excitation voltage. - - - - Accelerator, X-ray tube, or storage ring current - - - Accelerator voltage - - - Frequency of pulsed source - - - Period of pulsed source - - - Pulsed source target material - - - - - - - - - - - - - any source/facility related messages/events that - occurred during the experiment - - - - - For storage rings, description of the bunch pattern. - This is useful to describe irregular bunch patterns. - - name of the bunch pattern - - - For storage rings, the number of bunches in use. - - - For storage rings, temporal length of the bunch - - - For storage rings, time between bunches - - - temporal width of source pulse - - - source pulse shape - - - source operating mode - - for storage rings - for storage rings - - - - - Is the synchrotron operating in top_up mode? - - - For storage rings, the current at the end of the most recent injection. - date and time of the most recent injection. - - - - "Engineering" location of source. - - - - - This group describes the shape of the beam line component + + + The neutron or x-ray storage ring/facility. + + + + Effective distance from sample + Distance as seen by radiation from sample. This number should be negative + to signify that it is upstream of the sample. + + + + + Name of source + + + + short name for source, perhaps the acronym + + + + + + type of radiation source (pick one from the enumerated list and spell exactly) + + + + + + + + + + + + + + + + + + + + type of radiation probe (pick one from the enumerated list and spell exactly) + + + + + + + + + + + + + + + Source power + + + + + Source emittance (nm-rad) in X (horizontal) direction. + + + + + Source emittance (nm-rad) in Y (horizontal) direction. + + + + + particle beam size in x + + + + + particle beam size in y + + + + + Source intensity/area (example: s-1 cm-2) + + + + + Source energy. + For storage rings, this would be the particle beam energy. + For X-ray tubes, this would be the excitation voltage. + + + + + Accelerator, X-ray tube, or storage ring current + + + + + Accelerator voltage + + + + + Frequency of pulsed source + + + + + Period of pulsed source + + + + + Pulsed source target material + + + + + + + + + + + + + + any source/facility related messages/events that + occurred during the experiment + + + + + For storage rings, description of the bunch pattern. + This is useful to describe irregular bunch patterns. + + + + name of the bunch pattern - - - The wavelength or energy distribution of the source - + + + + + For storage rings, the number of bunches in use. + + + + + For storage rings, temporal length of the bunch + + + + + For storage rings, time between bunches + + + + + temporal width of source pulse + + + + + + source pulse shape + + + + + + source operating mode + + + + + for storage rings + + + + + for storage rings + + + + + + + + + Is the synchrotron operating in top_up mode? + + + + + For storage rings, the current at the end of the most recent injection. + + + + date and time of the most recent injection. + + + + + + The center photon energy of the source, before it is + monochromatized or converted + + + + + The center wavelength of the source, before it is + monochromatized or converted + + + + + For pulsed sources, the energy of a single pulse + + + + + For pulsed sources, the pulse energy divided + by the pulse duration + + + + + Some facilities tag each bunch. + First bunch of the measurement + + + + + Last bunch of the measurement + + + + + "Engineering" location of source. + + + + + This group describes the shape of the beam line component + + + + + The wavelength or energy distribution of the source + + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. - NeXus positions components by applying a set of translations and rotations - to apply to the component starting from 0, 0, 0. The order of these operations - is critical and forms what NeXus calls a dependency chain. The depends_on - field defines the path to the top most operation of the dependency chain or the - string "." if located in the origin. Usually these operations are stored in a - NXtransformations group. But NeXus allows them to be stored anywhere. - - The reference point of the source plane is its center in the x and y axis. The source is considered infinitely thin in the - z axis. - - .. image:: source/source.png - :width: 40% - + NeXus positions components by applying a set of translations and rotations + to apply to the component starting from 0, 0, 0. The order of these operations + is critical and forms what NeXus calls a dependency chain. The depends_on + field defines the path to the top most operation of the dependency chain or the + string "." if located in the origin. Usually these operations are stored in a + NXtransformations group. But NeXus allows them to be stored anywhere. + + The reference point of the source plane is its center in the x and y axis. The source is considered infinitely thin in the + z axis. + + .. image:: source/source.png + :width: 40% - This is the group recommended for holding the chain of translation - and rotation operations necessary to position the component within - the instrument. The dependency chain may however traverse similar groups in - other component groups. + This is the group recommended for holding the chain of translation + and rotation operations necessary to position the component within + the instrument. The dependency chain may however traverse similar groups in + other component groups. diff --git a/contributed_definitions/NXcollectioncolumn.nxdl.xml b/contributed_definitions/NXcollectioncolumn.nxdl.xml index d2a5fb8fa5..3117648c3a 100644 --- a/contributed_definitions/NXcollectioncolumn.nxdl.xml +++ b/contributed_definitions/NXcollectioncolumn.nxdl.xml @@ -21,10 +21,10 @@ # # For further information, see http://www.nexusformat.org --> - + - Subclass of NXelectronanalyser to describe the electron collection column of a - photoelectron analyser. + Subclass of NXelectronanalyser to describe the electron collection + column of a photoelectron analyser. diff --git a/contributed_definitions/NXmpes.nxdl.xml b/contributed_definitions/NXmpes.nxdl.xml index 8a92c050ce..f29e7337f0 100644 --- a/contributed_definitions/NXmpes.nxdl.xml +++ b/contributed_definitions/NXmpes.nxdl.xml @@ -21,11 +21,7 @@ # # For further information, see http://www.nexusformat.org --> - - + This is the most general application definition for multidimensional photoelectron spectroscopy. @@ -196,7 +192,6 @@ with higher granularity in the data description.--> - Description of the detector type. @@ -308,8 +303,8 @@ with higher granularity in the data description.--> List of comma-separated elements from the periodic table - that are contained in the sample. - If the sample substance has multiple components, all + that are contained in the sample. + If the sample substance has multiple components, all elements from each component must be included in `atom_types`. @@ -328,11 +323,6 @@ with higher granularity in the data description.--> other metadata file. In the case these are not available, free-text description. - In the case of a fixed temperature measurement this is the scalar temperature of @@ -349,7 +339,6 @@ It seems quite contorted to ask to create a separate timestamp array when we hav -