Merge pull request #23661 from mantidproject/live_data_rebinning

LiveData Do not rebin event data unless not already binned

Framework/LiveData/inc/MantidLiveData/LoadLiveData.h

@@ -66,7 +66,7 @@ private:
   void appendChunk(Mantid::API::Workspace_sptr chunkWS);
   API::Workspace_sptr appendMatrixWSChunk(API::Workspace_sptr accumWS,
                                           Mantid::API::Workspace_sptr chunkWS);
-  void resetAllXToSingleBin(API::Workspace *workspace);
+  void updateDefaultBinBoundaries(API::Workspace *workspace);
 
   /// The "accumulation" workspace = after adding, but before post-processing
   Mantid::API::Workspace_sptr m_accumWS;

Framework/LiveData/src/LiveDataAlgorithm.cpp

@@ -74,10 +74,7 @@ void LiveDataAlgorithm::initProps() {
       make_unique<PropertyWithValue<std::string>>("ProcessingAlgorithm", "",
                                                   Direction::Input),
       "Name of the algorithm that will be run to process each chunk of data.\n"
-      "Optional. If blank, no processing will occur. Note that, if "
-      "PreserveEvents is enabled, any rebinning done in this step will be "
-      "lost. Use the Post-Process step for custom rebinning of "
-      "EventWorkspaces.");
+      "Optional. If blank, no processing will occur.");
 
   declareProperty(
       make_unique<PropertyWithValue<std::string>>("ProcessingProperties", "",
@@ -89,19 +86,13 @@ void LiveDataAlgorithm::initProps() {
                       "ProcessingScript", "", Direction::Input),
                   "A Python script that will be run to process each chunk of "
                   "data. Only for command line usage, does not appear on the "
-                  "user interface. Note that, if PreserveEvents is enabled, "
-                  "any rebinning done in this step will be lost. Use the "
-                  "Post-Process step for custom rebinning of "
-                  "EventWorkspaces.");
+                  "user interface.");
 
   declareProperty(make_unique<FileProperty>("ProcessingScriptFilename", "",
                                             FileProperty::OptionalLoad, "py"),
                   "A Python script that will be run to process each chunk of "
                   "data. Only for command line usage, does not appear on the "
-                  "user interface. Note that, if PreserveEvents is enabled, "
-                  "any rebinning done in this step will be lost. Use the "
-                  "Post-Process step for custom rebinning of "
-                  "EventWorkspaces.");
+                  "user interface.");
 
   std::vector<std::string> propOptions{"Add", "Replace", "Append"};
   declareProperty(

Framework/LiveData/src/LoadLiveData.cpp

@@ -417,6 +417,17 @@ Workspace_sptr LoadLiveData::appendMatrixWSChunk(Workspace_sptr accumWS,
   return accumWS;
 }
 
+namespace {
+bool isUsingDefaultBinBoundaries(const EventWorkspace *workspace) {
+  // only check first spectrum
+  const auto &x = workspace->binEdges(0);
+  if (x.size() > 2)
+    return false;
+  // make sure that they are sorted
+  return (x.front() < x.back());
+}
+} // namespace
+
 //----------------------------------------------------------------------------------------------
 /** Resets all HistogramX in given EventWorkspace(s) to a single bin.
  *
@@ -428,15 +439,17 @@ Workspace_sptr LoadLiveData::appendMatrixWSChunk(Workspace_sptr accumWS,
  *
  * @param workspace :: Workspace(Group) that will have its bins reset
  */
-void LoadLiveData::resetAllXToSingleBin(API::Workspace *workspace) {
+void LoadLiveData::updateDefaultBinBoundaries(API::Workspace *workspace) {
   if (auto *ws_event = dynamic_cast<EventWorkspace *>(workspace)) {
-    ws_event->resetAllXToSingleBin();
+    if (isUsingDefaultBinBoundaries(ws_event))
+      ws_event->resetAllXToSingleBin();
   } else if (auto *ws_group = dynamic_cast<WorkspaceGroup *>(workspace)) {
     auto num_entries = static_cast<size_t>(ws_group->getNumberOfEntries());
     for (size_t i = 0; i < num_entries; ++i) {
       auto ws = ws_group->getItem(i);
       if (auto *ws_event = dynamic_cast<EventWorkspace *>(ws.get()))
-        ws_event->resetAllXToSingleBin();
+        if (isUsingDefaultBinBoundaries(ws_event))
+          ws_event->resetAllXToSingleBin();
     }
   }
 }
@@ -492,18 +505,17 @@ void LoadLiveData::exec() {
   this->setPropertyValue("LastTimeStamp", lastTimeStamp.toISO8601String());
 
   // For EventWorkspaces, we adjust the X values such that all events fit
-  // within the bin boundaries. This is done both before and after the
-  // "Process" step. Any custom rebinning should be done in Post-Processing.
-  bool PreserveEvents = this->getProperty("PreserveEvents");
-  if (PreserveEvents)
-    this->resetAllXToSingleBin(chunkWS.get());
+  // within the bin boundaries
+  const bool preserveEvents = this->getProperty("PreserveEvents");
+  if (preserveEvents)
+    this->updateDefaultBinBoundaries(chunkWS.get());
 
   // Now we process the chunk
   Workspace_sptr processed = this->processChunk(chunkWS);
 
   EventWorkspace_sptr processedEvent =
       boost::dynamic_pointer_cast<EventWorkspace>(processed);
-  if (!PreserveEvents && processedEvent) {
+  if (!preserveEvents && processedEvent) {
     // Convert the monitor workspace, if there is one and it's necessary
     MatrixWorkspace_sptr monitorWS = processedEvent->monitorWorkspace();
     auto monitorEventWS =
@@ -548,18 +560,20 @@ void LoadLiveData::exec() {
   g_log.notice() << "Performing the " << accum << " operation.\n";
 
   // Perform the accumulation and set the AccumulationWorkspace workspace
-  if (accum == "Replace")
+  if (accum == "Replace") {
     this->replaceChunk(processed);
-  else if (accum == "Append")
+  } else if (accum == "Append") {
     this->appendChunk(processed);
-  else
+  } else {
     // Default to Add.
     this->addChunk(processed);
 
-  // For EventWorkspaces, we adjust the X values such that all events fit
-  // within the bin boundaries. This is done both before and after the
-  // "Process" step. Any custom rebinning should be done in Post-Processing.
-  this->resetAllXToSingleBin(m_accumWS.get());
+    // When adding events, the default bin boundaries may need to be updated.
+    // The function itself checks to see if it is appropriate
+    if (preserveEvents) {
+      this->updateDefaultBinBoundaries(m_accumWS.get());
+    }
+  }
 
   // At this point, m_accumWS is set.
 

Framework/LiveData/test/LoadLiveDataTest.h

@@ -289,7 +289,7 @@ public:
     // Accumulated workspace: it was rebinned, but rebinning should be reset
     TS_ASSERT_EQUALS(ws_accum->getNumberHistograms(), 2);
     TS_ASSERT_EQUALS(ws_accum->getNumberEvents(), 200);
-    TS_ASSERT_EQUALS(ws_accum->blocksize(), 1);
+    TS_ASSERT_EQUALS(ws_accum->blocksize(), 40);
 
     // The post-processed workspace was rebinned starting at 40e3
     TS_ASSERT_EQUALS(ws->getNumberHistograms(), 2);

docs/source/algorithms/LoadLiveData-v1.rst

@@ -31,26 +31,20 @@ Data Processing
 -  You have two options on how to process this workspace:
 
 Processing with an Algorithm
-############################
+++++++++++++++++++++++++++++
 
 -  Specify the name of the algorithm in the ``ProcessingAlgorithm``
    property.
 
-   -  This could be, e.g. a `Python Algorithm <Python Algorithm>`__
-      written for this purpose.
+   -  This could be a python algorithm written for this purpose
    -  The algorithm *must* have at least 2 properties: ``InputWorkspace``
       and ``OutputWorkspace``.
    -  Any other properties are set from the string in
       ``ProcessingProperties``.
-   -  The algorithm is then run, and its ``OutputWorkspace`` is saved.
-
-.. note:
-
-   When PreserveEvents is enabled, any rebinning done in this step will be
-   lost. Use the Post-Process step instead for EventWorkspaces.
+   -  The algorithm is then run, and its ``OutputWorkspace`` is saved
 
 Processing with a Python Script
-###############################
++++++++++++++++++++++++++++++++
 
 The python script is run using :ref:`algm-RunPythonScript`. Please see
 its documentation for details of how the script is run.
@@ -72,10 +66,13 @@ its documentation for details of how the script is run.
 
    - Contents of the file have the exact same rules as specifying the ``ProcessingScript``
 
-.. note:
+.. note::
 
-   When PreserveEvents is enabled, any rebinning done in this step will be
-   lost. Use the Post-Process step instead for EventWorkspaces.
+   When ``PreserveEvents`` is enabled and the data has not been binned
+   during the process step (with ``ProcessingAlgorithm``,
+   ``ProcessingScript``, or ``ProcessingScriptFilename``), the data
+   will be rebinned at the end of the step to include all events. Use
+   the Post-Process step instead for :ref:`EventWorkspaces <EventWorkspace>`.
 
 Data Accumulation
 #################
@@ -90,36 +87,31 @@ Data Accumulation
    -  If you select ``Append``, then the spectra from each chunk will be
       appended to the output workspace.
 
-A Warning About Events
-######################
+.. warning::
 
-Beware! If you select ``PreserveEvents=True`` and your processing
-keeps the data as :ref:`EventWorkspaces <EventWorkspace>`, you may end
-up creating **very large** EventWorkspaces in long runs. Most plots
-require re-sorting the events, which is an operation that gets much
-slower as the list gets bigger (Order of :math:`N * log(N)`). This
-could cause Mantid to run very slowly or to crash due to lack of
-memory.
+   Beware! If you select ``PreserveEvents=True`` and your processing
+   keeps the data as :ref:`EventWorkspaces <EventWorkspace>`, you may end
+   up creating **very large** EventWorkspaces in long runs. Most plots
+   require re-sorting the events, which is an operation that gets much
+   slower as the list gets bigger (Order of :math:`N * log(N)`). This
+   could cause Mantid to run very slowly or to crash due to lack of
+   memory.
 
-Additionally, the resulting EventWorkspaces produced when
-``PreserveEvents=True`` will have their X values reset to a single bin with
-boundaries that encompass all events currently in the workspace. This means
-that any rebinning that was done during the Process step will be lost. If
-custom binning is required, this should be done using the Post-Process step
-described below.
+   It is highly recommended that early in the PostProcessing step one
+   uses :ref:`CompressEvents <algm-CompressEvents>` if the data is going
+   to remain in events.
 
 Post-Processing Step
 ####################
 
--  Optionally, you can specify some processing to perform *after*
-   accumulation.
+- Optionally, you can specify some processing to perform *after*
+  accumulation.
 
-   -  You then need to specify the ``AccumulationWorkspace`` property.
+  -  You then need to specify the ``AccumulationWorkspace`` property.
 
-- Using either the ``PostProcessingAlgorithm``,
-   ``PostProcessingScript``, or ``PostProcessingScriptFilename`` (same
-   way as above), the ``AccumulationWorkspace`` is processed into the
-   ``OutputWorkspace``
+- Using either the ``PostProcessingAlgorithm``, ``PostProcessingScript``,
+  or ``PostProcessingScriptFilename`` (same way as above), the
+  ``AccumulationWorkspace`` is processed into the ``OutputWorkspace``
 
 Usage
 -----

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

@@ -48,7 +48,7 @@ Improvements
 - :ref:`CropToComponent <algm-CropToComponent>` now supports also scanning workspaces.
 - :ref:`SumOverlappingTubes <algm-SumOverlappingTubes>` will produce histogram data, and will not split the counts between bins by default.
 - :ref:`SumSpectra <algm-SumSpectra>` has an additional option, ``MultiplyBySpectra``, which controls whether or not the output spectra are multiplied by the number of bins. This property should be set to ``False`` for summing spectra as PDFgetN does.
-- :ref:`Live Data <algm-StartLiveData>` for events in PreserveEvents mode now produces workspaces that have bin boundaries which encompass the total x-range (TOF) for all events across all spectra.
+- :ref:`Live Data <algm-StartLiveData>` for events with ``PreserveEvents=True`` now produces workspaces that have bin boundaries which encompass the total x-range (TOF) for all events across all spectra if the data was not binned during the process step.
 - Bugfix in :ref:`ConvertToMatrixWorkspace <algm-ConvertToMatrixWorkspace>` with ``Workspace2D`` as the ``InputWorkspace`` not being cloned to the ``OutputWorkspace``. Added support for ragged workspaces.
 - :ref:`RebinToWorkspace <algm-RebinToWorkspace>` now checks if the ``WorkspaceToRebin`` and ``WorkspaceToMatch`` already have the same binning. Added support for ragged workspaces.
 - :ref:`GroupWorkspaces <algm-GroupWorkspaces>` supports glob patterns for matching workspaces in the ADS.