Moving various bits of documentation from the wiki to sphinx

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())
 

docs/source/concepts/EventFiltering.rst

+.. _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.

docs/source/concepts/SplittersWorkspace.rst

+.. _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.

docs/source/concepts/TimeSeriesProperty.rst

+.. _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