Merge remote-tracking branch 'origin/fix_filterevents_issues'

Framework/Algorithms/inc/MantidAlgorithms/FilterEvents.h

@@ -82,12 +82,20 @@ private:
   /// Process user input properties
   void processAlgorithmProperties();
 
+  /// process splitters given by a SplittersWorkspace
   void processSplittersWorkspace();
 
-  ///
+  void processTableSplittersWorkspace();
+
+  /// process splitters given by a MatrixWorkspace
   void processMatrixSplitterWorkspace();
 
   void createOutputWorkspaces();
+  /// create output workspaces in the case of using TableWorlspace for splitters
+  void createOutputWorkspacesTableSplitterCase();
+  /// create output workspaces in the case of using MatrixWorkspace for
+  /// splitters
+  void createOutputWorkspacesMatrixCase();
 
   /// Set up detector calibration parameters
   void setupDetectorTOFCalibration();
@@ -115,17 +123,24 @@ private:
   /// Examine workspace
   void examineEventWS();
 
+  /// Convert SplittersWorkspace to vector of time and vector of target
+  /// (itarget)
+  void convertSplittersWorkspaceToVectors();
+
   DataObjects::EventWorkspace_sptr m_eventWS;
   DataObjects::SplittersWorkspace_sptr m_splittersWorkspace;
+  DataObjects::TableWorkspace_sptr m_splitterTableWorkspace;
   API::MatrixWorkspace_const_sptr m_matrixSplitterWS;
   DataObjects::TableWorkspace_sptr m_detCorrectWorkspace;
 
   /// Flag to use matrix splitters or table splitters
-  bool m_useTableSplitters;
+  bool m_useSplittersWorkspace;
+  bool m_useArbTableSplitters;
 
-  std::set<int> m_workGroupIndexes;
+  std::set<int> m_targetWorkspaceIndexSet;
+  int m_maxTargetIndex;
   Kernel::TimeSplitterType m_splitters;
-  std::map<int, DataObjects::EventWorkspace_sptr> m_outputWS;
+  std::map<int, DataObjects::EventWorkspace_sptr> m_outputWorkspacesMap;
   std::vector<std::string> m_wsNames;
 
   std::vector<double> m_detTofOffsets;
@@ -138,20 +153,41 @@ private:
 
   double m_progress;
 
+  /// DOC! TODO
   std::vector<std::string> getTimeSeriesLogNames();
 
   Kernel::TimeSplitterType generateSplitters(int wsindex);
 
+  void generateSplitterTSP(
+      std::vector<Kernel::TimeSeriesProperty<int> *> &split_tsp_vec);
+
+  void generateSplitterTSPalpha(
+      std::vector<Kernel::TimeSeriesProperty<int> *> &split_tsp_vec);
+
+  ///
+  void mapSplitterTSPtoWorkspaces(
+      const std::vector<Kernel::TimeSeriesProperty<int> *> &split_tsp_vec);
+
   void splitLog(DataObjects::EventWorkspace_sptr eventws, std::string logname,
                 Kernel::TimeSplitterType &splitters);
 
   /// Base of output workspace's name
   std::string m_outputWSNameBase;
 
+  /// TableWorkspace splitters: from target map to vector workspace group-index
+  /// These 2 maps are complimentary to each other
+  std::map<std::string, int> m_targetIndexMap;
+  std::map<int, std::string> m_wsGroupIndexTargetMap;
+
+  /// MatrixWorkspace splitters:
+  std::map<int, uint32_t> m_yIndexMap;
+  std::map<uint32_t, int> m_wsGroupdYMap;
+
   /// Flag to group workspace
   bool m_toGroupWS;
 
   /// Vector for splitting time
+  /// FIXME - shall we convert this to DateAndTime???.  Need to do speed test!
   std::vector<int64_t> m_vecSplitterTime;
   /// Vector for splitting grouip
   std::vector<int> m_vecSplitterGroup;
