FilterEvents v1¶

FilterEvents dialog.

Table of Contents

Summary
Properties
Description
Developer’s Note
- Splitters given by TableWorkspace
- Undefined splitting target
Usage
Source

Summary ¶

Filter events from an EventWorkspace to one or multiple EventWorkspaces according to a series of splitters.

Properties ¶

Name	Direction	Type	Default	Description
InputWorkspace	Input	EventWorkspace	Mandatory	An input event workspace
SplitterWorkspace	Input	Workspace	Mandatory	An input SpilltersWorskpace for filtering
OutputWorkspaceBaseName	Input	string	OutputWorkspace	The base name to use for the output workspace
InformationWorkspace	Input	TableWorkspace		Optional output for the information of each splitter workspace index.
OutputTOFCorrectionWorkspace	Output	MatrixWorkspace	TOFCorrectWS	Name of output workspace for TOF correction factor.
FilterByPulseTime	Input	boolean	False	Filter the event by its pulse time only for slow sample environment log. This option can make execution of algorithm faster. But it lowers precision.
GroupWorkspaces	Input	boolean	False	Option to group all the output workspaces. Group name will be OutputWorkspaceBaseName.
OutputWorkspaceIndexedFrom1	Input	boolean	False	If selected, the minimum output workspace is indexed from 1 and continuous.
CorrectionToSample	Input	string	None	Type of correction on neutron events to sample time from detector time. Allowed values: [‘None’, ‘Customized’, ‘Direct’, ‘Elastic’, ‘Indirect’]
DetectorTOFCorrectionWorkspace	Input	TableWorkspace		Name of table workspace containing the log time correction factor for each detector.
IncidentEnergy	Input	number	Optional	Value of incident energy (Ei) in meV in direct mode.
SpectrumWithoutDetector	Input	string	Skip	Approach to deal with spectrum without detectors. Allowed values: [‘Skip’, ‘Skip only if TOF correction’]
SplitSampleLogs	Input	boolean	True	If selected, all sample logs will be splitted by the event splitters. It is not recommended for fast event log splitters.
NumberOutputWS	Output	number		Number of output output workspace splitted.
DBSpectrum	Input	number	Optional	Spectrum (workspace index) for debug purpose.
OutputWorkspaceNames	Output	str list		List of output workspaces names
RelativeTime	Input	boolean	False	Flag to indicate that in the input Matrix splitting workspace,the time indicated by X-vector is relative to either run start time or some indicted time.
FilterStartTime	Input	string		Start time for splitters that can be parsed to DateAndTime.
TimeSeriesPropertyLogs	Input	str list		List of name of sample logs of TimeSeriesProperty format. They will be either excluded from splitting if ExcludedSpecifiedLogs is specified as True. Or They will be the only TimeSeriesProperty sample logs that will be split to child workspaces.
ExcludeSpecifiedLogs	Input	boolean	True	If true, all the TimeSeriesProperty logs listed will be excluded from duplicating. Otherwise, only those specified logs will be split.

Description ¶

This algorithm filters events from an Event Workspace to one or multiple EventWorkspaces according to an input Splitters Workspace containing a series of splitters (i.e., splitting intervals).

FilterEvents takes 2 mandatory input Workspaces and 1 optional Workspace. One of mandatory workspace is the Event Workspace where the events are filtered from. The other mandatory workspace is workspace containing splitters. It can be a MatrixWorkspace, a TableWorkspace or a SplittersWorkspace.

The optional workspace is a TableWorkspace for information of splitters.

Workspace containing splitters ¶

This algorithm accepts three types of workspace that contains event splitters. - TableWorkspace: a general TableWorkspace with at three columns - MatrixWorkspace: a 1-spectrum MatrixWorkspace - SplittersWorkspace: an extended TableWorkspace with restrict definition on start and stop time.

Event splitter ¶

An event splitter contains three items, start time, stop time and splitting target (index). All the events belonged to the same splitting target will be saved to a same output EventWorkspace.

Unit of input splitters ¶

MatrixWorkspace: the unit must be second.
TableWorkspace: the unit must be second.
SplittersWorkspace: by the definition of SplittersWorkspace, the unit has to be nanosecond.

How to generate input workspace containing splitters ¶

There are two ways to generate

