Update sphinx documentation

Add documentation for DirectILLTubeBackground and update DirectILL technique docs accordingly.

Re #22224

docs/source/algorithms/DirectILLTubeBackground-v1.rst

+
+.. algorithm::
+
+.. summary::
+
+.. relatedalgorithms::
+
+.. properties::
+
+Description
+-----------
+
+This algorithm calculates the time-independent background over instrument components. It is geared towards TOF spectrometers with position sensitive detector tubes such as IN5 at ILL and can be readily used as a part of ILL's direct geometry reduction workflow (see :ref:`here <DirectILL>`).
+
+The algorithm works as following:
+
+#. Pick a tube from the given list of tube components
+#. For each pixel in the tube, calculate the average Y excluding the elastic peak region
+#. Fit a polynomial over the averaged Ys of the pixels using :ref:`CalculatePolynomialBackground <algm-CalculatePolynomialBackground>`
+#. Move to the next tube in the list
+
+The *OutputWorkspace* contains the evaluated background polynomials and can be readily used for background subtraction.
+
+The tube components can be given as a list of component names in *Components*, or listed as a comma separated string in the instrument parameters file under the name :literal:`components-for-backgrounds`.
+
+The background exclusion range is determined by the *EPPWorkspace* and *NonBkgRegionInSigmas* properties. *EPPWorkspace* is a table workspace containing the centres of the exclusion regions, usually the elastic peaks of a TOF workspace. Such a workspace can be produced for instance by :ref:`FindEPP <algm-FindEPP>` or :ref:`CreateEPP <algm-CreateEPP>` algorithms. The exclusion region is :literal:`[PeakCentre - NonBkgRegionInSigmas * Sigma, PeakCentre + NonBkgRegionInSigmas * Sigma]` where :literal:`PeakCentre` and :literal:`Sigma` are read from *EPPWorkspace*.
+
+Any pixel for which the :literal:`FitStatus` column  in *EPPWorkspace* is not equal to :literal:`success` is ignored.
+
+A mask workspace produced for example by :ref:`DirectILLDiagnostics <algm-DirectILLDiagnostics>` can be given in the *DiagnosticsWorkspace* property to exclude pixels with known problems. Of course, *InputWorkspace* can be directly masked, too.
+
+Usage
+-----
+.. include:: ../usagedata-note.txt
+
+**Example - Usage as part of reduction workflow**
+
+.. plot::
+   :include-source:
+
+   from mantid.simpleapi import *
+   import matplotlib.pyplot as plt
+   import numpy as np
+   # Load and preprocess some IN5 data
+   DirectILLCollectData('ILL/IN5/104007.nxs',
+       OutputWorkspace='ws', OutputEPPWorkspace='epp')
+   # Get default hard mask + beam stop mask
+   DirectILLDiagnostics('ws', OutputWorkspace='diagnostics_mask')
+   DirectILLTubeBackground('ws', OutputWorkspace='bkg',
+       EPPWorkspace='epp', DiagnosticsWorkspace='diagnostics_mask')
+   bkg = mtd['bkg']
+   # Apply the background
+   ws_bkg_subtracted = Subtract('ws', bkg)
+   # Plot the background levels of tubes in the forward direction
+   bkg_y = bkg.extractY()
+   fig, ax = plt.subplots(subplot_kw={'projection':'mantid'})
+   xs = np.arange(0, bkg.getNumberHistograms())
+   ax.plot(xs, bkg_y[:, 0])
+   ax.set_xlim(xmin=70000)
+   ax.set_xlabel('Workspace index')
+   ax.set_ylabel('Background')
+   # Uncomment the following to show the plot
+   #fig.show()
+   # Remove all workspaces
+   mtd.clear()
+
+.. categories::
+
+.. sourcelink::
+

docs/source/techniques/DirectILL.rst

@@ -7,7 +7,7 @@ Data reduction for ILL's direct geometry instruments
 .. contents:: Table of contents
     :local:
 
