.. algorithm::

.. summary::

.. relatedalgorithms::

.. properties::

Description
-----------

Overview and similar algorithms
###############################

This algorithm will integrate disjoint single crystal Bragg peaks
by summing the number of raw or weighted events in a 3D ellipsoidal peak region in
reciprocal space (QLab frame) and subtracting an estimate of the background obtained
from an ellipsoidal shell.
In some ways it is similar to the :ref:`algm-IntegratePeaksMD` algorithm.
In particular the size parameters to this algorithm are also specified in inverse Angstroms
and the background subtraction is done in the same way for both the intensity and the
estimated standard deviations.
However, this algorithm differs from :ref:`algm-IntegratePeaksMD` in several critical ways.

-  This algorithm works directly with raw or weighted events
   while :ref:`algm-IntegratePeaksMD` uses **MDEvents** from
   :ref:`MDEventWorkspace <MDWorkspace>`.
-  This algorithm uses 3D ellipsoidal regions with aspect ratios that
   are adapted to the set of events that are near the peak center, while
   :ref:`algm-IntegratePeaksMD` uses spherical or ellipsoidal regions.
-  This algorithm includes an option to automatically choose the size of
   the ellipsoidal regions based on the statistics of the set of events
   near the peak.

The algorithm calculates the three principal axes of the events near a
peak, and uses the standard deviations in the directions of the
principal axes to determine the aspect ratio of ellipsoids used for the
peak and background regions.

By default, the satellite peaks are processed through the same pipeline as the Bragg peaks.
If desired, users can specify satellite peaks specific integration parameters so that
a different integrator is used to integrate the satellite peaks.

Explanation of Inputs
#####################

-  The event data to be integrated is obtained from an ordinary
   :ref:`EventWorkspace <EventWorkspace>`
   with an X-axis in time-of-flight, as loaded from a
   NeXus event file. This algorithm maps the events to reciprocal space
   using *PeaksWorkspace* with indexed peaks to determine the parameters
   of the transformation into the reciprocal space

-  The peaks to be integrated are are also obtained from a *PeaksWorkspace*. The
   peaks must be indexed, and any peaks indexed as (0,0,0) will be
   ignored.

-  Only events that are near a peak are considered when constructing the
   ellipsoids. The *RegionRadius* specifies the maximum distance from the
   peak center to an event in reciprocal space, for that event to be used.
   See the figure below. Also, each event will be counted for at most
   one peak, the one with the nearest QLab value. The RegionRadius should
   be specified to be just slightly larger than the expected peak region
   to avoid overlap with other peaks, and to avoid including excessive
   background. As the size of the *RegionRadius* increases, the ellipsoids
   will become more spherical and less well adapted to the actual shape
   of the peak.

.. figure:: /images/IntegrateEllipsoids.png
   :alt: IntegrateEllipsoids.png

   Integrate ellipsoids algorithm regions map.

-  If the *SpecifySize* option is selected, then the user MUST specify the
   *PeakSize*, *BackgroundInnerSize* and *BackgroundOuterSize*. In this mode,
   the algorithm is similar to the :ref:`algm-IntegratePeaksMD` algorithm. As shown
   in the figure, these values determine the length of the major axis
   for the ellipsoidal peak region, and of the inner and outer
   ellipsoids bounding the background region. The same major axis
   lengths are used for all peaks, but the lengths of the other two axes
   of the ellipsoids are adjusted based on the standard deviations of
   the events in those directions. If *SpecifySize* is false, then the
   major axis length for each peak will be set to include a range of
   plus or minus three times the standard deviation of the events in
   that direction. That is, *PeakSize* is set to three times the standard
   deviation in the direction of the first principal axis. Also, in this
   case the *BackgroundInnerSize* is set to the *PeakSize* and the
   *BackgroundOuterSize* is set so that the background ellipsoidal shell
   has the same volume as the peak ellipsoidal region. If specified by
   the user, these parameters must be ordered correctly with:
   :math:`0 < PeakSize \leq BackgroundInnerSize` and
   :math:`BackgroundInnerSize < BackgroundOuterSize \leq RegionRadius`

-  If *UseOnePercentBackgroundCorrection* is enabled, then the top 1% of the background
   events are removed so that there are no intensity spikes near the edges. This
   is enabled by default.

-  *AdaptiveQMultiplier* can be used with *SpecifySize* for the radius to vary as
   a function of the modulus of Q. If the *AdaptiveQBackground* option is set to True,
   the background radius also changes so each peak has a different integration
   radius. Q includes the 2*pi factor.

   -  PeakRadius + AdaptiveQMultiplier * **|Q|**
   -  BackgroundOuterRadius + AdaptiveQMultiplier * **|Q|**
   -  BackgroundInnerRadius + AdaptiveQMultiplier * **|Q|**

