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

FilterEvents v1¶

../_images/ImageNotFound.png — Enable screenshots using DOCS_SCREENSHOTS in CMake¶

Summary ¶

Filter events from an EventWorkspace to one or multiple target event workspaces according to a series of splitters.

Properties ¶

Name	Direction	Type	Default	Description
InputWorkspace	Input	EventWorkspace	Mandatory	Input event workspace.
SplitterWorkspace	Input	Workspace	Mandatory	Input workspace specifying “splitters”, i.e. time intervals and targets for InputWorkspace filtering.
RelativeTime	Input	boolean	False	Flag indicating whether in SplitterWorkspace the times are absolute or relative. If true, they are relative to either the run start time or, if specified, FilterStartTime.
InformationWorkspace	Input	TableWorkspace		Optional information on each filtering target workspace.
OutputWorkspaceBaseName	Input	string	OutputWorkspace	The base name to use for the output workspaces. An output workspace name is a combination of this and the target specified in SplitterWorkspace. For unfiltered events the workspace name will end with “_unfiltered”.
DescriptiveOutputNames	Input	boolean	False	If selected, the names of the output workspaces will include their time intervals.
GroupWorkspaces	Input	boolean	False	An option to group all the output workspaces. The group name will be OutputWorkspaceBaseName.
OutputWorkspaceIndexedFrom1	Input	boolean	False	If selected, the target index included in the output workspace name will be 1-based.
OutputTOFCorrectionWorkspace	Output	MatrixWorkspace	TOFCorrectWS	Name of the output workspace for TOF correction factor.
SplitSampleLogs	Input	boolean	True	DEPRECATED. All logs will be split.
FilterByPulseTime	Input	boolean	False	If selected, events will be filtered by their pulse time as opposed to full time.
TimeSeriesPropertyLogs	Input	str list		DEPRECATED. All logs will be split.
ExcludeSpecifiedLogs	Input	boolean	True	DEPRECATED. All logs will be split.
FilterStartTime	Input	string		Absolute base time for relative times in SplitterWorkspace. Specify date and UTC time in ISO8601 format, e.g. 2010-09-14T04:20:12.
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		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’]
DBSpectrum	Input	number	Optional	Spectrum (workspace index) for debug purpose.
NumberOutputWS	Output	number		Number of output workspaces after splitting InputWorkspace.
OutputWorkspaceNames	Output	str list		List of output workspace names.
OutputUnfilteredEvents	Input	boolean	False	If selected, unfiltered events will be output.

This algorithm filters events from a single Event Workspace to one or multiple target event workspaces according to the SplitterWorkspace property. The Event Filtering concept page has a detailed introduction to event filtering.

Specifying the splitting strategy ¶

The SplitterWorkspace provides information for splitting the InputWorkspace into target output workspaces. It can have one of three types:

workspace class	units	rel/abs
MatrixWorkspace	seconds	either
`SplittersWorkspace`	nanoseconds	absolute
TableWorkspace	seconds	either

Whether the times in SplitterWorkspace are treated as relative or absolute is dependent on the value of RelativeTime. In the case of RelativeTime=True, the times are relative to the start of the run (in the ws.run()['run_start']) or, if specified, the FilterStartTime. In the case of RelativeTime=False, the times are relative to the GPS epoch.

Both TableWorkspace and SplittersWorkspace have 3 columns, start, stop, and target. MatrixWorkspace has a single spectrum where X-values represent the time boundaries and Y-values represent the target workspace indexes. The Usage examples and Event Filtering concept page have details on creating the SplitterWorkspace by hand. Note that event filtering treats all time intervals as [inclusive,exclusive).

The optional InformationWorkspace is a TableWorkspace for information on splitters.

Unfiltered Events ¶

Some events do not fall into any time-splitting intervals. They are put into a workspace with the name ending with _unfiltered. If OutputUnfilteredEvents=False, this workspace will not be created.

Correcting time neutron was at the sample ¶

When filtering fast logs, the time to filter by is the time that the neutron was at the sample. This can be specified using the CorrectionToSample parameter. Either the user specifies the correction parameter for every pixel, or one is calculated. The correction parameters are applied as

\[TOF_{sample} = TOF_{detector} * scale[detectorID] + shift[detectorID]\]

and stored in the OutputTOFCorrectionWorkspace.

CorrectionToSample="None" applies no correction
CorrectionToSample="Elastic" applies \(shift = 0\) with \(scale = L1/(L1+L2)\) for detectors and \(scale = L1/L_{monitor}\) for monitors
CorrectionToSample="Direct" applies \(scale = 0\) and \(shift = L1 / \sqrt{2 E_{fix} / m_n}\). The value supplied in IncidentEnergy will override the value found in the workspace’s value of Ei.
CorrectionToSample="Indirect" applies \(scale = 1\) and \(shift = -1 * L2 / \sqrt{2 E_{fix} / m_n}\) for detectors. For monitors, uses the same corrections as Elastic.
CorrectionToSample="Customized" applies the correction supplied in the DetectorTOFCorrectionWorkspace.

Filter by pulse time vs. full time ¶

In the case of FilterByPulseTime=True, events will be filtered by pulse time. This is recommended for slow sample environment logs. The algorithm will run faster, but with lower precision. In the case of FilterByPulseTime=False, events will be filtered by full time, i.e. pulse time plus TOF.

Usage ¶

Example - Filtering events 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",
        OutputTOFCorrectionWorkspace='mock', OutputUnfilteredEvents = True)

# 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 events by a user-generated TableWorkspace

import numpy as np
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",
        OutputTOFCorrectionWorkspace='mock',
        RelativeTime=True, OutputUnfilteredEvents = 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()))
    time_roi = tmpws.run().getTimeROI()
    splitters = time_roi.toTimeIntervals()
    for index, splitter in enumerate(splitters, 1):
        times = np.array(splitter, dtype=np.int64) * np.timedelta64(1, 'ns') + np.datetime64('1990-01-01T00:00')
        print("event splitter " + str(index) + ": from " + np.datetime_as_string(times[0], timezone='UTC') + " to " + np.datetime_as_string(times[1], timezone='UTC'))

Output:

workspace tempsplitws3_a has 77580 events
event splitter 1: from 2010-03-25T16:08:37.000000000Z to 2010-03-25T16:10:17.000000000Z
workspace tempsplitws3_b has 0 events
event splitter 1: from 2010-03-25T16:11:57.000000000Z to 2010-03-25T16:13:37.000000000Z
event splitter 2: from 2010-03-25T16:18:37.000000000Z to 2010-03-25T16:19:27.000000000Z
workspace tempsplitws3_c has 0 events
event splitter 1: from 2010-03-25T16:15:17.000000000Z to 2010-03-25T16:18:37.000000000Z
workspace tempsplitws3_unfiltered has 34686 events
event splitter 1: from 2010-03-25T16:10:17.000000000Z to 2010-03-25T16:11:57.000000000Z
event splitter 2: from 2010-03-25T16:13:37.000000000Z to 2010-03-25T16:15:17.000000000Z

Example - Filtering events by a user-generated MatrixWorkspace

import numpy as np
ws = Load(Filename='CNCS_7860_event.nxs')

# create MatrixWorkspace. Use -1 as a target for unfiltered events.
times = [0, 100, 200, 300, 400, 600, 650]
targets = [0, -1, 1, -1, 2, 1]
split_matrix_ws = CreateWorkspace(DataX=times, DataY=targets, NSpec=1)

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

# print result
wsgroup = mtd["tempsplitws4"]
wsnames = wsgroup.getNames()
for name in sorted(wsnames):
    tmpws = mtd[name]
    print("workspace %s has %d events" % (name, tmpws.getNumberEvents()))
    time_roi = tmpws.run().getTimeROI()
    splitters = time_roi.toTimeIntervals()
    for index, splitter in enumerate(splitters, 1):
        times = np.array(splitter, dtype=np.int64) * np.timedelta64(1, 'ns') + np.datetime64('1990-01-01T00:00')
        print("event splitter " + str(index) + ": from " + np.datetime_as_string(times[0], timezone='UTC') + " to " + np.datetime_as_string(times[1], timezone='UTC'))

Output:

workspace tempsplitws4_0 has 77580 events
event splitter 1: from 2010-03-25T16:08:37.000000000Z to 2010-03-25T16:10:17.000000000Z
workspace tempsplitws4_1 has 0 events
event splitter 1: from 2010-03-25T16:11:57.000000000Z to 2010-03-25T16:13:37.000000000Z
event splitter 2: from 2010-03-25T16:18:37.000000000Z to 2010-03-25T16:19:27.000000000Z
workspace tempsplitws4_2 has 0 events
event splitter 1: from 2010-03-25T16:15:17.000000000Z to 2010-03-25T16:18:37.000000000Z
workspace tempsplitws4_unfiltered has 34686 events
event splitter 1: from 2010-03-25T16:10:17.000000000Z to 2010-03-25T16:11:57.000000000Z
event splitter 2: from 2010-03-25T16:13:37.000000000Z to 2010-03-25T16:15:17.000000000Z

Example - Filtering events 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",
    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 events 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",
    OutputTOFCorrectionWorkspace='mock',
    OutputUnfilteredEvents = True)

# 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: AlgorithmIndex | Events\EventFiltering