-There are six workflow algorithms supporting data reduction at ILL's time-of-flight instruments. These algorithms are:
+There are seven workflow algorithms supporting data reduction at ILL's time-of-flight instruments. These algorithms are:
 
 :ref:`algm-DirectILLCollectData`
     Loads data from disk and applies some simple reduction steps. The starting point of all reductions, as most of the other DirectILL algorithms expect their input data to originate from here.
@@ -27,6 +27,9 @@ There are six workflow algorithms supporting data reduction at ILL's time-of-fli
 :ref:`algm-DirectILLApplySelfShielding`
     Applies absorption corrections and subtracts an empty container measurement.
 
+:ref:`algm-DirectILLTubeBackground`
+    Calculates a per-tube backgrounds for position sensitive tubes such as found in IN5.
+
 The algorithms can be used as flexible building blocks in Python scripts. Not all of them need to be necessarily used in a reduction: the simplest script could call :ref:`algm-DirectILLCollectData` and :ref:`algm-DirectILLReduction` only.
 
 Together with the other algorithms and services provided by the Mantid framework, the reduction algorithms can handle a great number of reduction scenarios. If this proves insufficient, however, the algorithms can be accessed using Python. Before making modifications it is recommended to copy the source files and rename the algorithms as not to break the original behavior.
@@ -121,6 +124,76 @@ Every ``DirectILL`` algorithm has an *OutputWorkspace* property which provides t
 
 As shown above, these optional outputs are sometimes named similarly the corresponding inputs giving a hint were they are supposed to be used.
 
+Time-independent background for position sensitive tubes
+========================================================
+
+The flat background subtraction in :ref:`algm-DirectILLCollectData` does not work properly for instruments such as IN5. Another algorithm, :ref:`algm-DirectILLTubeBackground` should be used instead. For this algorithm, one should run :ref:`algm-DirectILLDiagnostics` to utilize the default hard mask and beam stop masking in the background determination.
+
+.. code-block:: python
+
+    # Add a temporary data search directory.
+    mantid.config.appendDataSearchDir('/data/')
+
+    # Vanadium
+    DirectILLCollectData(
+        Run='0100-0109',
+        OutputWorkspace='vanadium',
+        OutputEPPWorkspace='vanadium-epps',  # Elastic peak positions.
+    )
+
+    DirectILLDiagnostics(
+        InputWorkspace='vanadium-raw',
+        OutputWorkspace='diagnostics',
+    )
+
+    # Determine time-independent background
+    DirectILLTubeBackground(
+        InputWorkspace='vanadium',
+        OutputWorkspace='vanadium-background'
+        EPPWorkspace='vanadiums-epps',
+        DiagnosticsWorkspace='diagnostics'
+    )
+    # Subtract the background
+    Subtract(
+        LHSWorkspace='vanadium'
+        RHSWorkspace='vanadium-background',
+        OutputWorkspace='vanadium-bkgsubtr'
+    )
+
+    DirectILLIntegrateVanadium(
+        InputWorkspace='vanadium-bkgsubtr',  # Integrate background subtracted data
+        OutputWorkspace='integrated',
+        EPPWorkspace='vanadium-epps'
+    )
+
+    # Sample
+    DirectILLCollectData(
+        Run='0201+0205+0209-0210',
+        OutputWorkspace='sample',
+        OutputEPPWorkspace='sample-epps'
+    )
+
+    # Determine time-independent background
+    DirectILLTubeBackground(
+        InputWorkspace='sample',
+        OutputWorkspace='sample-background',
+        EPPWorkspace='sample-epps',
+        DiagnosticsWorkspace='diagnostics'
+    )
+    Subtract(
+        LHSWorkspace='sample',
+        RHSWorkspace='sample-background',
+        OutputWorkspace='sample-bkgsubtr'
+    )
+
+    DirectILLReduction(
+        InputWorkspace='sample-bkgsubtr',
+        OutputWorkspace='SofQW',
+        IntegratedVanadiumWorkspace='integrated'
+        DiagnosticsWorkspace='diagnostics'
+    )
+
+
 Self-shielding corrections
 ==========================