\(\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.

See Also

GenerateEventsFilter, FilterByTime, FilterByLogValue

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.

Description

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

Source

C++ header: FilterEvents.h

C++ source: FilterEvents.cpp