# 3.3.2.10. NXmx¶

Status:

application definition, extends NXobject

Description:

functional application definition for macromolecular crystallography

Symbols:

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 element.

dataRank: rank of the data field

np: number of scan points

i: number of detector pixels in the slowest direction

j: number of detector pixels in the second slowest direction

k: number of detector pixels in the third slowest direction

Groups cited:
NXattenuator, NXbeam, NXcollection, NXdata, NXdetector_group, NXdetector_module, NXdetector, NXentry, NXgeometry, NXinstrument, NXnote, NXsample, NXsource, NXtransformations

Structure:

(entry): (required) NXentry

title: (optional) NX_CHAR

start_time: (required) NX_DATE_TIME

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.

end_time: (optional) NX_DATE_TIME

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.

end_time_estimated: (required) NX_DATE_TIME

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 avilable.

definition: (required) NX_CHAR

NeXus NXDL schema to which this file conforms

Obligatory value: NXmx

(data): (required) NXdata

data[np, i, j, k]: (recommended) NX_NUMBER

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.

(sample): (required) NXsample

name: (required) NX_CHAR

Descriptive name of sample

depends_on: (required) NX_CHAR

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 ”.”

temperature: (optional) NX_CHAR {units=NX_TEMPERATURE}

(transformations): (required) NXtransformations

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.

(instrument): (required) NXinstrument

name: (required) NX_CHAR

Name of instrument

@short_name: (required) NX_CHAR

short name for instrument, perhaps the acronym

time_zone: (recommended) NX_DATE_TIME

ISO 8601 time_zone offset from UTC

(attenuator): (optional) NXattenuator

attenuator_transmission: (optional) NX_NUMBER {units=NX_UNITLESS}

(detector_group): (recommended) NXdetector_group

Optional logical grouping of detector elements.

Each detector element is represented as an NXdetector group with its own detector data array. Each detector data array may be further decomposed into array sections by use of NXdetector_module groups. The names are given in the group names field.

The groups are defined hierarchically, with names given in the group_names field, unique identifiing 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, DET, consists of four elements 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]


group_names: (required) NX_CHAR

An array of the names of the detector elements or hierarchical groupings of detector elements.

Specified in the base classes as comma separated list of names, but new code should use an array of names as quoted strings.

group_index[i]: (required) NX_INT

An array of unique indices for detector elements or groupings of detector elements.

Each element is a unique ID for the corresponding group named in the field group_names. The IDs are positive integers starting with 1.

group_parent[group_index]: (required) NX_INT

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

(detector): (required) NXdetector

Normally the detector group will have the name detector. However, in the case of multiple detector elements, each element needs a uniquely named NXdetector group.

depends_on: (required) NX_CHAR

NeXus path to the detector positioner axis that most directly supports the detector.

data[np, i, j, k]: (recommended) NX_NUMBER

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.

description: (recommended) NX_CHAR

name/manufacturer/model/etc. information

time_per_channel: (optional) NX_CHAR {units=NX_TIME}

todo: define more clearly

distance: (recommended) NX_FLOAT {units=NX_LENGTH}

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.

distance_derived: (recommended) NX_BOOLEAN {units=NX_LENGTH}

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.

count_time: (recommended) NX_NUMBER {units=NX_TIME}

Elapsed actual counting time

beam_center_derived: (optional) NX_BOOLEAN {units=NX_LENGTH}

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

beam_center_x: (recommended) NX_FLOAT {units=NX_LENGTH}

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 precendence if it is not a derived quantity.

beam_center_y: (recommended) NX_FLOAT {units=NX_LENGTH}

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 precendence if it is not a derived quantity.

angular_calibration_applied: (optional) NX_BOOLEAN

True when the angular calibration has been applied in the electronics, false otherwise.

angular_calibration[i, j, k]: (optional) NX_FLOAT

Angular calibration data.

flatfield_applied: (optional) NX_BOOLEAN

