\(\renewcommand\AA{\unicode{x212B}}\)
GenerateEventsFilter v1¶
Summary¶
Generate one or a set of event filters according to time or specified log’s value.
See Also¶
Properties¶
Name 
Direction 
Type 
Default 
Description 

InputWorkspace 
Input 
Mandatory 
An input Matrix workspace. 

OutputWorkspace 
Output 
Mandatory 
The name to use for the output SplittersWorkspace object, ie the filter. 

InformationWorkspace 
Output 
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’ (2) absolute time Absolute time takes a string in format as 19900101T00:00:00, while the relative time takes a string representing an integer or a floatingpoint number. 

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’ (2) absolute time Absolute time takes a string in format as 19900101T00:00:00, while the relative time takes a string representing an integer or a floatingpoint number. 

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 if this value is positive, all splitters will have same time intervals, else the time intervals will be exponentially increasing; if the size of the array is larger than one, then the splitters can have various time interval values. 

UnitOfTime 
Input 
string 
Seconds 
This option determines the units of options ‘StartTime’, ‘StopTime’ and ‘DeltaTime’. Allowed units are ‘Seconds’ or ‘Nanoseconds’, counting from the run start time, or a ‘Percentage’ of the 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 being any value, positive only and negative only respectively. Allowed values: [‘Both’, ‘Increase’, ‘Decrease’] 
TimeTolerance 
Input 
number 
0 
Tolerance, in seconds, for the event times to keep. It is used in the case to filter by single value. How TimeTolerance is applied is highly correlated to LogBoundary and PulseFilter. Check the help or algorithm documents for details. 
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’. This value must be set to Left if the sample log is recorded upon changing,which applies to most of the sample environment devices in SNS. Allowed values: [‘Centre’, ‘Left’, ‘Other’] 
LogValueTolerance 
Input 
number 
Optional 
Tolerance of the log value to be included in filter, 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. 
UseReverseLogarithmic 
Input 
boolean 
False 
Use reverse logarithm for the time filtering. 
Description¶
This algorithm is able to generate event splitting according to user’s requirements. The generated time splitters are stored either in a Splitters Workspace or a MatrixWorkspace. Either can be used by algorithm FilterEvents to filter an EventWorkspace.
This algorithm is designed as a generalpurposed method for generating event splitting. The time resolution of this two algorithms is microseconds, i.e., the absolute time of the (neutron) event including timeofflight. In contrast, FilterByTime and FilterByLogValue only consider the pulse time. The extra time resolution is necessary to process the fast frequency sample logs, which can be faster than chopper frequencies.
Input Workspace¶
This algorithm mainly uses the information retrieved from sample logs to create event splitters. Therefore, EventWorkspace is only required if the run end time cannot be determined by sample logs. For example, proton charge log cannot be found.
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 Xaxis to store time stamp in total nanoseconds and Yaxis 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 an exponentially increasing length, or exponentially decreasing length. 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 \cdot \Delta_{v} \pm 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 if the value is positive, all event splitters will have the same duration.
If it is negative, the event splitters duration will exponentially increase (if UseReverseLogarithmic
is unchecked)
or exponentially decrease (if UseReverseLogarithmic
is checked).
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 boundaries as
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_{i1}, 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: LogBoundary
¶
The input string parameter LogBoundary
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.
Logs that only record changes
In SNS, most of the sample environment devices record values upon changing.
Therefore, the LogBoundary
value shall set to Left
but not Centre
.
And in this case, TimeTolerance
is ignored.
Please check with the instrument scientist to confirm how the sample log values are recorded.
Here is an example how the time splitter works with the a motor’s position.
Time Tolerance and Log Boundary¶
How TimeTolerance
is applied in this algorithm is similar to that in FilterByLogValue
except that this algorithm does not support PulseFilter
.
If
LogBoundary
isLeft
,TimeTolerance
is ignored in the algorithm.If
LogBoundary
is set toCentre
, assuming the log entries are(t0, v0), (t1, v1), (t2, v2), (t3, v3), ... (t_n, v_n) ...
.If there is a log entry
(t_i, v_i)
is betweenMinimumValue
andMaximumValue
, whilev_{i1}
andv_{i+1}
are not in the desired log value range, all events betweent_i  TimeTolerance
andt_i + TimeTolerance)
are kept.If there are several consecutive log entries that have values in the desired log value range, such as
(t_i, v_i), ..., (t_j, v_j)
, events betweent_i  TimeTolerance
andt_j + TimToleranc
are kept.
A good value is 1/2 your measurement interval if the intervals are constant.
Parameter: FastLog
¶
When FastLog
is set to True, a MatrixWorkspace will be used to store the event
splitters, which is more appropriate for fast changing logs. (see above for details).
Parameter: UseReverseLogarithmic
¶
When UseReverseLogarithmic
is checked, if only one TimeInterval
value has been provided and it is negative,
the logarithmic time splitting will start from the end of the run going back to the start, resulting in time splits
shorter and shorter. The bin widths correspond to those that would have been generated by the log binning algorithm,
except they are reverted  ie the last, biggest log bin comes first, etc ….
The bins are always in decreasing order of width, so the first bin might be merged with the second one if it is incomplete.
Parameter: MinimumLogValue
, MaximumLogValue
, LogValueTolerance
and LogValueInterval
¶
These four parameters are used to determine the log value intervals for filtering events.
Double value log¶
Let userspecified minimum log value to be \(L_{\text{min}}\), LogValueTolerance to be \(t\), and LogValueInterval to be \(\delta\), then the log value intervals are
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
andMaximumLogValue
can be same such that only entries with exactly 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 toMinimumLogValue
and smaller and equal toMaximumLogValue
will be considered. Be noticed that in the same case for double value log, log entry with value equal toMaximumLogValue
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 singlelogvalue mode:
MinimumLogValue = \(s_0\)
MaximumLogValue = \(s_f\)
LogValueInterval is left to default
Use multiplelogvalue 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 Mantid this is done using Manage User Directories.
Example  Generate event filter by temperature value
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
Example  Generate event filter by temperature value with an empty workspace
The following is a contrived example to show how one would use the algorithm to generate event splitters from an empty workspace, which has sample logs in run object, by a temperature log. The resulting workspaces would then be fed to FilterEvents for further processing.
ws = CreateWorkspace(DataX=[0], DataY=[0], NSpec=1, OutputWorkspace='ws')
ws = LoadNexusLogs(ws, "CNCS_7860_event.nxs")
# The InformationWorkspace name is mandatory
ws2 = GenerateEventsFilter(InputWorkspace='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: AlgorithmIndex  Events\EventFiltering
Source¶
C++ header: GenerateEventsFilter.h
C++ source: GenerateEventsFilter.cpp