[Previous Page | Next Page | NeXus Home Page | NeXus Site Map]

The Contents of NeXus Files

The structure of NeXus files, described in the previous sections, ensures that generic browsers and plotting packages will be able to navigate them in order to locate plottable data and identify instrumental parameters manually. However, in order to develop more specific analysis software, it is necessary to define the actual contents of NeXus files. As discussed in the introduction, it is not necessary for every piece of information defined in the standard to be present in every NeXus file. The user can decide how comprehensive the file contents will be. However, NeXus defines where the information should go if it is included, and what it should be called.

• Naming Conventions
  
• Units
  
• Glossary
  
• Instrument Definitions
  

Naming Conventions

As the NeXus format develops, a glossary of neutron and X-ray data items will be built up. The following naming conventions are proposed for NeXus file, data and attribute names:

File Names

It is recommended that NeXus files are given the extension .nxs, rather than the generic HDF extensions of .hdf or .h5. If it is necessary to distinguish between HDF4 and HDF5 files, e.g., containing the same data, use .nx4 and/or .nx5.

Name Spaces

The name of any data item within a NeXus group must be unique to that group. This is important in HDF5 versions of NeXus files, since the full path name, e.g., /entry/sample/temperature, is a unique identifier of each data item. However, the same name can be used in different groups.

General Rules

• Lower case letters are used throughout, except for common symbols and abbreviations such as FWHM. Note that HDF names are case-sensitive so this rule is designed to avoid confusion between, e.g. name and Name.

• Names are constructed from full words separated by the underscore character e.g. time_of_flight.

• For sequentially indexed group names, the sequential number is simply appended to the name, e.g. filter1, filter2. This convention should be used only for data group names, and then sparingly, because of a potential for confusion between indexed and non-indexed names.

  The datasets with multiple instances of some primitive data record should be stored in multi-dimensional arrays rather than in differently-named HDF data elements.

• Class names are prefixed with the letters NX to avoid clashes with class names internal to HDF. Their names are prescribed by the NeXus standard.

• The hierarchical structure of NeXus files should be used to simplify data names. For example, the data set containing the sample temperature will be called "temperature" since its location in the NXsample group makes the longer name "sample_temperature" unnecessary.

Units

It is very important that, whenever possible, data units are specified for all physical data. This is implemented in the NeXus API in the NXputattr command. Our intentions is to give the user flexibility in specifying their preferred units when writing the NeXus data. The NeXus API will then perform automatic conversions to the requested units when reading the data (N.B. not yet implemented in API).

Physical Units

We recommend the use of S.I. units while recognizing that other units are very common in the neutron and X-ray community e.g. meV and Angstroms. Whatever units are used, they must be specified as a character string in the format used by the Unidata UDunits utility (in particular, see udunits.dat). This is because we plan to make use of the utility internally for unit conversions in the NeXus API.

Dates and Times

NeXus dates and times should be stored using the ISO 8601 format e.g. 1996-07-31T21:15:22+0600. This will avoid confusion, e.g. between U.S. and European conventions, and is appropriate for machine sorting. We intend to provide routines for converting from absolute time in the ISO 8601 format to elapsed time e.g. in seconds.

Glossary

The glossary defines the names of all the groups, data items, and attributes so far defined in the NeXus format. NeXus files will typically contain only a small fraction of these items. Although users are free to include data items not defined here, they are encouraged to use the defined names where possible.

The NeXus glossary is now defined in XML files for each NeXus group and uses a simplified meta-DTD format. The glossary is not complete; if you wish to suggest additional group classes or data items, please contact me. Comments may also be addressed to the NeXus mailing list.

NeXus Group Classes

NXentry

This is 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.

NXdata

This contains plottable data along with its dimension scales.

NXuser

This contains contact information for the user. These items are also listed as global attributes. The reason for this duplication is that it may be necessary to maintain the user/owner information of an NXentry if it is transferred as a unit. By default, the global attributes are specified by the first NXentry in the NeXus file.

NXsample