@@ -175,6 +211,8 @@ private:
   bool m_isSplittersRelativeTime;
   // Starting time for starting time of event filters
   Kernel::DateAndTime m_filterStartTime;
+  // EventWorkspace (aka. run)'s starting time
+  Kernel::DateAndTime m_runStartTime;
 };
 
 } // namespace Algorithms

Framework/Kernel/inc/MantidKernel/TimeSeriesProperty.h

@@ -157,6 +157,12 @@ public:
   void splitByTime(std::vector<SplittingInterval> &splitter,
                    std::vector<Property *> outputs,
                    bool isPeriodic) const override;
+
+  /// New split method
+  void splitByTimeVector(std::vector<DateAndTime> &splitter_time_vec,
+                         std::vector<int> &target_vec,
+                         std::vector<TimeSeriesProperty *> outputs);
+
   /// Fill a TimeSplitterType that will filter the events by matching
   void makeFilterByValue(std::vector<SplittingInterval> &split, double min,
                          double max, double TimeTolerance = 0.0,

Framework/Kernel/src/TimeSeriesProperty.cpp

@@ -521,6 +521,152 @@ void TimeSeriesProperty<TYPE>::splitByTime(
   }
 }
 
+/// Split this TimeSeriresProperty by a vector of time with N entries,
+/// and by the target workspace index defined by target_vec
+/// Requirements:
+/// 1. vector outputs must be defined before this method is called;
+template <typename TYPE>
+void TimeSeriesProperty<TYPE>::splitByTimeVector(
+    std::vector<DateAndTime> &splitter_time_vec, std::vector<int> &target_vec,
+    std::vector<TimeSeriesProperty *> outputs) {
+  // check inputs
+  if (splitter_time_vec.size() != target_vec.size() + 1)
+    throw std::runtime_error("Input time vector's size does not match taget "
+                             "workspace index vector's size.");
+  // return if the output vector TimeSeriesProperties is not defined
+  if (outputs.empty())
+    return;
+
+  // sort if necessary
+  sortIfNecessary();
+
+  // work on m_values, m_size, and m_time
+  std::vector<Kernel::DateAndTime> tsp_time_vec = this->timesAsVector();
+
+  // go over both filter time vector and time series property time vector
+  size_t index_splitter = 0;
+  size_t index_tsp_time = 0;
+
+  DateAndTime tsp_time = tsp_time_vec[index_tsp_time];
+  DateAndTime split_start_time = splitter_time_vec[index_splitter];
+  DateAndTime split_stop_time = splitter_time_vec[index_splitter + 1];
+
+  // move splitter index such that the first entry of TSP is before the stop
+  // time of a splitter
+  bool continue_search = true;
+  bool no_entry_in_range = false;
+
+  std::vector<DateAndTime>::iterator splitter_iter;
+  splitter_iter = std::lower_bound(splitter_time_vec.begin(),
+                                   splitter_time_vec.end(), tsp_time);
+  if (splitter_iter == splitter_time_vec.begin()) {
+    // do nothing as the first TimeSeriesProperty entry's time is before any
+    // splitters
+    ;
+  } else if (splitter_iter == splitter_time_vec.end()) {
+    // already search to the last splitter which is still earlier than first TSP
+    // entry
+    no_entry_in_range = true;
+  } else {
+    // calculate the splitter's index (now we check the stop time)
+    index_splitter = splitter_iter - splitter_time_vec.begin() - 1;
+    split_start_time = splitter_time_vec[index_splitter];
+    split_stop_time = splitter_time_vec[index_splitter + 1];
+  }
+
+  g_log.debug() << "TSP entry: " << index_tsp_time
+                << ", Splitter index = " << index_splitter << "\n";
+
+  // move along the entries to find the entry inside the current splitter
+  if (!no_entry_in_range) {
+    std::vector<DateAndTime>::iterator tsp_time_iter;
+    tsp_time_iter = std::lower_bound(tsp_time_vec.begin(), tsp_time_vec.end(),
+                                     split_start_time);
+    if (tsp_time_iter == tsp_time_vec.end()) {
+      // the first splitter's start time is LATER than the last TSP entry, then
+      // there won't be any
+      // TSP entry to be split into any target splitter.
+      no_entry_in_range = true;
+    } else {
+      // first splitter start time is between tsp_time_iter and the one before
+      // it.
+      // so the index for tsp_time_iter is the first TSP entry in the splitter
+      index_tsp_time = tsp_time_iter - tsp_time_vec.begin();
+      tsp_time = *tsp_time_iter; // tsp_time_vec[index_splitter];
+    }
+  }
+
+  g_log.debug() << "TSP entry: " << index_tsp_time
+                << ", Splitter index = " << index_splitter << "\n";
+
+  // now it is the time to put TSP's entries to corresponding
+  continue_search = !no_entry_in_range;
+  while (continue_search) {
+    // get the first entry index
+    if (index_tsp_time > 0)
+      --index_tsp_time;
+
+    int target = target_vec[index_splitter];
+
+    g_log.debug() << "Target = " << target
+                  << " with splitter index = " << index_splitter << "\n"
+                  << "\t"
+                  << "Time index = " << index_tsp_time << "\n\n";
+
+    bool continue_add = true;
+    while (continue_add) {
+      // add current entry
+      g_log.debug() << "Add entry " << index_tsp_time << " to target " << target
+                    << "\n";
+      if (outputs[target]->size() == 0 ||
+          outputs[target]->lastTime() < tsp_time) {
+        // avoid to add duplicate entry
+        outputs[target]->addValue(m_values[index_tsp_time].time(),
+                                  m_values[index_tsp_time].value());
+      }
+
+      // advance to next entry
+      ++index_tsp_time;
+
+      g_log.debug() << "\tEntry time " << tsp_time_vec[index_tsp_time]
+                    << ", stop time " << split_stop_time << "\n";
+
+      if (index_tsp_time == tsp_time_vec.size()) {
+        // last entry. quit all loops
+        continue_add = false;
+        continue_search = false;
+      } else if (tsp_time_vec[index_tsp_time] > split_stop_time) {
+        // next entry is out of this splitter: add the next one and quit
+        if (outputs[target]->lastTime() < m_values[index_tsp_time].time()) {
+          // avoid the duplicate cases occured in fast frequency issue
+          outputs[target]->addValue(m_values[index_tsp_time].time(),
+                                    m_values[index_tsp_time].value());
+        }
+        // FIXME - in future, need to find out WHETHER there is way to skip the
+        // rest without going through the whole sequence
+        continue_add = false;
+        // reset time entry as the next splitter will add
+        // --index_tsp_time;
+      } else {
+        // advance to next time
+        tsp_time = tsp_time_vec[index_tsp_time];
+      }
+    } // END-WHILE continue add
+
+    // make splitters to advance to next
+    ++index_splitter;
+    if (index_splitter == splitter_time_vec.size() - 1) {
+      // already last splitters
+      continue_search = false;
+    } else {
+      split_start_time = split_stop_time;
+      split_stop_time = splitter_time_vec[index_splitter + 1];
+    }
+  } // END-OF-WHILE
+
+  return;
+}
+
 // The makeFilterByValue & expandFilterToRange methods generate a bunch of
 // warnings when the template type is the wider integer types
 // (when it's being assigned back to a double such as in a call to minValue or

