diff --git a/docs/source/algorithms/FilterEvents-v1.rst b/docs/source/algorithms/FilterEvents-v1.rst
index d64878f29f26c3d8911b05c1f882774c6a840ac7..40a591c7faadcc61e7fd3300382db3e7a858f55c 100644
--- a/docs/source/algorithms/FilterEvents-v1.rst
+++ b/docs/source/algorithms/FilterEvents-v1.rst
@@ -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())
diff --git a/docs/source/api/python/mantid/api/ISplittersWorkspace.rst b/docs/source/api/python/mantid/api/ISplittersWorkspace.rst
new file mode 100644
index 0000000000000000000000000000000000000000..bc93bcc162071178babdaa4af3865c9bf151ff80
--- /dev/null
+++ b/docs/source/api/python/mantid/api/ISplittersWorkspace.rst
@@ -0,0 +1,33 @@
+.. _SplittersWorkspace:
+
+===================
+Splitters Workspace
+===================
+
+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.
+
+.. autoclass:: mantid.api.ISplittersWorkspace
+ :members:
+ :undoc-members:
+ :inherited-members:
diff --git a/docs/source/api/python/mantid/kernel/TimeSeriesProperty.rst b/docs/source/api/python/mantid/kernel/TimeSeriesProperty.rst
new file mode 100644
index 0000000000000000000000000000000000000000..82a4ffe9fc87e82bcbb16a846997f268f330e332
--- /dev/null
+++ b/docs/source/api/python/mantid/kernel/TimeSeriesProperty.rst
@@ -0,0 +1,75 @@
+.. _TimeSeriesProperty:
+
+==================
+TimeSeriesProperty
+==================
+
+A TimeSeriesProperty is a specialised :class:`mantid.kernel.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 :class:`mantid.api.Run` object.
+
+To get the :class:`mantid.kernel.TimeSeriesPropertyStatistics` object,
+you then call ``getStatistics()`` 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
diff --git a/docs/source/concepts/EventFiltering.rst b/docs/source/concepts/EventFiltering.rst
new file mode 100644
index 0000000000000000000000000000000000000000..f5a852a34c454fe6ccd21dec289d1d9c2a2c3f63
--- /dev/null
+++ b/docs/source/concepts/EventFiltering.rst
@@ -0,0 +1,90 @@
+.. _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
+:class:`mantid.api.ISplittersWorkspace` 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
+:class:`mantid.api.ISplittersWorkspace`.
+
+* :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 :class:`mantid.api.ISplittersWorkspace` from scrach from Python
+ script, because :class:`mantid.api.ISplittersWorkspace` 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.