LoadEventNexus dialog.
Table of Contents
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.
| 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). |
| 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 | -1 | Run CompressEvents while loading (optional, leave blank or negative to not do). This specified the tolerance to use (in microseconds) when compressing. |
| 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 the Sample/DAS logs from the file (default True). |
| 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)’] |
The LoadEventNeXus algorithm loads data from an EventNexus file into an EventWorkspace. The default histogram bin boundaries consist of a single bin able to hold all events (in all pixels), 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.
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:
The latter two possibilities are achieved via LoadInstrument
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.
Veto pulses can be filtered out in a separate step using FilterByLogValue v1:
FilterByLogValue(InputWorkspace="ws", OutputWorkspace="ws", LogName="veto_pulse_time", PulseFilter="1")
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 |
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.
Note
To run these usage examples please first download the usage data, and add these to your path. In MantidPlot 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 10 and 20 minutes
ws = LoadEventNexus('CNCS_7860_event.nxs', FilterByTimeStart=600, FilterByTimeStop=1200)
print("The number of events: {}".format(ws.getNumberEvents()))
Output:
The number of events: 112266
Categories: Algorithm Index | DataHandling\Nexus
C++ source: LoadEventNexus.cpp (last modified: 2019-02-18)
C++ header: LoadEventNexus.h (last modified: 2019-01-28)