True when the flat field correction has been applied in the electronics, false otherwise.

flatfield[i, j, k]: (optional) NX_FLOAT

Flat field correction data. If provided, it is recommended that is be compressed

flatfield_error[i, j, k]: (optional) NX_FLOAT

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 or high or otherwise unwanted or undesirable pixels. They have the following meaning:

• bit 0: gap (pixel with no sensor)
• 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 provided, it is recommended that it be compressed

countrate_correction_applied: (optional) NX_BOOLEAN

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.

frame_time: (optional) NX_FLOAT {units=NX_TIME}

This is time for each frame. This is exposure_time + readout time.

gain_setting: (optional) NX_CHAR

The gain setting of the detector. This influences background.

saturation_value: (optional) NX_INT

The value at which the detector goes into saturation. Data above this value is known to be invalid.

sensor_material: (required) NX_CHAR

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.

sensor_thickness: (required) NX_FLOAT {units=NX_LENGTH}

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.

threshold_energy: (optional) NX_FLOAT {units=NX_ENERGY}

Single photon counter detectors can be adjusted for a certain energy range in which they work optimally. This is the energy setting for this.

type: (optional) NX_CHAR

Description of type such as scintillator, ccd, pixel, image plate, CMOS, ...

(transformations): (required) NXtransformations

Location for axes (transformations) to do with the detector

(collection): (optional) NXcollection

Suggested container for detailed non-standard detector information like corrections applied automatically or performance settings.

(detector_module): (required) NXdetector_module

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.

data_origin: (required) NX_INT

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 order of indices (i, j or i, j, k) is slow to fast.

data_size: (required) NX_INT

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.

data_stride: (optional) NX_INT

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.

module_offset: (optional) NX_NUMBER {units=NX_LENGTH}

Offset of the module in regards to the origin of the detector in an arbitrary direction.

@transformation_type: (required) NX_CHAR

Obligatory value: translation

@vector: (required) NX_CHAR

@offset: (required) NX_CHAR

@depends_on: (required) NX_CHAR

fast_pixel_direction: (required) NX_NUMBER {units=NX_LENGTH}

Values along the direction of fastest varying pixel direction. The direction itself is given through the vector attribute

@transformation_type: (required) NX_CHAR

Obligatory value: translation

@vector: (required) NX_CHAR

@offset: (required) NX_CHAR

@depends_on: (required) NX_CHAR

slow_pixel_direction: (required) NX_NUMBER {units=NX_LENGTH}

Values along the direction of slow varying pixel direction. The direction itself is given through the vector attribute

@transformation_type: (required) NX_CHAR

Obligatory value: translation

@vector: (required) NX_CHAR

@offset: (required) NX_CHAR

@depends_on: (required) NX_CHAR

(beam): (required) NXbeam

incident_wavelength: (required) NX_FLOAT {units=NX_WAVELENGTH}

In the case of a monchromatic beam this is the scalar wavelength.

In the case of a polychromatic beam this is an array of the wavelengths with the relative weights in incident_wavelength_weight.

incident_wavelength_weight: (optional) NX_FLOAT

In the case of a polychromatic beam this is an array of the relative weights of the corresponding wavelengths in incident_wavelength.

The wavelength spread FWHM for the corresponding wavelength(s) in incident_wavelength.

flux: (optional) NX_FLOAT {units=NX_FLUX}

flux incident on beam plane area in photons per second per unit area

total_flux: (required) NX_FLOAT {units=NX_FREQUENCY}

flux incident on beam plane in photons per second

incident_beam_size[2]: (recommended) NX_FLOAT {units=NX_LENGTH}

Two-element array of FWHM (if Gaussian or Airy function) or diameters (if top hat) or widths (if rectangular) of beam in the order x, y

profile: (recommended) NX_CHAR

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.

Any of these values: Gaussian | Airy | top-hat | rectangular

