TOFRawScan

NXTOFRWSC - proposed extensions to NXTOFRW to provide a NeXus Time-Of-Flight Raw Data File Scan Format

Introduction

This document defines extensions to the single run format to deal with scans and ISIS period type experiments; the same conventions used there apply here.

NXentry

One question that is the subject of much debate is whether a single NXentry should only describe a single measurement or whether it could contain several measurements. The single measurement case is outlined in TOFRaw and we outline here two possible methods of storing multiple measurements.

Type 1: linking entries to describe scans

Often each scan point will be written as an NXentry in a separate file e.g. the scan is controlled by some external script. In this case all that is needed is:

  1. a way to identify which files belong together
  2. preferably, a way to quickly identify what is changing during the scan without having to compare all items in the file

A suggestion for (1) is to have a “scan_id” variable so that all files with the same value of “scan_id” will form part of the same scan; the element scan_point will indicate the scan point (1, 2, 3, …). If scan_id is set to the “run_number” of the first scan point, it will be guaranteed not to conflict with any other scans or run as the run number is unique for a given file (and often part of the file name).

RE Name Attribute Type Value Description
0/1 <font color=red>Scan_id</font>   NX_INT   Allows Entries that are part of the same scan to be identified. This could be the run number of the first scan point
0/1 <font color=red>Scan_point</font>   NX_INT   the point within a scan. 1=first, 2=second etc
0/1 <font color=red>Scan_total</font>   NX_INT   Number of points in this scan i.e. number of separate NXentries making up the scan
0/1 <font color=red>Scan_labels</font>   NX_CHAR   comma separated list of titles/labels for each scan point

For (2) above there are two choices: either tag each variable that is being varied with an extra attribute called e.g. “scanned”, or link all the variables that are being scanned into an “NXscan” structure. If an NXscan structure is decided on, then scan_id above should probably be moved into this rather than be in NXentry.

In the case of a scan of two variables, we could set scanned=1 for the fastest varying variable and scanned=2 for the second fastest etc. Note that the notion of “fastest varying” depends, of course, on the order that you read the files in - this notion tells you which is varying fastest if the files are read in numerical run number order. Note that the “scanned variable” is a hint to the reading program and tells you what is being scanned over the whole measurement - if you just picked two files at random then only one of the many marked “scanned” variables would have changed and it is up to the reading program to work out which one.

If several NXentry objects are written to the same file to describe scan points, it would be useful to have a naming convention so that they could be ordered quickly. NeXus convention is that entries are called “entry1”, “entry2”, … maybe for scans this could be extended to “entry1_1”, “entry1_2” for scan points 1 and 2 etc.

Type 2: containing multiple measurements

Note: we are considering splitting “single measurement” and “scan” into separate definitions - see the discussion tab for more information

Sometimes a scan is set up and directed by the data acquisition electronics itself. An example would be when you want to perform a very rapid scan of e.g. temperature or to rapidly swap between two states (e.g. laser on and laser off). What is different about this situation compared to above is that no data is transferred from the acquisition system (and so no file written) until the scan is complete. Such a situation could be treated by the same mechanism as above, but has traditionally been done by adding an extra array dimension to the data and the varying variables rather than writing additional files.

To illustrate this rather than having “entry1.sample.temperature”, “entry1.detector.counts[i]”, “entry2.sample.temperature” and “entry2.detector.counts[i]” we would just have “entry1.sample.temperature[j]” and “entry1.detector.counts[i,j]” where j indexes the scan point. Advantages of this scheme over writing seapare NXentries to a single file are:

You still need a mechanism to indicate scanned variables (either a scanned attribute or an NXscan structure as described above). Several of the above variables in NXentry will also become arrays of size (number of scan points, scan_total) e.g. raw_frames, good_frames, scan_point. As the counts array that appears within NXdata now depends on the the scan index [j], you will need to link in additional axis/axes to the NXdata to indicate this dependence. For this you could link in the scan_point[j] array or the individual temperature[j], magnetic_field[j] etc. arrays depending on how you want to plot your data.

As as it is possible cycle rounds the scans and continue counting a particular scan point at a later stage, the following new variable is introduced:

           
1 <font color=red>scan_cycles</font>   NX_INT[j]   Number of times a data acquisition was initiated for this scan point

NXsample

Some variables describing sample environment parameters may become arrays with a Type 2 NXentry e.g.

RE Name Attribute Type Value Description
0/1 temperature   NX_FLOAT[nscan]    

NXdetector

If detetor angles are scanned, an extra array dimension may be present with a Type 2 NXentry e.g.

RE Name Attribute Type Value Description
1 Polar_angle   NX_FLOAT[i,nscan]    
0/1 Azimuthal_angle   NX_FLOAT[i,nscan]    
0/1 Distance   NX_FLOAT[i,nscan] distance from sample