-  The integrated intensities will be set in the specified
   *OutputWorkspace*. If this is different from the input *PeaksWorkspace*,
   the input peaks workspace will be copied to the *OutputWorkspace*
   before setting the integrated intensities.

Detailed Algorithm Description
##############################

This algorithm will integrate a list of indexed single-crystal
diffraction peaks from a *PeaksWorkspace*, using events from an
( :ref:`EventWorkspace <EventWorkspace>` ).

Given and input **RegionRadius**, QLab space is partitioned into a
cubic lattice with unit cell of size **RegionRadius**. This guarantees
that no two peaks can occupy the same cell. Events are distributed
among the cells according to their QLab Q-vectors. Later, each of the cells
containing one peak is inspected for the events it contains, as well as
its 27 fist-neighbor cells. The events thus collected are inspected to
determine which lie within **RegionRadius** of the peak Q-vector.

When the lists of events near the peaks have been built, the three
principal axes of the set of events near each peak are found, and the
standard deviations of the projections of the events on each of the
three principal axes are calculated. The principal axes and standard
deviations for the events around a peak in the directions of the
principal axes are used to determine an ellipsoidal region for the peak
and an ellipsoidal shell region for the background. The number of events
in the peak ellipsoid and background ellipsoidal shell are counted and
used to determine the net integrated intensity of the peak.

The ellipsoidal regions used for the peak and background can be obtained
in two ways. First, the user may specify the size of the peak ellipsoid
and the inner and outer size of the background ellipsoid. If these are
specified, the values will be used for half the length of the major axis
of an ellipsoid centered on the peak. The major axis is in the direction
of the principal axis for which the standard deviation in that direction
is largest. The other two axes for the ellipsoid are in the direction of
the other two principal axes and are scaled relative to the major axes
in proportion to their standard deviations. For example if the standard
deviations in the direction of the other two principal axes are .8 and .7
times the standard deviation in the direction of the major axis, then
the ellipse will extend only .8 and .7 times as far in the direction of
those axes, as in the direction of the major axis. Overall, the user
specified sizes for the *PeakSize*, *BackgroundInnerSize* and
*BackgroundOuterSize* are similar to the *PeakRadius*, *BackgroundInnerRadius*
and *BackgrounOuterRadius* for the :ref:`algm-IntegratePeaksMD` algorithm. The
difference is that the regions used in this algorithm are not spherical,
but are ellipsoidal with axis directions obtained from the principal
axes of the events near a peak and the ellipsoid shape (relative axis
lengths) is determined by the standard deviations in the directions of
the principal axes.

Second, if the user does not specify the size of the peak and
background ellipsoids, then the three axes of the peak ellipsoid are
again set to the principal axes of the set of nearby events but in this
case their axis lengths are set to cover a range of plus or minus three
standard deviations in the axis directions. In this case, the background
ellipsoidal shell is chosen to have the same volume as the peak
ellipsoid and it's inner surface is the outer surface of the peak
ellipsoid. The outer surface of the background ellipsoidal shell is an
ellipsoidal surface with the same relative axis lengths as the inner
surface.

By default, the algorithm does not distinguish satellite peaks from Bragg
peaks by using identical integrators for two different type of peaks.
However, users can specify *SatelliteRegionRadius*, *SatellitePeakSize*,
*SatelliteBackgroundInnerSize* and *SatelliteBackgroundOuterSize* such that
the integrator used for satellite peaks are different from the one used for
Bragg Peaks.

This algorithm uses principle component analysis to determine the principle
axis for each peak. For the event list (QLab) associated with each peak,
the algorithm determines a covariance matrix, and uses that to establish
eigenvectors corresponding to the principle axis (all orthogonal).
The sizes of each principle axis are used define the region of which events
will be counted/integrated from those already associated with each peak.

IntegrateIfOnEdge=False option
##############################

Edges for each bank or pack of tubes of the instrument are defined by masking
the edges in the PeaksWorkspace instrument. e.g. For CORELLI, tubes 1 and 16,
and pixels 0 and 255. Q in the lab frame for every peak is calculated, call it C
For every point on the edge, the trajectory in reciprocal space is a straight line,
going through:

:math:`\vec{O}=(0,0,0)`

Calculate a point at a fixed momentum, say k=1.
Q in the lab frame:

:math:`\vec{E}=(-k \cdot \sin(\theta) \cdot \cos(\phi), -k \cdot \sin(\theta) \cdot \sin(\phi), k - k \cdot \cos(\phi))`

Normalize E to 1:

:math:`\vec{E}=\vec{E} \cdot (1./\left|\vec{E}\right|)`

The distance from C to OE is given by:

:math:`dv=\vec{C}-\vec{E} \cdot (\vec{C} \cdot \vec{E})`

If:

