GenerateEventsFilter v1¶

GenerateEventsFilter dialog.

Table of Contents

Summary
Properties
Description
Algorithm Parameters and Examples
Usage
Source

Summary ¶

Generate one or a set of event filters according to time or specified log’s value.

Properties ¶

Name	Direction	Type	Default	Description
InputWorkspace	Input	EventWorkspace	Mandatory	An input event workspace
OutputWorkspace	Output	Workspace	Mandatory	The name to use for the output SplittersWorkspace object, i.e., the filter.
InformationWorkspace	Output	TableWorkspace	Mandatory	Optional output for the information of each splitter workspace index
FastLog	Input	boolean	False	Fast log will make output workspace to be a matrix workspace.
StartTime	Input	string		The start time, such that all events before this time are filtered out. It could be (1) relative time to run start time in unit as specified property ‘UnitOfTime’ or (2) absolute time. Absolute time takes a string in format as 1990-01-01T00:00:00, while the relative time takes integer or float.
StopTime	Input	string		The stop time, such that all events after this time are filtered out. It could be (1) relative time to run start time in unit as specified property ‘UnitOfTime’ or (2) absolute time. Absolute time takes a string in format as 1990-01-01T00:00:00, while the relative time takes integer or float.
TimeInterval	Input	dbl list		Array for lengths of time intervals for splitters. If the array is empty, then there will be one splitter created from StartTime and StopTime. If the array has one value, then all splitters will have same time intervals. If the size of the array is larger than one, then the splitters can have various time interval values.
UnitOfTime	Input	string	Seconds	StartTime, StopTime and DeltaTime can be given in various unit.The unit can be ‘Seconds’ or ‘Nanoseconds’ from run start time.They can also be defined as ‘Percentage’ of total run time. Allowed values: [‘Seconds’, ‘Nanoseconds’, ‘Percent’]
LogName	Input	string		Name of the sample log to use to filter. For example, the pulse charge is recorded in ‘ProtonCharge’.
MinimumLogValue	Input	number	Optional	Minimum log value for which to keep events.
MaximumLogValue	Input	number	Optional	Maximum log value for which to keep events.
LogValueInterval	Input	number	Optional	Delta of log value to be sliced into from min log value and max log value. If not given, then only value
FilterLogValueByChangingDirection	Input	string	Both	d(log value)/dt can be positive and negative. They can be put to different splitters.There are 3 options, ‘Both’, ‘Increase’ and ‘Decrease’ corresponding to d(log value)/dt can be any value, positive only and negative only respectively. Allowed values: [‘Both’, ‘Increase’, ‘Decrease’]
TimeTolerance	Input	number	0	Tolerance in time for the event times to keep. It is used in the case to filter by single value.
LogBoundary	Input	string	Centre	How to treat log values as being measured in the centre of time. There are three options, ‘Centre’, ‘Left’ and ‘Other’. Allowed values: [‘Centre’, ‘Left’, ‘Other’]
LogValueTolerance	Input	number	Optional	Tolerance of the log value to be included in filter. It is used in the case to filter by multiple values.
TitleOfSplitters	Input	string		Title of output splitters workspace and information workspace.
UseParallelProcessing	Input	string	Serial	Use multiple cores to generate events filter by log values. Serial: Use a single core. Good for slow log. Parallel: Use multiple cores. Appropriate for fast log. Allowed values: [‘Serial’, ‘Parallel’]
NumberOfThreads	Input	number	Optional	Number of threads forced to use in the parallel mode.

This algorithm is able to generate event splitters according to user’s requirement for filtering events. The generated time splitters are stored either in a SplittersWorkspace`or a :ref:`MatrixWorkspace. Both of them will be used by algorithm FilterEvents to filter events from an EventWorkspace.

This algorithm is designed as a general-purposed event splitter generator. Combined with FilterEvents, it will replace

Moreover, the time resolution of these two algorithms is microseconds, i.e., the wall time of an (neutron) event. While the original FilterByTime and FilterByLogValue are of the resolution of pulse time. It is also enhanced to process the fast frequency sample logs, which can be even faster than chopper frequencies.

Workspace to store event splitters ¶

An event splitter used in Mantid contains start time, stop time and target workspace. Any data structure that has the above 3 properties can serve as an event splitter. There are two types of output workspaces for storing event splitters that are supported by this algorithm.

Splitters Workspace: It is a TableWorkspace that has 3 columns for start time, stop time and target workspace for events within start time and stop time. This type of workspace is appropriate for the case that the amount of generated event splitters are not huge;
MatrixWorkspace: It uses X-axis to store time stamp in total nanoseconds and Y-axis to store target workspace. For example, x_i, x_i+1 and y_i construct an event filter as start time is x_i, stop time is x_i+1, and target workspace is y_i-th workspace. If y_i is less than 0, then it means that all events between time x_i and x_i+1 will be discarded. This type of workspace is appropriate for the case that the amount of generated event splitters are huge, because processing a MatrixWorkspace is way faster than a TableWorkspace in Mantid.

Functionalities ¶

Here are the types of event filters (i.e., Splitters Workspace) that can be generated by this algorithm:

A filter for one time interval.
A series of filters for multiple continuous time intervals, which have the same length of period. Each of them has an individual workspace index associated. These workspace indices are incremented by 1 from 0 along with their orders in time.
A series of filters for multiple continuous time intervals, which have various lengths of period. Each of them has an individual workspace index associated. These workspace indices are incremented by 1 from 0 along with their order in time.
A filter containing one or multiple time intervals according to a specified log value. Any log value of the time that falls into the selected time intervals is equal or within the tolerance of a user specified value.
A series filters containing one or multiple time intervals according to specified log values incremented by a constant value. Any log value of the time that falls into the selected time intervals is equal or within the tolerance of the log value as v_0 + n x delta_v +/- tolerance_v.