This is the NeXus group which contains all the information describing the state of the sample. These could include scanned variables that are associated with one of the data dimensions e.g. the magnetic field, or logged data, e.g. monitored temperature v real time.

NXmonitor

This group contains monitor data. It is similar to the NXdata groups containing monitor data and its associated dimension scale e.g. time_of_flight or wavelength in pulsed neutron instruments. However, it may also include integrals, or scalar monitor counts, which are often used in both in both pulsed and steady-state instrumentation.

NXinstrument

This comprises the top-level instrument description and is a means of organizing components in the instrument. 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.

NXsource

This contains information about the neutron or X-ray source.

NXchopper

Data sets required to describe the chopper configuration, including the type of chopper, e.g. Fermi, rotation speeds, slit widths etc.

NXcrystal

Data sets that define a crystal used for wavelength monochromatization, either before or after the sample e.g. d-spacing, mosaicity.

NXcollimator

Data sets that define the physical characteristics of a beamline collimator.

NXaperture

Data sets that define beam apertures.

NXattenuator

Data sets that define attenuators in the beam.

NXpolarizer

Data sets that define the physical characteristics of a polarizing device.

NXflipper

Data sets that define polarization flippers

NXmirror

Data sets that define the properties of mirror guides.

NXdetector

Data sets that define the properties of a detector, bank of detectors or multi-detector

NXbeam

This NeXus group stores information required to define the state of the neutron or X-ray beam at any location. It will be referenced by beamline component groups within the NXinstrument group or by the NXsample group. Note that variables such as the incident energy could be scalar values or arrays. 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 NXsample group in which it defines the results of the neutron scattering by the sample e.g. energy transfer, polarizations.

NXlog

This is a group class designed to contain any logged information i.e. information monitored during the run at time intervals. They contain the logged values and the times at which they were measured in either ISO 8601 format, or as elapsed time since the beginning of the run. This method of storing logged data helps to distinguish instances in which a variable is a dimension scale of the data, in which case it is stored in an NXdata group, and instances in which it is logged during the run, when it should be stored in an NXlog group.

NeXus Global Attributes

Global attributes are attributes of the whole file. The first three (file_name, file_time, and NeXus_version) are defined automatically by the NeXus API when the file is first produced.

NeXus Data Attributes

Data attributes provide extra information defining the contents of each data item. The most common is the "units" attribute which is a required part of the NeXus standard whenever the data item has physical units.

Instrument Definitions

It is impossible to define the precise format for every type of neutron and X-ray instrument. New developments ensure that such a project would need constant revision and updating, and it is not clear that there is any point to specifying such a standard when only one or two instances of an instrument design exists. However, it is possible to define some generic forms of instrumentation which would describe an appreciable number of existing instruments around the world. Although not identical in every detail, they share enough common characteristics, and more importantly, they require sufficiently similar modes of data analysis, to make a standard description useful.

The following instruments have been, or are in the process of being, defined for the NeXus standard. This list reflects the interests and expertise of those involved in developing the format. If you are interested in defining a new type of instrument, or wish to suggest modifications to the current definitions, please contact me. Comments may also be addressed to the NeXus mailing list. The NeXus meta-DTD format used in these instrument definitions is described here.

The following instruments have been, or are in the process of being, defined for the NeXus standard. This list reflects the interests and expertise of those involved in developing the format. If you are interested in defining a new type of instrument, or wish to suggest modifications to the current definitions, please contact me. Comments may also be addressed to the NeXus mailing list.

Monochromatic Neutron/X-ray Powder Diffractometer Time-of-flight Neutron Powder Diffractometer Monochromatic Neutron/X-ray Single Crystal Diffractometer Time-of-flight Neutron Single Crystal Diffractometer Monochromatic Neutron/X-ray Small Angle Scattering Diffractometer Time-of-flight Neutron Small Angle Scattering Diffractometer Monochromatic Neutron/X-ray Reflectometer Time-of-flight Neutron Reflectometer Neutron/X-ray Triple-Axis Spectrometer Neutron Direct-Geometry Time-of-flight Spectrometer Neutron Inverse-Geometry Time-of-flight Spectrometer