Algorithm GenerateEventsFilter creates both the SplittersWorkspace and splitter information workspace.

Splitters in relative time or absolute time ¶

As the SplittersWorkspace is in format of MatrixWorkspace, its time, i.e., the value in X vector, can be relative time.

Property RelativeTime flags that the splitters’ time is relative. Property FilterStartTime specifies the starting time of the filter. Or the shift of time of the splitters. If it is not specified, then the algorithm will search for sample log run_start.

Outputs ¶

The output will be one or multiple workspaces according to the number of index in splitters. The output workspace name is the combination of parameter OutputWorkspaceBaseName and the index in splitter.

Calibration File ¶

The calibration, or say correction, from the detector to sample must be consider in fast log. Thus a calibration file is required. The math is

TOF_calibrated = TOF_raw * correction(detector ID).

The calibration is in column data format.

A reasonable approximation of the correction is

correction(detector_ID) = L1/(L1+L2(detector_ID))

Unfiltered Events ¶

Some events are not inside any splitters. They are put to a workspace name ended with ‘_unfiltered’.

If input property ‘OutputWorkspaceIndexedFrom1’ is set to True, then this workspace shall not be outputed.

Difference from FilterByLogValue ¶

In FilterByLogValue(), EventList.splitByTime() is used.

In FilterEvents, if FilterByPulse is selected true, EventList.SplitByTime is called; otherwise, EventList.SplitByFullTime() is called instead.

The difference between splitByTime and splitByFullTime is that splitByTime filters events by pulse time, and splitByFullTime considers both pulse time and TOF.

Therefore, FilterByLogValue is not suitable for fast log filtering.

The start/stop time is converted to m_vecSplitterTime.
The splitting target (in string) is mapped to a set of continuous integers that are stored in m_vecSplitterGroup. - The mapping will be recorded in m_targetIndexMap and m_wsGroupIndexTargetMap. - Class variable m_maxTargetIndex is set up to record the highest target group/index,i.e., the max value of m_vecSplitterGroup.

Undefined splitting target ¶

Indexed as 0 in m_vecSplitterGroup.

Usage ¶

Example - Filtering event without correction on TOF

ws = Load(Filename='CNCS_7860_event.nxs')
splitws, infows = GenerateEventsFilter(InputWorkspace=ws, UnitOfTime='Nanoseconds', LogName='SampleTemp',
        MinimumLogValue=279.9,  MaximumLogValue=279.98, LogValueInterval=0.01)

FilterEvents(InputWorkspace=ws, SplitterWorkspace=splitws, InformationWorkspace=infows,
        OutputWorkspaceBaseName='tempsplitws',  GroupWorkspaces=True,
        FilterByPulseTime = False, OutputWorkspaceIndexedFrom1 = False,
        CorrectionToSample = "None", SpectrumWithoutDetector = "Skip", SplitSampleLogs = False,
        OutputTOFCorrectionWorkspace='mock')

# Print result
wsgroup = mtd["tempsplitws"]
wsnames = wsgroup.getNames()
for name in sorted(wsnames):
    tmpws = mtd[name]
    print "workspace %s has %d events" % (name, tmpws.getNumberEvents())

Output:

workspace tempsplitws_0 has 124 events
workspace tempsplitws_1 has 16915 events
workspace tempsplitws_2 has 10009 events
workspace tempsplitws_3 has 6962 events
workspace tempsplitws_4 has 22520 events
workspace tempsplitws_5 has 5133 events
workspace tempsplitws_unfiltered has 50603 events

Example - Filtering event by a user-generated TableWorkspace

ws = Load(Filename='CNCS_7860_event.nxs')

# create TableWorkspace
split_table_ws = CreateEmptyTableWorkspace()
split_table_ws.addColumn('float', 'start')
split_table_ws.addColumn('float', 'stop')
split_table_ws.addColumn('str', 'target')

split_table_ws.addRow([0., 100., 'a'])
split_table_ws.addRow([200., 300., 'b'])
split_table_ws.addRow([400., 600., 'c'])
split_table_ws.addRow([600., 650., 'b'])