:math:`\left|dv\right|<PeakRadius`

for the integration, one of the detector trajectories on the edge is too close to the peak
This method is also applied to all masked pixels. If there are masked pixels
trajectories inside an integration volume, the peak must be rejected.
If there are masked pixel trajectories inside the background volume, the background
events are scaled by estimating the volume of the ellipsoid on the detector.

ShareBackground option
######################

With this option enabled, satellite peaks will share the integrated background
intensity and volume of its corresponding Bragg peak. The integrated intensity
of satellite peaks will still use the radii set with **SatelliteRegionRadius**
and **SatelitePeakSize** though its background intensity will be borrowed
from its Bragg peak.

In cases where a Bragg peak could not be found for a satellite peak, then the background
for the satellite peak is determined as normal using the values of **SatelliteBackgroundInnerSize**
and **SatelliteBackgroundOuterSize** for background subtraction.

Sigma from the background
#########################
The sigma from the background could be too small because the background contains
events from other peaks. In an effort to reduce this, all the background events
are sorted and the top 1% are removed. Note that this behaviour is optional and
can be enabled if the property *UseOnePercentBackgroundCorrection* is enabled.
It is enabled by default.

Usage
------

**Example - IntegrateEllipsoids:**

User should provide their own event nexus file instead of **TOPAZ_3132_event.nxs** used within this example. The original **TOPAZ_3132_event.nxs**
file is available in `Mantid system tests repository <https://github.com/mantidproject/systemtests/tree/master/Data/TOPAZ_3132_event.nxs>`_.

.. code-block:: python
   :linenos:

   def print_tableWS(pTWS,nRows):
       ''' Method to print part of the table workspace '''
       tab_names=pTWS.keys()
       row = ""
       for name in tab_names:
           if len(name)>8:
              name= name[:8]
           row += "| {:8} ".format(name)
       print(row + "|")

       for i in range(nRows):
           row = ""
           for name in tab_names:
                 col = pTWS.column(name);
                 data2pr=col[i]
                 if type(data2pr) is float:
                     row += "| {:8.1f} ".format(data2pr)
                 else:
                     row += "| {:8} ".format(str(data2pr))
           print(row + "|")

   # load test workspace
   Load(Filename=r'TOPAZ_3132_event.nxs',OutputWorkspace='TOPAZ_3132_event',LoadMonitors='1')

   # build peak workspace necessary for IntegrateEllipsoids algorithm to work
   ConvertToMD(InputWorkspace='TOPAZ_3132_event',QDimensions='Q3D',dEAnalysisMode='Elastic',Q3DFrames='Q_sample',LorentzCorrection='1',OutputWorkspace='TOPAZ_3132_md',\
   MinValues='-25,-25,-25',MaxValues='25,25,25',SplitInto='2',SplitThreshold='50',MaxRecursionDepth='13',MinRecursionDepth='7')
   FindPeaksMD(InputWorkspace='TOPAZ_3132_md',PeakDistanceThreshold='0.3768',MaxPeaks='50',DensityThresholdFactor='100',OutputWorkspace='TOPAZ_3132_peaks')
   FindUBUsingFFT(PeaksWorkspace='TOPAZ_3132_peaks',MinD='3',MaxD='15',Tolerance='0.12')
   IndexPeaks(PeaksWorkspace='TOPAZ_3132_peaks',Tolerance='0.12')

   # integrate Ellipsoids
   result=IntegrateEllipsoids(InputWorkspace='TOPAZ_3132_event',PeaksWorkspace='TOPAZ_3132_peaks',\
          RegionRadius='0.25',PeakSize='0.2',BackgroundInnerSize='0.2',BackgroundOuterSize='0.25',OutputWorkspace='TOPAZ_3132_peaks')

   # print 10 rows of resulting table workspace
   print_tableWS(result,10)


**Output:**

