\(\renewcommand\AA{\unicode{x212B}}\)

LoadEventNexus v1¶

Summary ¶

Loads an Event NeXus file and stores as an EventWorkspace. Optionally, you can filter out events falling outside a range of times-of-flight and/or a time interval.

Properties ¶

Name	Direction	Type	Default	Description
Filename	Input	string	Mandatory	The name of the Event NeXus file to read, including its full or relative path. The file name is typically of the form INST_####_event.nxs (N.B. case sensitive if running on Linux). Allowed extensions: [‘.nxs.h5’, ‘.nxs’, ‘_event.nxs’]
OutputWorkspace	Output	Workspace	Mandatory	The name of the output EventWorkspace or WorkspaceGroup in which to load the EventNexus file.
NXentryName	Input	string		Optional: Name of the NXentry to load if it’s not the default.
FilterByTofMin	Input	number	Optional	Optional: To exclude events that do not fall within a range of times-of-flight. This is the minimum accepted value in microseconds. Keep blank to load all events.
FilterByTofMax	Input	number	Optional	Optional: To exclude events that do not fall within a range of times-of-flight. This is the maximum accepted value in microseconds. Keep blank to load all events.
FilterByTimeStart	Input	number	Optional	Optional: To only include events after the provided start time, in seconds (relative to the start of the run).
FilterByTimeStop	Input	number	Optional	Optional: To only include events before the provided stop time, in seconds (relative to the start of the run).
FilterBadPulsesLowerCutoff	Input	number	Optional	Optional: To filter bad pulses set the Lower Cutoff percentage to use.
BankName	Input	str list		Optional: To only include events from one bank. Any bank whose name does not match the given string will have no events.
SingleBankPixelsOnly	Input	boolean	True	Optional: Only applies if you specified a single bank to load with BankName. Only pixels in the specified bank will be created if true; all of the instrument’s pixels will be created otherwise.
Precount	Input	boolean	True	Pre-count the number of events in each pixel before allocating memory (optional, default True). This can significantly reduce memory use and memory fragmentation; it may also speed up loading.
CompressTolerance	Input	number	Optional	CompressEvents while loading (optional, default: off). This specified the tolerance to use (in microseconds) when compressing where positive is linear tolerance, negative is logorithmic tolerance, and zero indicates that time-of-flight must be identical to compress.
CompressBinningMode	Input	string	Default	Optional. Binning behavior can be specified in the usual way through sign of binwidth and other properties (‘Default’); or can be set to one of the allowed binning modes. This will override all other specification or default behavior. Allowed values: [‘Default’, ‘Linear’, ‘Logarithmic’]
ChunkNumber	Input	number	Optional	If loading the file by sections (‘chunks’), this is the section number of this execution of the algorithm.
TotalChunks	Input	number	Optional	If loading the file by sections (‘chunks’), this is the total number of sections.
LoadMonitors	Input	boolean	False	Load the monitors from the file (optional, default False).
MonitorsLoadOnly	Input	string		If multiple repesentations exist, which one to load. Default is to load the one that is present. Allowed values: [‘’, ‘Events’, ‘Histogram’]
FilterMonByTofMin	Input	number	Optional	Optional: To exclude events from monitors that do not fall within a range of times-of-flight. This is the minimum accepted value in microseconds.
FilterMonByTofMax	Input	number	Optional	Optional: To exclude events from monitors that do not fall within a range of times-of-flight. This is the maximum accepted value in microseconds.
FilterMonByTimeStart	Input	number	Optional	Optional: To only include events from monitors after the provided start time, in seconds (relative to the start of the run).
FilterMonByTimeStop	Input	number	Optional	Optional: To only include events from monitors before the provided stop time, in seconds (relative to the start of the run).
SpectrumMin	Input	number	Optional	The number of the first spectrum to read.
SpectrumMax	Input	number	Optional	The number of the last spectrum to read.
SpectrumList	Input	int list		A comma-separated list of individual spectra to read.
MetaDataOnly	Input	boolean	False	If true, only the meta data and sample logs will be loaded.
LoadLogs	Input	boolean	True	Load only the Sample/DAS logs from the file (default True).
LoadAllLogs	Input	boolean	False	Load all the logs from the nxs, without checking or processing them; if checked, LoadLogs will be ignored; use with caution
LoadType	Input	string	Default	Set type of loader. 2 options {Default, Multiproceess},’Multiprocess’ should work faster for big files and it is experimental, available only in Linux. Allowed values: [‘Default’, ‘Multiprocess (experimental)’]
LoadNexusInstrumentXML	Input	boolean	True	Reads the embedded Instrument XML from the NeXus file (optional, default True).
NumberOfBins	Input	number	500	The number of bins intially defined. Use Rebin to change the binning later. If there is no data loaded, or you select meta data only you will only get 1 bin.
AllowList	Input	str list		If specified, only these logs will be loaded from the file (each separated by a space).
BlockList	Input	str list		If specified, these logs will NOT be loaded from the file (each separated by a space).

The LoadEventNeXus algorithm loads data from an EventNexus file into an EventWorkspace. The histogram bin boundaries depend on the setting of NumberOfBins, which by default will be the whole range of time of flight able to hold all events (in all pixels) split into NumberOfBins linear bins, and will have their units set to time-of-flight. Since it is an EventWorkspace, it can be rebinned to finer bins with no loss of data.

Child algorithms used ¶

Sample logs, such as motor positions or e.g. temperature vs time, are also loaded using LoadNexusLogs.

Monitors are loaded using LoadNexusMonitors.

Instrument geometry

There are a series of approaches for extracting the instrument geometry. These follow the escalation path as follows:

