diff --git a/docs/source/cutting.rst b/docs/source/cutting.rst index 5f2812d65..3f55640bd 100644 --- a/docs/source/cutting.rst +++ b/docs/source/cutting.rst @@ -30,10 +30,9 @@ integrate over [0,3], [3,6], [6,9] and [9,10] respectively. Cuts with the same range from multiple datasets can be plotted by first selecting multiple workspaces in the left panel. -There are two different methods to compute cuts: ``Rebin`` and ``Integration``. -**NOTE: for mantid major releases from** ``v6.40``\ **, the default cutting algorithm has been changed from** ``Rebin`` -**to** ``Integration``\ **. For more detail on this change, and cutting algorithms in general, see the** *Cutting Algorithms* -**section below**. +There are two different methods to compute cuts: ``Rebin`` and ``Integration``, which can be selected from the +``Cut Algorithm`` drop down menu. The difference between these methods are described in the :ref:`Cutting_Algorithms` +section below and in more detail in the :ref:`Mathematical_Reference`. Clicking on the ``Norm to 1`` check box will cause the resulting cut data to be normalised such that the maximum of the data of each cut is unity. @@ -92,12 +91,33 @@ that tab. When MSlice is used as a Mantid interface ``MD Histo`` type workspaces can also be saved to Mantid Workbench by clicking the ``Save to Workbench`` button either on the ``MD Histo`` or the ``Cut`` tab. +.. _Cutting_Algorithms: + Cutting Algorithms ------------------ -There are two different methods used to compute cuts. ``Rebin`` uses the basic rebinning algorithms directly and effectively averages -the counts in the integration range, whilst ``Integration`` sums the counts in the integration range. -For mantid major releases from ``v6.40``, the default cutting algorithm has been changed from ``Rebin`` to ``Integration``. This change -has been made because the ``Integration`` method can be used for both absolute and non-absolute units measurements. Conversely, for -absolute units measurements the ``Rebin`` method will give incorrect and misleading values. -As a result of this change, it is expected that values calculanced henceforth will differ from those calculated historically, if the -default integration method has been used. + +There are two different methods used to compute cuts: + +- ``Integration`` sums the (signal :math:`\times` bin width) in the integration range. +- ``Rebin`` averages the signal in the integration range. + +The two methods are described in more detail in the :ref:`Mathematical_Reference`, +but in short, there is a bin-dependent conversion factor between the two types of +cuts which depends on the data coverage in the integration range of that bin. +That is, if the integration range does not include regions without data +(e.g. due to kinematic constraints), then the two cuts will be equivalent except +for a constant scaling factor (proportional to the integration range). +However, if the integration range overlaps regions without data, +then the two cuts will give markedly different results. + +The default method is ``Rebin`` and is more suitable for DOS-types cuts which +integrate over :math:`|Q|` whilst if you are interested in cross-sections and +are integrating over energy transfer, it is recommended to use ``Integration``. + +There is an option in the ``Cut`` tab to change the cut algorithm from ``Rebin`` +to ``Integration`` or vice versa and this setting will be saved for subsequent +similar cuts on the same workspace. + +You can also change the default using the ``Options`` menu, ``Cut algorithm default`` +entry. This will change the default cut algorithm *for this session of MSlice* +(the default algorithm will revert to ``Rebin`` if you restart MSlice). diff --git a/docs/source/images/math_ref/rebin_cuts.png b/docs/source/images/math_ref/rebin_cuts.png new file mode 100644 index 000000000..94279ca61 Binary files /dev/null and b/docs/source/images/math_ref/rebin_cuts.png differ diff --git a/docs/source/images/math_ref/rebin_grids.svg b/docs/source/images/math_ref/rebin_grids.svg new file mode 100644 index 000000000..a0b72faa1 --- /dev/null +++ b/docs/source/images/math_ref/rebin_grids.svg @@ -0,0 +1,725 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/index.rst b/docs/source/index.rst index 7cb4b79a9..74412db5c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,6 +18,7 @@ to report any bugs or suggest any improvements to the program. cutting slicing cli + math_ref * :ref:`search` diff --git a/docs/source/math_ref.rst b/docs/source/math_ref.rst new file mode 100644 index 000000000..173068513 --- /dev/null +++ b/docs/source/math_ref.rst @@ -0,0 +1,210 @@ +.. _Mathematical_Reference: + +Mathematical Reference +====================== + +This page describes the mathematical operations behind the ``Slice`` and ``Cut`` operations of MSlice + +In general, MSlice handles "reduced" (processed) inelastic neutron scattering data which has been +binned (histogrammed) in energy transfer for each detector / position-sensitive-detector (PSD) element. +We will use the terminology of the `Horace `_ program and +refer to these energy-detector-element bins as "pixels". + +Since the detector elements are in the laboratory coordinates, but we often want to plot the data +in reciprocal space, a coordinate transformation is needed. +This means that the input and output binning grids of the data will not be axis aligned, and will +instead look something like this: + +.. _grid_figure: + +.. image:: images/math_ref/rebin_grids.svg + :width: 600 + +Where the square red grid represents the target (output) bins, and the slanted green grids +(parallelograms) represents the original bins ("pixels"). +As discussed in the :ref:`PSD_and_non-PSD_modes` section, MSlice makes a distinction between +**PSD** (fine green grid) and **non-PSD** (coarser green grid) data. + +A ``Slice`` refers to a rebin into a two dimensional output, whilst a ``Cut`` is a rebin _or_ +integration into a one dimensional output. +For each type of data (**PSD** and **non-PSD**) we will describe each operation in turn. + + +PSD Slice +--------- + +For **PSD** data, MSlice uses *centre-point rebinning*, treating each input bin ("pixel") as a +point and summing the full signal of each pixel whose centres lie within an output bin +(illustrated in the image by the darker green shading in top left, with dots marking centres). +Thus the output signal in the :math:`(i,j)`\ th bin, :math:`Y_{ij}`, is: + +.. math:: + Y_{ij} = \frac{1}{N_{kl}} \sum_{kl} y_{kl} + +where :math:`y_{kl}` is the input signal in the input :math:`(k,l)`\ th bin +and the sum runs over the :math:`N_{kl}` number of bins whose centres lie within the +boundaries of the :math:`(i,j)`\ th output bin. + +The above expression uses the ``NumEventsNormalization`` convention of Mantid which is the +same as that adopted by the `Horace `_ program. +The error values are considered to be standard deviations and are summed in quadrature. + +PSD Cut +------- + +Since MSlice allows users to specify bins in the non-integrating direction which are not +necessarily aligned with respect to the original data, a rebinning step as described above +is needed for the ``Cut`` operation too. + +This leads to the two types of behaviour ("algorithms") for the ``Cut`` operation described +in the :ref:`Cutting_Algorithms` section: + +- The default ``Rebin`` method just uses the rebinning described above with one axis having + only a single bin. +- The ``Integration`` method first rebins the data as described above with the integration axis + divided into :math:`N_{\mathrm{int}} =` 100 bins. + It then calls the relevant Mantid algorithm + (`IntegrateMDHistoWorkspace `_\ ) + to integrate (sums the signal) in those 100 bins. + +Taking the :math:`j` index to be over the integration axis, the integrated ``Cut`` signal +:math:`C_i` is then given by: + +.. math:: + C_i^{\mathrm{integration}} = w_i \sum_{j \in \mathcal{D}} Y_{ij} + +where the index :math:`j` only runs over regions with data :math:`\mathcal{D}`, and the width +:math:`w_i = \sum_{j \in \mathcal{D}} w_{ij}` where :math:`w_{ij}` is the width in the +:math:`j`\ th direction of the :math:`(i,j)`\ th bin. + +Note that the equivalent expression for a ``Rebin`` cut is simply: + +.. math:: + C_i^{\mathrm{rebin}} = \sum_{j \in \mathcal{F}} Y_{ij} + +where now the index :math:`j` runs over the full integration range :math:`\mathcal{F}`. +The difference is thus a coordinate-dependent weighting factor :math:`w_i`. +If the integration range *does not include regions without data* (e.g. :math:`\mathcal{D} \equiv \mathcal{F}`) +then all the :math:`w_i` will be equal to the full integration width and the difference between +:math:`C_i^{\mathrm{integration}}` and :math:`C_i^{\mathrm{rebin}}` is a constant. + +However, if the integration range covers region with no data (e.g. beyond the kinematic limits) +then the two cuts *may* look very different because :math:`C_i^{\mathrm{integration}}` will weight +regions with data more heavily than regions without data. + + +Non-PSD Slice +------------- + +For **non-PSD** data, MSlice uses *fractional rebinning*, where it first calculates the +overlap area between the input and output bins, and then sums only the fraction of the +signal of the input bins which overlaps the output bin. + +The output signal is computed as: + +.. math:: + Y_{ij} = \left. \sum_{kl} y_{kl} f_{kl} \right/ \sum_{kl} f_{kl} + +and the output uncertainty as: + +.. math:: + E_{ij} = \left. \sqrt{\sum_{kl} e^2_{kl} f_{kl}} \right/ \sum_{kl} f_{kl} + +where :math:`f_{kl}` is the fractional overlap of the input :math:`(k,l)`\ th bin with +the output :math:`(i,j)`\ th bin. + +This is illustrated in the :ref:`figure ` at the start of the page by the square on the right +hand side with blue triangular and orange quadrilateral shaded regions. +The blue and orange shading illustrates the fractional overlap areas which weights +the signal in the top left and top right input bins (large parallelograms) respectively. + +Non-PSD Cuts +------------ + +Like for **PSD** data, there are two ``Cut`` "algorithms" for **non-PSD** data also. + +The ``Rebin`` cut algorithm performs the same operation described in the previous section +but with a single bin in the integration axis, yielding + +.. math:: + C_i^{\mathrm{rebin}} = \left. \sum_{j \in \mathcal{F}} Y_{ij} \right/ \sum_{j \in \mathcal{F}} F_{ij} + +where :math:`F_{ij} = \sum_{kl} f_{kl}`, and :math:`\mathcal{F}` indicates the full integration range. + +In order to support rebinning in the non-integration axis, the ``Integration`` algorithm +first rebins the data into the desired bins in the non-integration axis, +and 100 bins in the integration axis and then sums them as: + +.. math:: + C_i^{\mathrm{integration}} = \left. N_i \sum_{j \in \mathcal{F}} Y_{ij} w_{ij} \right/ \sum_{j \in \mathcal{F}} F_{ij} + +where :math:`N_i = \sum_{j \in \mathcal{D}} 1` is the number of :math:`j` bins at a given +:math:`i` *with non-zero fraction* (e.g. if the integration contains only regions with data +then :math:`N_i` = 100, otherwise :math:`N_i` will be less), +and :math:`w_{ij}` is the width along the :math:`j`\ th axis of the :math:`(i,j)`\ th bin. +The :math:`N_i` normalisation is needed because in the limiting case where all the fractions +:math:`F_{ij}` are unity, the denominator would be :math:`N_i`, so we recover the usual +expression for integrating over a distribution. +Note that as previously, :math:`\mathcal{D}` indicates the region within the integration +range with data (in this case equivalent to regions with non-zero fractions). + +Like with the **PSD** case there is thus an :math:`i` dependent scaling factor :math:`N_i w` +(assuming all the bins have the same width) between ``Cuts`` computed using the ``Rebin`` or +``Integration`` algorithm. +This scaling factor is a constant if the integration range includes only regions with data +(e.g. :math:`\mathcal{D} \equiv \mathcal{F}`), but will not be constant if the integration +overlaps regions without data. + +The difference is illustrated below: + +.. image:: images/math_ref/rebin_cuts.png + +The cuts have been normalised to the peak intensity so that the constant scaling factor between +the two algorithms factorises out. +In the top cut, integrating over :math:`6 \leq |Q| < 8 \mathrm{\AA}^{-1}` there are no regions +without data so the two cuts are equivalent except for a constant scaling factor. +In the bottom cut, integrating over :math:`8 \leq |Q| < 10 \mathrm{\AA}^{-1}` there is a large +region with no data, so now cuts from the two techniques differ markedly. +At :math:`E<0` meV Where the data covers the full integration range, we have :math:`N_i` = 100 +and the two cuts are equivalent. +As :math:`E` increases, :math:`N_i` decreases until at around 20 meV, it is :math:`N_i` = 50, +and we see that at that point the (normalised) ``Integration`` cut is half the intensity of +the (normalised) ``Rebin`` cut. + +A note on units +--------------- + +One advantage of inelastic neutron scattering over other techniques is that it is (relatively) +easy to normalise the measured data to absolute units. +At the ISIS Neutron and Muon Source if this normalisation is done, then the signal will be in +units of [milibarns per steradian per meV per formula unit] or [mb/sr/meV/f.u.]. + +An ``Integration`` over energy would then yield a differential cross-section in [mb/sr/f.u.], +whereas a ``Rebin`` over energy would leave the units unchanged at [mb/sr/meV/f.u.]. + +However, an ``Integration`` over :math:`|Q|` instead of energy will yield units of +[mb/Å/sr/meV/f.u.] rather [mb/meV/f.u.] and as such it may be more useful to perform an +average ``Rebin`` which will leave the units unchanged. + +Unfortunately, the input files read by MSlice do not indicate if the signal values saved +are in absolute units or not, so MSlice cannot automatically display the correct units on plots +- this is left to the user. + +A note on the regions of validity of the two algorithms +------------------------------------------------------- + +As can be seen in the example above, the ``Integration`` cut algorithm will produce low signals +where there is less data, whereas the ``Rebin`` cut algorithm will amplify the signals in such +regions. In effect, it assumes that the signal is constant across the integration range and +can be extrapolated over regions without data (so the only manifestation of the lack of data +are larger errorbars associated with these bins). + +This assumption *may* be valid for density-of-states (DOS) type cuts where one would expect +that the signal is approximately constant over :math:`|Q|` and only varies in energy. +Thus for these applications, it may be suitable to chose the ``Rebin`` algorithm, and to +extrapolate the high-energy, high-:math:`|Q|` regions which are kinematically inaccessible. + +Conversely, for integration over energy - for example over the elastic line to compute a +differential cross-section or over a finite energy crystal field excitation to obtain a +magnetic cross-section, the ``Integration`` algorithm should be chosen else the signal +in the cut will vary with the integration range and would not be a cross-section.