.. code-block:: none
   :linenos:

   | RunNumbe | DetID    | h        | k        | l        | Waveleng | Energy   | TOF      | DSpacing | Intens   | SigInt   | BinCount | BankName | Row      | Col      | QLab     | QSample  | PeakNumb |
   | 3132     | 1124984  |     -2.0 |     -1.0 |      2.0 |      3.1 |      8.5 |  14482.3 |      2.0 | 120486.0 |    375.8 |   1668.0 | bank17   |    120.0 |     42.0 | [1.57771,1.21779,2.37854] | [2.99396,0.815958,0.00317344] | 1        |
   | 3132     | 1156753  |     -3.0 |     -2.0 |      3.0 |      2.1 |     18.8 |   9725.7 |      1.3 | 149543.0 |    393.0 |   1060.0 | bank17   |    145.0 |    166.0 | [2.48964,1.45725,3.88666] | [4.52618,1.71025,0.129461] | 2        |
   | 3132     | 1141777  |     -4.0 |     -2.0 |      3.0 |      1.7 |     28.1 |   7963.2 |      1.0 |   8744.0 |    106.3 |     96.0 | bank17   |     17.0 |    108.0 | [2.60836,2.31423,4.86391] | [5.69122,1.79492,-0.452799] | 3        |
   | 3132     | 1125241  |     -4.0 |     -2.0 |      4.0 |      1.6 |     33.9 |   7252.2 |      1.0 |  19740.0 |    146.2 |     83.0 | bank17   |    121.0 |     43.0 | [3.15504,2.42573,4.75121] | [5.97829,1.63473,0.0118744] | 4        |
   | 3132     | 1170598  |     -4.0 |     -3.0 |      4.0 |      1.5 |     34.1 |   7224.6 |      0.9 |  15914.0 |    131.4 |     73.0 | bank17   |    166.0 |    220.0 | [3.43363,1.70178,5.39301] | [6.07726,2.59962,0.281759] | 5        |
   | 3132     | 1214951  |     -2.0 |     -1.0 |      4.0 |      1.9 |     22.8 |   8839.5 |      1.7 | 121852.0 |    352.9 |    719.0 | bank18   |    231.0 |    137.0 | [2.73683,1.43808,2.11574] | [3.5786,0.470838,1.00329] | 6        |
   | 3132     | 1207827  |     -3.0 |     -1.0 |      4.0 |      1.7 |     27.9 |   7991.7 |      1.3 |  64593.0 |    257.7 |    447.0 | bank18   |     19.0 |    110.0 | [2.80324,2.29519,3.09134] | [4.71517,0.554412,0.37714] | 7        |
   | 3132     | 1232949  |     -4.0 |     -2.0 |      6.0 |      1.2 |     53.3 |   5782.1 |      0.9 |  18247.0 |    139.3 |     45.0 | bank18   |     53.0 |    208.0 | [4.29033,2.63319,4.46168] | [6.52658,1.27985,1.00646] | 8        |
   | 3132     | 1189484  |     -4.0 |     -1.0 |      6.0 |      1.1 |     63.4 |   5299.3 |      1.0 |  13512.0 |    120.7 |     31.0 | bank18   |    108.0 |     38.0 | [4.02414,3.39659,3.83664] | [6.4679,0.298896,0.726133] | 9        |
   | 3132     | 1218337  |     -5.0 |     -2.0 |      7.0 |      1.0 |     79.8 |   4724.1 |      0.8 |   7411.0 |     88.3 |     15.0 | bank18   |     33.0 |    151.0 | [4.96622,3.61607,5.32554] | [7.99244,1.19363,0.892655] | 10       |


**Example - IntegrateEllipsoids with satellite peaks:**

Users should test this function with the data set that contains satellite peaks (such as **TOPAZ_36079_crop.nxs** from the testing data).
The first peak is a satellite peak, which was integrated using the satellite peak integrator, while the other peaks are regular Bragg peaks integrated using the default integrator.

.. code-block:: python
   :linenos:

   Load(Filename='TOPAZ_36079_crop.nxs',OutputWorkspace='ws',FilterByTofMin=500,FilterByTofMax=16666)
   UB = np.array([[0.15468228,0.10908475,-0.14428671],[-0.08922105,-0.08617147,-0.22976459],[-0.05616441,0.12536522,-0.03238277]])
   ConvertToMD(
      InputWorkspace='ws',
      QDimensions='Q3D',
      dEAnalysisMode='Elastic',
      Q3DFrames='Q_sample',
      LorentzCorrection=True,
      OutputWorkspace='md',
      MinValues='1,1,1.675',
      MaxValues='10,5,8.425')
   CreatePeaksWorkspace(InstrumentWorkspace='crop', NumberOfPeaks=0, OutputWorkspace='peaks')
   SetUB('peaks', UB=UB)
   AddPeakHKL('peaks', [0.15, 1.85, -1])
   AddPeakHKL('peaks', [1, 4, -3])
   AddPeakHKL('peaks', [1, 5, -3])
   # perform integration
   IntegrateEllipsoids(
      InputWorkspace='ws',
      PeaksWorkspace='peaks',
      RegionRadius=0.055,
      SpecifySize=True,
      PeakSize=0.0425,
      BackgroundInnerSize=0.043,
      BackgroundOuterSize=0.055,
      OutputWorkspace='peaks_integrated_satellite',
      CutoffIsigI=5,
      UseOnePercentBackgroundCorrection=False,
      SatelliteRegionRadius=0.1,
      SatellitePeakSize=0.08,
      SatelliteBackgroundInnerSize=0.081,
      SatelliteBackgroundOuterSize=0.1,
      )


.. categories::


.. sourcelink::
   :filename: IntegrateEllipsoidsV1