Generate event filters by time ¶

Event filters can be created by defining start time, stop time and time intervals. The three input properties for them are StartTime, StopTime and TimeInterval, respectively.

TimeInterval accepts an array of doubles. If the array size is zero, then there will be one and only splitter will be created from StartTime and StopTime. If the size of the array is one, then all event splitters will have the same duration of time. In general if the array is composed as $t_1, t_2, \cdots, t_n$ , and $T_0$ is the run start time, then the event splitters will have the time boudaries as

$(T_0, T_0+t_1), (T_0+t_1, T_0+t_1+t_2), \cdots, (T_0+\sum_{i=1}^{n-1}t_i, T_0+\sum_{i=1}^nt_i), (T_0+\sum_{i=1}^nt_i, T_0+\sum_{i=1}^nt_i+t_1), \cdots$

until the stop time is reached.

Unit of time ¶

There are three types of units that are supported for time. They are second, nanosecond and percentage of duration from StartTime to StopTime.

Generate event filters by sample log value ¶

The sample log will be divided to intervals as $v_0, v_1, \cdots, v_{i-1}, v_i, v_{i+1}, \cdots$ . All log entries, whose values falls into range $[v_j, v_{j+1})$ , will be assigned to a same workspace group.

About how log value is recorded ¶

SNS DAS records log values upon its changing. The frequency of log sampling is significantly faster than change of the log, i.e., sample environment devices. Therefore, it is reasonable to assume that all the log value changes as step functions.

The option to do interpolation is not supported at this moment.

Comparison to FilterByLogValue ¶

1. If the first log value is within the specified range and the first log time is after run star time, FilterByLogValue assumes that the log value before the first recorded log time is also within range, and thus the first splitter starts from the run star time, while GenerateEventsFilter tends to be more conservative, and thus the first splitter will start from the first log time.

2. FilterByLogValue only filters events at the resolution of pulse time, while GenerateEventsFilter can improve the resolution to 1 microsecond.

Algorithm Parameters and Examples ¶

Here are the introductions to some important parameters (i.e., algorithm’s properties).

Parameter: Centre¶

The input Boolean parameter centre is for filtering by log value(s). If option centre is taken, then for each interval,

starting time = log_time - tolerance_time;
stopping time = log_time - tolerance_time;

It is a shift to left.

Parameter: MinimumLogValue, MaximumLogValue, LogValueTolerance and LogValueInterval¶

These four parameters are used to determine the log value intervals for filtering events.

Double value log ¶

Let user-specified minimum log value to be $L_{min}$ , LogValueTolerance to be $t$ , and LogValueInterval to be $\delta$ , then the log value intervals are

$[L_{min}-t, L_{min}-tol+\delta), [L_{min}-tol+\delta, L_{min}-tol+2\cdot\delta), \cdots$

The default value of LogValueTolerance is LogValueInterval divided by 2.

Integer value log ¶

It is a little bit different for sample log recorded with integer.

MinimumLogValue and MaximumLogValue can be same such that only entries with exacly the same log value will be considered;
If LogValueInterval is not give (i.e., default value is used), then any log enetry with log value larger and equal to MinimumLogValue and smaller and equal to MaximumLogValue will be considered. Be noticed that in the same case for double value log, log entry with value equal to MaximumLogValue will be excluded.

Example: Filter by double log value from $s_0$ to $s_f$ ¶

There are two setup to acquire the same result:

Use single-log-value mode:
- MinimumLogValue = $s_0$
- MaximumLogValue = $s_f$
- LogValueInterval is left to default
Use multiple-log-value mode:
- MinimumLogValue = $s_0$
- MaximumLogValue = $s_f$
- LogValueInterval = $s_f - s_0$
- LogValueTolerance = 0

Usage ¶

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.

The following is a contrived example to show how one would use the algorithm to split up an EventWorkspace by a temperature log. The resulting workspaces would then be fed to FilterEvents for further processing.

ws = Load("CNCS_7860_event.nxs")
# The InformationWorkspace name is mandatory
ws2 = GenerateEventsFilter(ws, InformationWorkspace="info", UnitOfTime="Nanoseconds",
                           Logname="SampleTemp", MinimumLogValue=279.9, MaximumLogValue=279.98,
                           LogValueInterval=0.01)
# The first workspace is the SplittersWorkspace and the second is the InformationWorkspace
print("Number of workspaces = {}".format(len(ws2)))
print("First workspace type = {}".format(ws2[0].id()))
print("Second workspace type = {}".format(ws2[1].id()))
print("Number of columns in first TableWorkspace = {}".format(ws2[0].columnCount()))
print("Number of rows in first TableWorkspace = {}".format(ws2[0].rowCount()))
print("Number of columns in second TableWorkspace = {}".format(ws2[1].columnCount()))
print("Number of rows in second TableWorkspace = {}".format(ws2[1].rowCount()))

Output:

Number of workspaces = 2
First workspace type = TableWorkspace
Second workspace type = TableWorkspace
Number of columns in first TableWorkspace = 3
Number of rows in first TableWorkspace = 6
Number of columns in second TableWorkspace = 2
Number of rows in second TableWorkspace = 9

Categories: Algorithms | Events\EventFiltering

Source ¶

C++ source: GenerateEventsFilter.cpp (last modified: 2017-11-30)

C++ header: GenerateEventsFilter.h (last modified: 2017-09-28)