# filter events
FilterEvents(InputWorkspace=ws, SplitterWorkspace=split_table_ws,
        OutputWorkspaceBaseName='tempsplitws3',  GroupWorkspaces=True,
        FilterByPulseTime = False, OutputWorkspaceIndexedFrom1 = False,
        CorrectionToSample = "None", SpectrumWithoutDetector = "Skip", SplitSampleLogs = False,
        OutputTOFCorrectionWorkspace='mock',
        RelativeTime=True)

# Print result
wsgroup = mtd["tempsplitws3"]
wsnames = wsgroup.getNames()
for name in sorted(wsnames):
    tmpws = mtd[name]
    print "workspace %s has %d events" % (name, tmpws.getNumberEvents())
    split_log = tmpws.run().getProperty('splitter')
    print 'event splitter log: entry 0 and entry 1 are {0} and {1}.'.format(split_log.times[0], split_log.times[1])

Output:

workspace tempsplitws3_a has 77580 events
event splitter log: entry 0 and entry 1 are 2010-03-25T16:08:37  and 2010-03-25T16:10:17 .
workspace tempsplitws3_b has 0 events
event splitter log: entry 0 and entry 1 are 2010-03-25T16:08:37  and 2010-03-25T16:11:57 .
workspace tempsplitws3_c has 0 events
event splitter log: entry 0 and entry 1 are 2010-03-25T16:08:37  and 2010-03-25T16:15:17 .
workspace tempsplitws3_unfiltered has 34686 events
event splitter log: entry 0 and entry 1 are 2010-03-25T16:08:37  and 2010-03-25T16:10:17 .

Example - Filtering event by pulse time

ws = Load(Filename='CNCS_7860_event.nxs')
splitws, infows = GenerateEventsFilter(InputWorkspace=ws, UnitOfTime='Nanoseconds', LogName='SampleTemp',
        MinimumLogValue=279.9,  MaximumLogValue=279.98, LogValueInterval=0.01)

FilterEvents(InputWorkspace=ws,
    SplitterWorkspace=splitws,
    InformationWorkspace=infows,
    OutputWorkspaceBaseName='tempsplitws',
    GroupWorkspaces=True,
    FilterByPulseTime = True,
    OutputWorkspaceIndexedFrom1 = True,
    CorrectionToSample = "None",
    SpectrumWithoutDetector = "Skip",
    SplitSampleLogs = False,
    OutputTOFCorrectionWorkspace='mock')

# Print result
wsgroup = mtd["tempsplitws"]
wsnames = wsgroup.getNames()
for name in sorted(wsnames):
    tmpws = mtd[name]
    print "workspace %s has %d events" % (name, tmpws.getNumberEvents())

Output:

workspace tempsplitws_1 has 123 events
workspace tempsplitws_2 has 16951 events
workspace tempsplitws_3 has 9972 events
workspace tempsplitws_4 has 7019 events
workspace tempsplitws_5 has 22529 events
workspace tempsplitws_6 has 5067 events

Example - Filtering event with correction on TOF

ws = Load(Filename='CNCS_7860_event.nxs')
splitws, infows = GenerateEventsFilter(InputWorkspace=ws, UnitOfTime='Nanoseconds', LogName='SampleTemp',
        MinimumLogValue=279.9,  MaximumLogValue=279.98, LogValueInterval=0.01)

FilterEvents(InputWorkspace=ws, SplitterWorkspace=splitws, InformationWorkspace=infows,
    OutputWorkspaceBaseName='tempsplitws',
    GroupWorkspaces=True,
    FilterByPulseTime = False,
    OutputWorkspaceIndexedFrom1 = False,
    CorrectionToSample = "Direct",
    IncidentEnergy=3,
    SpectrumWithoutDetector = "Skip",
    SplitSampleLogs = False,
    OutputTOFCorrectionWorkspace='mock')

# Print result
wsgroup = mtd["tempsplitws"]
wsnames = wsgroup.getNames()
for name in sorted(wsnames):
    tmpws = mtd[name]
    print "workspace %s has %d events" % (name, tmpws.getNumberEvents())

Output:

workspace tempsplitws_0 has 123 events
workspace tempsplitws_1 has 16951 events
workspace tempsplitws_2 has 9972 events
workspace tempsplitws_3 has 7019 events
workspace tempsplitws_4 has 22514 events
workspace tempsplitws_5 has 5082 events
workspace tempsplitws_unfiltered has 50605 events

Categories: Algorithms | Events\EventFiltering