Framework/Kernel/test/TimeSeriesPropertyTest.h

@@ -711,6 +711,259 @@ public:
     delete outputs[0];
   }
 
+  //----------------------------------------------------------------------------
+  /**
+   * otuput 0 has entries: 3
+   * otuput 1 has entries: 5
+   * otuput 2 has entries: 2
+   * otuput 3 has entries: 7
+   * @brief test_splitByTimeVector
+   */
+  void test_splitByTimeVector() {
+    // create the splitters
+    std::vector<DateAndTime> split_time_vec;
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:17:10"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:17:40"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:17:55"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:17:56"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:18:09"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:18:45"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:22:50"));
+
+    std::vector<int> split_target_vec;
+    split_target_vec.push_back(1);
+    split_target_vec.push_back(0);
+    split_target_vec.push_back(2);
+    split_target_vec.push_back(0);
+    split_target_vec.push_back(1);
+    split_target_vec.push_back(3);
+
+    TimeSeriesProperty<int> log("test log");
+    log.addValue(DateAndTime("2007-11-30T16:17:00"), 1);
+    log.addValue(DateAndTime("2007-11-30T16:17:30"), 2);
+    log.addValue(DateAndTime("2007-11-30T16:18:00"), 3);
+    log.addValue(DateAndTime("2007-11-30T16:18:30"), 4);
+    log.addValue(DateAndTime("2007-11-30T16:19:00"), 5);
+    log.addValue(DateAndTime("2007-11-30T16:19:30"), 6);
+    log.addValue(DateAndTime("2007-11-30T16:20:00"), 7);
+    log.addValue(DateAndTime("2007-11-30T16:20:30"), 8);
+    log.addValue(DateAndTime("2007-11-30T16:21:00"), 9);
+    log.addValue(DateAndTime("2007-11-30T16:21:30"), 10);
+
+    std::vector<TimeSeriesProperty<int> *> outputs;
+    for (int itarget = 0; itarget < 4; ++itarget) {
+      TimeSeriesProperty<int> *tsp = new TimeSeriesProperty<int>("target");
+      outputs.push_back(tsp);
+    }
+
+    log.splitByTimeVector(split_time_vec, split_target_vec, outputs);
+
+    // Exam the split entries
+    TimeSeriesProperty<int> *out_0 = outputs[0];
+    // FIXME - Check whether out_0 is correct!
+    TS_ASSERT_EQUALS(out_0->size(), 3);
+    TS_ASSERT_EQUALS(out_0->nthValue(0), 2);
+    TS_ASSERT_EQUALS(out_0->nthValue(1), 3);
+    TS_ASSERT_EQUALS(out_0->nthValue(2), 4);
+
+    TimeSeriesProperty<int> *out_1 = outputs[1];
+    TS_ASSERT_EQUALS(out_1->size(), 5);
+    TS_ASSERT_EQUALS(out_1->nthValue(0), 1);
+    TS_ASSERT_EQUALS(out_1->nthValue(1), 2);
+    TS_ASSERT_EQUALS(out_1->nthValue(2), 3);
+    TS_ASSERT_EQUALS(out_1->nthValue(3), 4);
+    TS_ASSERT_EQUALS(out_1->nthValue(4), 5);
+
+    TimeSeriesProperty<int> *out_2 = outputs[2];
+    TS_ASSERT_EQUALS(out_2->size(), 2);
+    TS_ASSERT_EQUALS(out_2->nthValue(0), 2);
+    TS_ASSERT_EQUALS(out_2->nthValue(1), 3);
+
+    TimeSeriesProperty<int> *out_3 = outputs[3];
+    TS_ASSERT_EQUALS(out_3->size(), 7);
+    // out[3] should have entries: 4, 5, 6, 7, 8, 9, 10
+    for (int j = 0; j < out_3->size(); ++j) {
+      TS_ASSERT_EQUALS(out_3->nthValue(j), j + 4);
+    }
+
+    return;
+  }
+
+  //----------------------------------------------------------------------------
+  /** last splitter is before first entry
+   * @brief test_splitByTimeVectorEarlySplitter
+   */
+  void test_splitByTimeVectorEarlySplitter() {
+    // create the splitters
+    std::vector<DateAndTime> split_time_vec;
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:00:10"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:00:40"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:07:55"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:07:56"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:08:09"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:08:45"));
+    split_time_vec.push_back(DateAndTime("2007-11-30T16:12:50"));
+
+    std::vector<int> split_target_vec;
+    split_target_vec.push_back(1);
+    split_target_vec.push_back(0);
+    split_target_vec.push_back(2);
+    split_target_vec.push_back(0);
+    split_target_vec.push_back(1);
+    split_target_vec.push_back(3);
+
+    TimeSeriesProperty<int> log("test log");
+    log.addValue(DateAndTime("2007-11-30T16:17:00"), 1);
+    log.addValue(DateAndTime("2007-11-30T16:17:30"), 2);
+    log.addValue(DateAndTime("2007-11-30T16:18:00"), 3);
+    log.addValue(DateAndTime("2007-11-30T16:18:30"), 4);
+    log.addValue(DateAndTime("2007-11-30T16:19:00"), 5);
+    log.addValue(DateAndTime("2007-11-30T16:19:30"), 6);
+    log.addValue(DateAndTime("2007-11-30T16:20:00"), 7);
+    log.addValue(DateAndTime("2007-11-30T16:20:30"), 8);
+    log.addValue(DateAndTime("2007-11-30T16:21:00"), 9);
+    log.addValue(DateAndTime("2007-11-30T16:21:30"), 10);
+
+    // Initialze the 4 splitters
+    std::vector<TimeSeriesProperty<int> *> outputs;
+    for (int itarget = 0; itarget < 4; ++itarget) {
+      TimeSeriesProperty<int> *tsp = new TimeSeriesProperty<int>("target");
+      outputs.push_back(tsp);
+    }
+
+    log.splitByTimeVector(split_time_vec, split_target_vec, outputs);
+
+    // check
+    for (int i = 0; i < 4; ++i) {
+      TimeSeriesProperty<int> *out_i = outputs[i];
+      TS_ASSERT_EQUALS(out_i->size(), 0);
+    }
+
+    return;
+  }
+
+  //----------------------------------------------------------------------------
+  /** first splitter is after last entry
+   * @brief test_splitByTimeVectorLaterSplitter
+   */
+  void test_splitByTimeVectorLaterSplitter() {
+    // create the splitters
+    std::vector<DateAndTime> split_time_vec;
+    split_time_vec.push_back(DateAndTime("2007-12-30T16:00:10"));
+    split_time_vec.push_back(DateAndTime("2007-12-30T16:00:40"));
+    split_time_vec.push_back(DateAndTime("2007-12-30T16:07:55"));
+    split_time_vec.push_back(DateAndTime("2007-12-30T16:07:56"));
+    split_time_vec.push_back(DateAndTime("2007-12-30T16:08:09"));
+    split_time_vec.push_back(DateAndTime("2007-12-30T16:08:45"));
+    split_time_vec.push_back(DateAndTime("2007-12-30T16:12:50"));
+
+    std::vector<int> split_target_vec;
+    split_target_vec.push_back(1);
+    split_target_vec.push_back(0);
+    split_target_vec.push_back(2);
+    split_target_vec.push_back(0);
+    split_target_vec.push_back(1);
+    split_target_vec.push_back(3);
+
+    // create test log
+    TimeSeriesProperty<int> log("test log");
+    log.addValue(DateAndTime("2007-11-30T16:17:00"), 1);
+    log.addValue(DateAndTime("2007-11-30T16:17:30"), 2);
+    log.addValue(DateAndTime("2007-11-30T16:18:00"), 3);
+    log.addValue(DateAndTime("2007-11-30T16:18:30"), 4);
+    log.addValue(DateAndTime("2007-11-30T16:19:00"), 5);
+    log.addValue(DateAndTime("2007-11-30T16:19:30"), 6);
+    log.addValue(DateAndTime("2007-11-30T16:20:00"), 7);
+    log.addValue(DateAndTime("2007-11-30T16:20:30"), 8);
+    log.addValue(DateAndTime("2007-11-30T16:21:00"), 9);
+    log.addValue(DateAndTime("2007-11-30T16:21:30"), 10);
+
+    // Initialze the 4 splitters
+    std::vector<TimeSeriesProperty<int> *> outputs;
+    for (int itarget = 0; itarget < 4; ++itarget) {
+      TimeSeriesProperty<int> *tsp = new TimeSeriesProperty<int>("target");
+      outputs.push_back(tsp);
+    }
+
+    log.splitByTimeVector(split_time_vec, split_target_vec, outputs);
+
+    // check
+    for (int i = 0; i < 4; ++i) {
+      TimeSeriesProperty<int> *out_i = outputs[i];
+      TS_ASSERT_EQUALS(out_i->size(), 0);
+    }
+  }
+
+  //----------------------------------------------------------------------------
+  /** high-frequency splitters splits a slow change log
+   * @brief test_splitByTimeVectorFastLogSplitter
+   */
+  void test_splitByTimeVectorFastLogSplitter() {
+    // create test log
+    TimeSeriesProperty<int> log("test log");
+    log.addValue(DateAndTime("2007-11-30T16:17:00"), 1);
+    log.addValue(DateAndTime("2007-11-30T16:17:30"), 2);
+    log.addValue(DateAndTime("2007-11-30T16:18:00"), 3);
+    log.addValue(DateAndTime("2007-11-30T16:18:30"), 4);
+    log.addValue(DateAndTime("2007-11-30T16:19:00"), 5);
+    log.addValue(DateAndTime("2007-11-30T16:19:30"), 6);
+    log.addValue(DateAndTime("2007-11-30T16:20:00"), 7);
+    log.addValue(DateAndTime("2007-11-30T16:20:30"), 8);
+    log.addValue(DateAndTime("2007-11-30T16:21:00"), 9);
+    log.addValue(DateAndTime("2007-11-30T16:21:30"), 10);
+
+    // create a high frequency splitter
+    DateAndTime split_time("2007-11-30T16:17:00");
+    int64_t dt = 100 * 1000;
+
+    std::vector<DateAndTime> vec_split_times;
+    std::vector<int> vec_split_target;
+
+    for (int i = 0; i < 10; ++i) {
+      for (int j = 0; j < 10; ++j) {
+        vec_split_times.push_back(split_time);
+        split_time += dt;
+        vec_split_target.push_back(j);
+      }
+    }
+
+    // push back last split-time (split stop)
+    vec_split_times.push_back(split_time);
+
+    // Initialze the 10 splitters
+    std::vector<TimeSeriesProperty<int> *> outputs;
+    for (int itarget = 0; itarget < 10; ++itarget) {
+      TimeSeriesProperty<int> *tsp = new TimeSeriesProperty<int>("target");
+      outputs.push_back(tsp);
+    }
+
+    /*
+    size_t num_splits = vec_split_target.size();
+    for (size_t i = 0; i < num_splits; ++i) {
+      std::cout << "s[" << i << "]  start = " << vec_split_times[i]
+                << ", stop = " << vec_split_times[i + 1]
+                << ":  target = " << vec_split_target[i] << "\n";
+    }
+    */
+
+    // split time series property
+    log.splitByTimeVector(vec_split_times, vec_split_target, outputs);
+
+    // TODO/FIXME/ - continue to debug from here!
+    /*
+    TimeSeriesProperty<int> *out0 = outputs[0];
+    for (int i = 0; i < out0->size(); ++i) {
+      std::cout << i << "-th: " << out0->nthTime(i) << ", " << out0->nthValue(i)
+                << "\n";
+    }
+    */
+
+    // test
+    for (size_t i = 0; i < 10; ++i) {
+      TS_ASSERT_EQUALS(outputs[i]->size(), 2);
+    }
+  }
+
   //----------------------------------------------------------------------------
   void test_statistics() {
     TimeSeriesProperty<double> *log =

docs/source/algorithms/FilterEvents-v1.rst

@@ -94,6 +94,25 @@ Comparing with other event filtering algorithms
 Wiki page :ref:`EventFiltering` has a detailed introduction on event
 filtering in MantidPlot.
 
+
+Developer's Note
+----------------
+
+Splitters given by TableWorkspace
+#################################
+
+ - The *start/stop* time is converted to **m_vecSplitterTime**.
+ - The *splitting target* (in string) is mapped to a set of continuous integers that are stored in **m_vecSplitterGroup**.
+   - The mapping will be recorded in **m_targetIndexMap** and **m_wsGroupIndexTargetMap**.
+   - Class variable **m_maxTargetIndex** is set up to record the highest target group/index,i.e., the max value of m_vecSplitterGroup
+
+
+Undefined splitting target
+##########################
+
+Indexed as **0** in **m_vecSplitterGroup**.
+
+
 Usage
 -----
 
@@ -131,6 +150,53 @@ Output:
     workspace tempsplitws_5 has 5133 events
     workspace tempsplitws_unfiltered has 50603 events
 
+**Example - Filtering event by a user-generated TableWorkspace**
+
+.. testcode:: FilterEventNoCorrection
+
+    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 evnets
+    FilterEvents(InputWorkspace=ws, SplitterWorkspace=split_table_ws,
+            OutputWorkspaceBaseName='tempsplitws3',  GroupWorkspaces=True,
+            FilterByPulseTime = False, OutputWorkspaceIndexedFrom1 = False,
+            CorrectionToSample = "None", SpectrumWithoutDetector = "Skip", SplitSampleLogs = False,
+            OutputTOFCorrectionWorkspace='mock')
+
+    # 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())
+        split_log = tmpws.run().getProperty('splitter')
+        print 'event splitter log: entry 0 and entry 1 are {0} and {1}.'.format(split_log.times[0], split_log.times[1])
+
+
+Output:
+
+.. testoutput:: FilterEventNoCorrection
+
+    workspace tempsplitws3_a has 77580 events
+    event splitter log: entry 0 and entry 1 are 2010-03-25T16:08:37  and 2010-03-25T16:10:17 .
+    workspace tempsplitws3_b has 0 events
+    event splitter log: entry 0 and entry 1 are 2010-03-25T16:08:37  and 2010-03-25T16:11:57 .
+    workspace tempsplitws3_c has 0 events
+    event splitter log: entry 0 and entry 1 are 2010-03-25T16:08:37  and 2010-03-25T16:15:17 .
+    workspace tempsplitws3_unfiltered has 34686 events
+    event splitter log: entry 0 and entry 1 are 2010-03-25T16:08:37  and 2010-03-25T16:10:17 .
+
 
 **Example - Filtering event by pulse time**
 

docs/source/release/v3.10.0/framework.rst

@@ -25,7 +25,10 @@ Improved
 
 - :ref:`RawFileInfo <algm-RawFileInfo-v1>` now provides sample information.
 - :ref:`SetInstrumentParameter <algm-SetInstrumentParameter-v1>` now supports also boolean parameters, and better validates the inputs.
-- Two new properties were added to :ref:`algm-Integration`: *RangeLowerList* and *RangeUpperList* can be used to give histogram-specific integration ranges.
+- :ref:`FilterEvents <algm-FilterEvents-v1>` now accepts a general TableWorkspace as the splitters workspace.  The TableWorkspace must have at least 3 columns.  The first 3 columns are for relative starting time, relative stopping time and target workspace tag for splitters, respectively.
+- :ref:`FilterEvents <algm-FilterEvents-v1>` now generates a sample log named *splitter* of each output workspace (i.e., splitted workspace) to represent the event filter that is applied to it.
+- :ref:`FilterEvents <algm-FilterEvents-v1>` now splits all the sample logs if the input splitters are given by MatrixWorkspace or a general TableWorkspace.
+- Two new properties were added to :ref:`algm-Integration` *RangeLowerList* and *RangeUpperList* can be used to give histogram-specific integration ranges.
 - :ref:`algm-FindEPP` does not output the two extra workspaces from the :ref:`algm-Fit` anymore.
 
 Bug Fixes