Commit f6023441 authored by Peterson, Peter's avatar Peterson, Peter
Browse files

Moving various bits of documentation from the wiki to sphinx

parent df2af8c8
......@@ -9,29 +9,34 @@
Description
-----------
This algorithm filters events from an
:ref:`EventWorkspace <EventWorkspace>` to one or multiple
:ref:`EventWorkspaces <EventWorkspace>` according to an input
`SplittersWorkspace <http://www.mantidproject.org/SplittersWorkspace>`_ containing a series of
splitters (i.e., `SplittingIntervals <http://www.mantidproject.org/SplittingInterval>`_).
This algorithm filters events from an :ref:`EventWorkspace` to one or
multiple :ref:`EventWorkspaces <EventWorkspace>` according to an input
:ref:`SplittersWorkspace` containing a series of splitters (i.e.,
:ref:`splitting intervals <SplittingInterval>`).
Inputs
######
Algorithm *FilterEvents* takes 2 mandatory input Workspaces and 1 optional Workspace.
One of mandatory workspace is the EventWorkspace where the events are filtered from.
The other mandatory workspace is workspace containing splitters.
It can be either a MatrixWorkspace or a SplittersWorkspace.
The optional workspace is a TableWorkspace for information of splitters.
FilterEvents takes 2 mandatory input Workspaces and 1 optional
Workspace. One of mandatory workspace is the :ref:`EventWorkspace`
where the events are filtered from. The other mandatory workspace is
workspace containing splitters. It can be either a MatrixWorkspace or
a :ref:`SplittersWorkspace <SplittersWorkspace>`.
Algorithm *GenerateEventsFilter* creates both the splitters' workspace and splitter information workspace.
The optional workspace is a :ref:`TableWorkspace <Table Workspaces>`
for information of splitters.
Algorithm :ref:`GenerateEventsFilter <algm-GenerateEventsFilter>`
creates both the :ref:`SplittersWorkspace <SplittersWorkspace>` and
splitter information workspace.
Splitters in relative time
==========================
As the splitters' workspace is in format of MatrixWorkspace,
its time, i.e., the value in X vector, can be relative time.
As the SplittersWorkspace is in format of :ref:`MatrixWorkspace
<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.
......@@ -86,30 +91,30 @@ Therefore, FilterByLogValue is not suitable for fast log filtering.
Comparing with other event filtering algorithms
###############################################
Wiki page `EventFiltering <http://www.mantidproject.org/EventFiltering>`__ has a detailed
introduction on event filtering in MantidPlot.
Wiki page :ref:`EventFiltering` has a detailed introduction on event
filtering in MantidPlot.
Usage
-----
**Example - Filtering event without correction on TOF**
**Example - Filtering event without correction on TOF**
.. testcode:: FilterEventNoCorrection
ws = Load(Filename='CNCS_7860_event.nxs')
splitws, infows = GenerateEventsFilter(InputWorkspace=ws, UnitOfTime='Nanoseconds', LogName='SampleTemp',
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,
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):
for name in sorted(wsnames):
tmpws = mtd[name]
print "workspace %s has %d events" % (name, tmpws.getNumberEvents())
......@@ -127,30 +132,30 @@ Output:
workspace tempsplitws_unfiltered has 50603 events
**Example - Filtering event by pulse time**
**Example - Filtering event by pulse time**
.. testcode:: FilterEventByPulseTime
ws = Load(Filename='CNCS_7860_event.nxs')
splitws, infows = GenerateEventsFilter(InputWorkspace=ws, UnitOfTime='Nanoseconds', LogName='SampleTemp',
splitws, infows = GenerateEventsFilter(InputWorkspace=ws, UnitOfTime='Nanoseconds', LogName='SampleTemp',
MinimumLogValue=279.9, MaximumLogValue=279.98, LogValueInterval=0.01)
FilterEvents(InputWorkspace=ws,
SplitterWorkspace=splitws,
FilterEvents(InputWorkspace=ws,
SplitterWorkspace=splitws,
InformationWorkspace=infows,
OutputWorkspaceBaseName='tempsplitws',
GroupWorkspaces=True,
FilterByPulseTime = True,
OutputWorkspaceBaseName='tempsplitws',
GroupWorkspaces=True,
FilterByPulseTime = True,
OutputWorkspaceIndexedFrom1 = True,
CorrectionToSample = "None",
SpectrumWithoutDetector = "Skip",
CorrectionToSample = "None",
SpectrumWithoutDetector = "Skip",
SplitSampleLogs = False,
OutputTOFCorrectionWorkspace='mock')
OutputTOFCorrectionWorkspace='mock')
# Print result
wsgroup = mtd["tempsplitws"]
wsnames = wsgroup.getNames()
for name in sorted(wsnames):
for name in sorted(wsnames):
tmpws = mtd[name]
print "workspace %s has %d events" % (name, tmpws.getNumberEvents())
......@@ -167,29 +172,29 @@ Output:
workspace tempsplitws_6 has 5067 events
**Example - Filtering event with correction on TOF**
**Example - Filtering event with correction on TOF**
.. testcode:: FilterEventTOFCorrection
ws = Load(Filename='CNCS_7860_event.nxs')
splitws, infows = GenerateEventsFilter(InputWorkspace=ws, UnitOfTime='Nanoseconds', LogName='SampleTemp',
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,
OutputWorkspaceBaseName='tempsplitws',
GroupWorkspaces=True,
FilterByPulseTime = False,
OutputWorkspaceIndexedFrom1 = False,
CorrectionToSample = "Direct",
CorrectionToSample = "Direct",
IncidentEnergy=3,
SpectrumWithoutDetector = "Skip",
SpectrumWithoutDetector = "Skip",
SplitSampleLogs = False,
OutputTOFCorrectionWorkspace='mock')
# Print result
wsgroup = mtd["tempsplitws"]
wsnames = wsgroup.getNames()
for name in sorted(wsnames):
for name in sorted(wsnames):
tmpws = mtd[name]
print "workspace %s has %d events" % (name, tmpws.getNumberEvents())
......
.. _EventFiltering:
===============
Event Filtering
===============
.. contents::
:local:
In MantidPlot, there are a few algorithms working with event
filtering. These algorithms are :ref:`algm-FilterByTime`,
:ref:`algm-FilterByLogValue`, :ref:`algm-FilterEvents`, and
:ref:`algm-GenerateEventsFilter`.
How to generate event filters
=============================
Generating filters explicitly
-----------------------------
:ref:`algm-FilterEvents` reads and parses a :ref:`SplittersWorkspace`
object to generate a list of :ref:`SplittingIntervals
<SplittingInterval>`, which are used to split neutron events to
specified output workspaces according to the times that they arrive
detectors.
There can be two approaches to create a :ref:`SplittersWorkspace`.
* :ref:`algm-GenerateEventsFilter` generate event filters by either by
time or log value. The output filters are stored in a
:ref:`SplittersWorkspace`, which is taken as an input property of
:ref:`algm-FilterEvents`.
* Users can create a :ref:`SplittersWorkspace` from scrach from Python
script, because :ref:`SplittersWorkspace` inherits from
:ref:`TableWorkspace <Table Workspaces>`.
Generating inexplicit filters
-----------------------------
:ref:`algm-FilterByTime` and :ref:`algm-FilterByLogValue` generate event filters during execution.
* :ref:`algm-FilterByTime` generates a set of :ref:`SplittingInterval`
according to user-specified setup for time splicing;
* :ref:`algm-FilterByLogValue` generates a set of
:ref:`SplittingInterval` according to the value of a specific sample
log.
:ref:`algm-GenerateEventsFilter` and :ref:`algm-FilterEvents` vs :ref:`algm-FilterByTime` and :ref:`algm-FilterByLogValue`
--------------------------------------------------------------------------------------------------------------------------
* If :ref:`algm-GenerateEventsFilter` and :ref:`algm-FilterEvents` are
set up correctly, they can have the same functionality as
:ref:`algm-FilterByTime` and :ref:`algm-FilterByLogValue`.
* :ref:`algm-FilterEvents` is able to filter neutron events by either
their pulse times or their absolute times. An neutron event's
abolute time is the summation of its pulse time and TOF.
* :ref:`algm-FilterByLogValue` and :ref:`algm-FilterByTime` can only
split neutron events by their pulse time.
Types of events filters
=======================
Filtering by :ref:`SplittingInterval`
-------------------------------------
:ref:`SplittingInterval` is an individual class to indicate an
independent time splitter. Any event can be filtered by a
:ref:`SplittingInterval` object.
:ref:`SplittersWorkspace` is a :ref:`TableWorkspace <Table
Workspaces>` that stors a set of :ref:`SplittingInterval`.
Filtering by duplicate entries/booleans
---------------------------------------
Duplicate entries in a :ref:`TimeSeriesProperty` and boolean type of
:ref:`TimeSeriesProperty` are used in MantidPlot too to serve as time
splitters.
These two are applied in the MantidPlot log viewing functionality and
unfortunately intrudes into :ref:`TimeSeriesProperty`.
As time splitters are better to be isolated from logs, which are
recorded in :ref:`TimeSeriesProperty`, it is not
recommended to set up event filters by this approach.
.. _SplittersWorkspace:
===================
Splitters Workspace
===================
.. contents::
:local:
SplittersWorkspaces stores a vector of SplittingIntervals. It
inherits from :ref:`TableWorkspace <Table Workspaces>`.
A SplittersWorkspace object has 3 columns, ``start`` with type as
``int64``, ``stop`` with type as ``int64`` and ``workspacegroup`` as
``int``. Column ``start`` is to record the starting absolute time
(DateTime reference!) of a TimeSplitter. Column ``stop`` is to record
the stopping absolute time of a :ref:`SplittingInterval`. Column
``workspacegroup`` is to record what workspace should the events fall
into the time period defined by ``start`` and ``stop``.
.. _SplittingInterval:
Splitting Interval
------------------
SplittingInterval is a class to store and process the event splitting
information. It stores and returns the starting and stopping time of a
time-splitter. Each SplitterInterval will have an 'index'. The 'index'
(starting from zero) denotes which workspace to which any neutron
event falls into its time interval will be copied. An 'index' of -1 to
not filter the events.
.. _TimeSeriesProperty:
==================
TimeSeriesProperty
==================
A TimeSeriesProperty is a specialised [[Property]] class that holds time/value pairs. It offers a selection of statistics through it's Python interface which you can use in your scripts.
Introduction
============
To get hold of a time series property, you need to get the handle to the object from the [[Run]] object.
To get the statistics object, you then call <code>getStatistics()</code> on the property.
This allows you to access the following attributes:
* minimum
* maximum
* mean
* median
* standard_deviation
* duration
Functions
=========
``filterWith()``
----------------
**Handling boundary condition**
Definition: ``log_t0``, ``log_tf``, ``filter_t0``, ``filter_tf``
* Beginning of the filter
* If ``filter_t0`` < `log_t0``, then the log is extended to ``filter_t0``
* If ``filter_t0`` > ``log_t0``, all logs before first occurrence of False in filter are in the prohibited region.
It is to say that the first entry of a log starts from the first occurrence of TRUE value.
* End of the filter
* If ``filter_tf`` > ``log_tf``, and ``filter_tf`` is false, the (virtual) filtered log is extended by all filter entries beyond ``log_tf``;
* If ``filter_tf`` < `log_tf``, and last filter entry is false, then all entries of the log after ``filter_tf`` are in the disallowed region;
``nthInterval(n)``
------------------
Return the nth interval
* An interval starts from filter's time.
* If the starting filter time is not same as any log entry, then from this filter time to the log entry just behind it will be an interval.
* An interval ends at filter's time if there is a filter value change between this log entry and its next log entry;
* An interval can go beyond real log.
* If it is the last interval, dt is estimated from either previous log entry or previous (false) filter entry, which is later in time.
``nthValue(n)``
---------------
Return the value of nth interval.
* If the interval starts from a filter time, then the value is either
* the log value just before the filter time if filter time is not ahead all log entries' time or
* the value of first log entry
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment