Refs ED #70. Improved the doc on event filter setup.

docs/source/algorithms/FilterByLogValue-v1.rst

@@ -43,6 +43,25 @@ the range, then all events will be kept.
    :ref:`FilterByLogValue <algm-FilterByLogValue>` is not suitable for
    fast log filtering.
 
+
+For SNS Users
+#############
+
+In SNS, most of the sample environment devices record values upon changing.
+Therefore, the **LogBoundary** value shall set to **Left** but not **Centre**.
+And in this case, **TimeTolerance** is ignored.
+
+Please check with the instrument scientist to confirm how the sample log values are recorded.
+
+Here is an example how the time splitter works with the a motor's position.
+
+.. figure:: /images/SNAP_motor_filter.png
+
+        For this SNAP run, the user wants to filter events with motor (BL3:Mot:Hexa:MotZ) position
+        at value equal to 6.65 with tolerance as 0.1.
+        The red curve shows the boundary of the time splitters (i.e., event filters).
+
+
 PulseFilter (e.g. for Veto Pulses)
 ##################################
 
@@ -79,13 +98,71 @@ rejected. For example, this call will filter out veto pulses:
 
    ws = FilterByLogValue(ws, LogName="veto_pulse_time", PulseFilter="1")
 
-Comparing with other event filtering algorithms
-###############################################
+
+Comparing with GenerateEventsFilter/FilterEvents
+################################################
+
+The combination of :ref:`GenerateEventsFilter <algm-GenerateEventsFilter>` and :ref:`FilterEvents <algm-FilterEvents>` with proper configuration
+can produce same result as :ref:`FilterByLogValue`.
+
+For sample,
+
+.. code-block:: python
+
+   from mantid.simpleapi import *
+
+   # Load data
+   LoadEventNexus(Filename='/SNS/SNAP/IPTS-25836/nexus/SNAP_52100.nxs.h5', OutputWorkspace='52100')
+
+   # FilterByLogValue
+   FilterByLogValue(InputWorkspace='52100',
+                    OutputWorkspace='52100_hexaZ_L',
+                    LogName='BL3:Mot:Hexa:MotZ',
+                    MinimumValue= 6.55,
+                    MaximumValue= 6.75,
+                    LogBoundary='Left')
+
+   # Equivalent GenerateEventsFilter/FilterEvents combination
+   GenerateEventsFilter(InputWorkspace='52100',
+                        OutputWorkspace='MotZSplitter_left',
+                        InformationWorkspace='MotZSplitter_left_info',
+                        LogName='BL3:Mot:Hexa:MotZ',
+                        MinimumLogValue=6.55,
+                        MaximumLogValue=6.75,
+                        LogBoundary='Left',
+                        TitleOfSplitters='Left')
+   FilterEvents(InputWorkspace='52100',
+                SplitterWorkspace='MotZSplitter_left',
+                OutputWorkspaceBaseName='Chop52100',
+                InformationWorkspace='MotZSplitter_left_info',
+                FilterByPulseTime=True)
+
+
+
+The OutputWorkspace with name *Chop52100_0* output from :ref:`FilterEvents <algm-FilterEvents>` is equivalent to *52100_hexaZ_L*
+from *FilterByLogValue*.
+
+Here is the comparison between FilterByLogValue and :ref:`GenerateEventsFilter<algm-GenerateEventsFilter>`/:ref:`FilterEvents<algm-FilterEvents>`.
+
+1. *FilterByLogValue* can only filter events at the resolution of neutron pulse.
+
+   - If the start time *t_s* of a splitter is inside a pulse, then all the events inside that pulse but before *t_s*
+     will be included in the filtered workspace.
+   - If the end time *t_e* of a splitter is inside a pulse, then all the events inside that pulse even before *t_e*
+     will be excluded in the filtered workspace.
+   - :ref:`FilterEvents<algm-FilterEvents>` is able to do the filtering precisely to include events only within time range [*t_s*, *t_e*).
+
+2. *FilterByLogValue* can only filter events around only **one** log value, while
+   :ref:`GenerateEventsFilter<algm-GenerateEventsFilter>`/:ref:`FilterEvents<algm-FilterEvents>`
+   combination can filter events against a series of log values.
+
+3. :ref:`GenerateEventsFilter<algm-GenerateEventsFilter>`/:ref:`FilterEvents<algm-FilterEvents>`
+   have more outputs to examine the result.
+
 
 The :ref:`EventFiltering` page has a detailed introduction on event
 filtering in mantid.
 
-
 Usage
 -----
 

docs/source/algorithms/GenerateEventsFilter-v1.rst

@@ -167,17 +167,35 @@ Algorithm Parameters and Examples
 Here are the introductions to some important parameters (i.e., algorithm's properties).
 
 
-Parameter: ``Centre``
-#####################
+Parameter: ``LogBoundary``
+##########################
+
+The input string parameter ``LogBoundary`` is for filtering by log value(s).
 
-The input Boolean parameter ``centre`` is for filtering by log value(s).
 If option ``centre`` is taken, then for each interval,
 
 -  starting time = log\_time - tolerance\_time;
 -  stopping time = log\_time - tolerance\_time;
 
 It is a shift to left.
 
+**For SNS Users**
+
+In SNS, most of the sample environment devices record values upon changing.
+Therefore, the **LogBoundary** value shall set to **Left** but not **Centre**.
+And in this case, **TimeTolerance** is ignored.
+
+Please check with the instrument scientist to confirm how the sample log values are recorded.
+
+Here is an example how the time splitter works with the a motor's position.
+
+.. figure:: /images/SNAP_motor_filter.png
+
+        For this SNAP run, the user wants to filter events with motor (BL3:Mot:Hexa:MotZ) position
+        at value equal to 6.65 with tolerance as 0.1.
+        The red curve shows the boundary of the time splitters (i.e., event filters).
+
+
 Parameter: ``FastLog``
 ######################