16.5. Diamond Scan Collection

When nexus is written using the new (GDA9) nexus writing framework, whether that is with solstice (new) scanning or classic scanning, the resulting nexus file will contain a group called diamond_scan with nexus class NXcollection. This group is used to gather useful information about the scan, for use by DAWN and for processing. This includes timing related information, such as scan start and end time, as well as the unique keys dataset(s). The diamond_scan collection is contained directly in the main entry for the scan, i.e. it has the path /entry:NXentry/diamond_scan:NXcollection/

This page lists the datasets that may be contained within the diamond_scan collection.

16.5.1. Timing related datasets

The following datasets relate to timings. Most are of type NX_DATE_TIME, i.e. a timestamp. These are actually written into the nexus file as Strings, using ISO8601 format, with 3 digits for milliseconds.

Dataset Name	Type	Description
start_time	NX_DATE_TIME	The time the scan started. A link to entry/start_time.
end_time	NX_DATE_TIME	The time the scan finished. A link to entry/end_time.
duration	NX_INT	The duration of the scan in milliseconds. A link to entry/duration.
scan_estimated_duration	NX_INT	The estimated duration of the scan in milliseconds, calculated as exposure time * number of points
scan_dead_time	NX_FLOAT	The dead time of the scan in milliseconds, calculated as duration - scan_estimated_duration
scan_dead_time_percent	NX_INT	The percentage of the scan duration that was dead time.
scan finished	NX_INT	1 if the scan has finished, otherwise 0.
point_start	NX_DATE_TIME	The start time of each point of the scan. A per-point dataset. New scanning software scan only.
point_end	NX_DATE_TIME	The end time of each point of the scan. A per-point dataset. New scanning software scans only.

16.5.2. Scan metadata datasets

These datasets give non-timing related information about the scan, such as the scan shape. Many of these fields are specific either to old scanning or new scanning.

Dataset Name	Type	Description
scan_shape	NX_INT	The shape of the scan datasets, A one-dimensional array valued dataset, e.g. a 5x10 grid scan, scanned at at 8 different values of ‘energy’ will have shape [8, 5, 10]. Note that scan shape may be flattened, e.g. for a spiral scan, or a grid scan with an non-rectangular shaped region, such as a circle.
scan_rank	NX_INT	The rank of the scan, a single integer value. E.g. for a grid scan this will be 2 (unless it has been flattened. This scan rank is equal to the length of the scan_shape dataset above.
scan_request	NX_CHAR	The scan request as a JSON string. New scanning only.
scan_model	NX_CHAR	The scan path model as a JSON string. New scanning only.
scan_command	NX_CHAR	The scan command. Currently old scanning only.
scan_fields	NX_CHAR	The fields of the scan, i.e. the input and extra names of the scannables and monitors, and the detector header fields, as found in a dat file. Old scanning only.
current_script_name	NX_CHAR	The top-level script that launched the scan, if known. Currently old scanning only.

16.5.3. Unique Keys datasets

New nexus writing supports SWMR (Single Write, Multiple Read), allowing a nexus file to be read as it is being written. This is used to process the data in the nexus file as it is being written (live processing). The unique keys dataset exists(s) to enable live processing to know when a point of the scan has been written. These unique keys dataset(s) have the same shape as the scan, with a sequential number being written at the end of each point to the appropriate location in the dataset. These datasets are contained within a child group of the diamond_scan collection called keys, also of nexus class NXcollection. The path of this collection within the nexus file will therefore be /entry:NXentry/diamond_scan:NXcollection/keys:NXcollection.

For most scans, GDA will write a global unique keys dataset, called uniqueKeys. Some detectors may write their own unique_keys dataset (for example Area Detector normally does). If so, the keys collection will contains a link to that dataset. If multiple unique keys datasets are present, then a point will not be processed until all of the unique keys datasetset have been written to for that point. For hardware (malcolm) scans, GDA does not write a global uniqueKeys dataset - this would not be possible as malcolm is running the scan. Instead malcolm (through its datasets attribute) informs GDA of the datasets that it knows about. These will include a unique keys dataset for each detector. The keys collection will contain a link to each of these unique keys datasets.

Dataset Name	Type	Description
uniqueKeys	NX_INT	The global unique keys dataset, written by GDA. Software scans only.
(detectorName)	NX_INT	One or more unique keys datasets for specific detectors