incident_polarisation_stokes[np, 4]: (recommended) NX_CHAR

incident_wavelength_spectrum: (optional) NXdata

(source): (required) NXsource

The neutron or x-ray storage ring/facility.

distance: (optional) NX_FLOAT {units=NX_LENGTH}

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: (required) NX_CHAR

Name of source

@short_name: (optional) NX_CHAR

short name for source, perhaps the acronym

type: (optional) NX_CHAR

type of radiation source (pick one from the enumerated list and spell exactly)

Any of these values:

• Spallation Neutron Source
• Pulsed Reactor Neutron Source
• Reactor Neutron Source
• Synchrotron X-ray Source
• Pulsed Muon Source
• Rotating Anode X-ray
• Fixed Tube X-ray
• UV Laser
• Free-Electron Laser
• Optical Laser
• Ion Source
• UV Plasma Source

probe: (optional) NX_CHAR

type of radiation probe (pick one from the enumerated list and spell exactly)

Any of these values:

• neutron
• x-ray
• muon
• electron
• ultraviolet
• visible light
• positron
• proton

power: (optional) NX_FLOAT {units=NX_POWER}

Source power

emittance_x: (optional) NX_FLOAT {units=NX_EMITTANCE}

Source emittance (nm-rad) in X (horizontal) direction.

emittance_y: (optional) NX_FLOAT {units=NX_EMITTANCE}

Source emittance (nm-rad) in Y (horizontal) direction.

sigma_x: (optional) NX_FLOAT {units=NX_LENGTH}

particle beam size in x

sigma_y: (optional) NX_FLOAT {units=NX_LENGTH}

particle beam size in y

flux: (optional) NX_FLOAT {units=NX_FLUX}

Source intensity/area (example: s-1 cm-2)

energy: (optional) NX_FLOAT {units=NX_ENERGY}

Source energy. For storage rings, this would be the particle beam energy. For X-ray tubes, this would be the excitation voltage.

current: (optional) NX_FLOAT {units=NX_CURRENT}

Accelerator, X-ray tube, or storage ring current

voltage: (optional) NX_FLOAT {units=NX_VOLTAGE}

Accelerator voltage

frequency: (optional) NX_FLOAT {units=NX_FREQUENCY}

Frequency of pulsed source

period: (optional) NX_FLOAT {units=NX_PERIOD}

Period of pulsed source

target_material: (optional) NX_CHAR

Pulsed source target material

Any of these values:

• Ta
• W
• depleted_U
• enriched_U
• Hg
• Pb
• C

number_of_bunches: (optional) NX_INT

For storage rings, the number of bunches in use.

bunch_length: (optional) NX_FLOAT {units=NX_TIME}

For storage rings, temporal length of the bunch

bunch_distance: (optional) NX_FLOAT {units=NX_TIME}

For storage rings, time between bunches

pulse_width: (optional) NX_FLOAT {units=NX_TIME}

temporal width of source pulse

mode: (optional) NX_CHAR

source operating mode

Any of these values:

• Single Bunch: for storage rings
• Multi Bunch: for storage rings

top_up: (optional) NX_BOOLEAN

Is the synchrotron operating in top_up mode?

last_fill: (optional) NX_NUMBER {units=NX_CURRENT}

For storage rings, the current at the end of the most recent injection.

@time: (required) NX_DATE_TIME

date and time of the most recent injection.

notes: (optional) NXnote

any source/facility related messages/events that occurred during the experiment

bunch_pattern: (optional) NXdata

For storage rings, description of the bunch pattern. This is useful to describe irregular bunch patterns.

title: (required) NX_CHAR

name of the bunch pattern

pulse_shape: (optional) NXdata

source pulse shape

geometry: (optional) NXgeometry

“Engineering” location of source

distribution: (optional) NXdata

The wavelength or energy distribution of the source
NXDL Source:
https://github.com/nexusformat/definitions/blob/master/applications/NXmx.nxdl.xml