Tries to load embedded instrument_xml from the NXinstrument if present using LoadIDFFromNexus.
Else tries to load embedded nexus geometry from the NXinstrument if present
Else tries to load the instrument using the name extracted from NXinstrument

The latter two possibilities are achieved via LoadInstrument

Optional properties ¶

If desired, you can filter out the events at the time of loading, by specifying minimum and maximum time-of-flight values. This can speed up loading and reduce memory requirements if you are only interested in a narrow range of the times-of-flight of your data.

You can specify to load only certain spectra within the file, using the SpectraMax, SpectraMin and SpectraList properties. This will load data only matching those restrictions. At facilities that do not group detectors in hardware such as the SNS, then this will also equate to the detector IDs.

You may also filter out events by providing the start and stop times, in seconds, relative to the first pulse (the start of the run).

If you wish to load only a single bank, you may enter its name and no events from other banks will be loaded.

The Precount option will count the number of events in each pixel before allocating the memory for each event list. Without this option, because of the way vectors grow and are re-allocated, it is possible for up to 2x too much memory to be allocated for a given event list, meaning that your EventWorkspace may occupy nearly twice as much memory as needed. The pre-counting step takes some time but that is normally compensated by the speed-up in avoid re-allocating, so the net result is smaller memory footprint and approximately the same loading time.

Event Compression ¶

When CompressTolerance is set, the data loaded will be compressed while creating the individual weighted events. The compression will accumulate events to create a weighted event with no time and cannot be further filtered afterwards. This parameter is interpreted to be linear tolerance when positive, and logorithmic tolerance when negative. When CompressBinningMode is specified, the CompressTolerance is modified be linear or logarithmic. This mode does take longer than running LoadEventNexus without compression, but reduces the overall memory used during algorithm execution, and memory used by the resulting workspace. For files that do not have many events, this does not necessarily have an effect other than slowing down loading.

Note

The workspace created by LoadEventNexus with compression are different from those created by LoadEventNexus without compression then CompressedEvents. The histogram representation will be near identical if the tolerence is selected appropriately.

Veto Pulses ¶

Veto pulses can be filtered out in a separate step using FilterByLogValue v1:

FilterByLogValue(InputWorkspace="ws", OutputWorkspace="ws", LogName="veto_pulse_time", PulseFilter="1")

Data Loaded from Nexus File ¶

If LoadAllLogs is checked, all the logs in the Nexus files will be loaded directly in the sample logs as they are. The LoadLogs flag will be ignored. If only LoadLogs is checked, only a subset of the logs will be processed and loaded, in the manner described afterward.

The nexus file must have /raw_data_1 or /entry as its main group and that group be of type NXentry. It also needs a group of type NXevent_data.

The data is read from each group of type NXevent_data.

If the file has an isis_vms_compat then it is taken to be an ISIS file and the data will be modified according to the information obtained from this group.

Here are some tables that show it in more detail:

Description of Data	Found in Nexus file (within ‘raw_data_1’)	Placed in Workspace (Workspace2D)
Monitor Data	groups of Class NXMonitor (one monitor per group)	Monitor Data
Detector Data	groups of Class NXevent_data (one bank per group)	Event data
Instrument	group `Instrument`	Workspace instrument if not overridden
Spectrum of each detector ID	If `isis_vms_compat` exists, `NSP1`, `UDET` and `SPEC` within it, else one spectrum per detector assumed	Spectra-Detector mapping
Run	mainly as loaded from LoadNexusLogs v1	Run Object
Sample	If `isis_vms_compat` exists, `SPB` and `RSPB` within `isis_vms_compat` else sample not loaded	Sample Object

Invalid Period Logs Error ¶

There is an issue specific to ISIS, particularly on long runs, where noise on data collection instruments can change the period of the data. This can cause the period associated with certain data points to exceed the total number of periods we expect.

LoadEventNeXus compares the total number of periods we expect, which can be found in the periods/number attribute of the run, and the greatest period number found in framelog/period_log/value attribute of the data. If they do not match, an error message is raised which explains this problem, and loading of the data will be unsuccessful.

In this case, the data is fundamentally corrupted, so Mantid does not know how to correct this automatically. If you only expect 1 period, there is a script in the script repository, user/TomTitcombe/correct_period_logs.py, which will change all the periods in framelog/period_log/value to 1.

If you expect more than 1 periods, there is currently no solution script available through Mantid. You should contact the Mantid team to discuss the problem and possible solutions.

Sample Object ¶

If isis_vms_compat exists, then the following sample properties are read from it:

Nexus	Workspace sample object
`SPB[2]`	Geometry flag
`RSPB[3]`	Thickness
`RSPB[4]`	Height
`RSPB[5]`	Width

This is the same as read by LoadISISNexus v2.

Usage ¶

Note

To run these usage examples please first download the usage data, and add these to your path. In Mantid this is done using Manage User Directories.

Example - Load SNS/ISIS event Nexus file:

# Load SNS HYS event dataset
ws = LoadEventNexus('HYS_11092_event.nxs')

print("The number of histograms (spectra) is: {}".format(ws.getNumberHistograms()))

Output:

The number of histograms (spectra) is: 20480

Example - Load event nexus file with time filtering:

# Load SNS CNCS event dataset between 1 and 2 minutes
ws = LoadEventNexus('CNCS_7860_event.nxs', FilterByTimeStart=60, FilterByTimeStop=120)

print("The number of events: {}".format(ws.getNumberEvents()))

Output:

The number of events: 29753

Categories: AlgorithmIndex | DataHandling\Nexus

Source ¶

C++ header: LoadEventNexus.h

C++ source: LoadEventNexus.cpp