Merge pull request #248 from mantidproject/feature/10875_integrate_el…

…lipsoids_docs

IntegrateEllipsoids Better Documentation

Code/Mantid/Framework/MDEvents/src/Integrate3DEvents.cpp

@@ -188,11 +188,17 @@ int Integrate3DEvents::numInEllipsoid(std::vector<V3D> const &events,
 
 /**
  *  Given a list of events, associated with a particular peak
- *  and SHIFTED to be centered at (0,0,0), calculate the 3x3
+ *  and already SHIFTED to be centered at (0,0,0), calculate the 3x3
  *  covariance matrix for finding the principal axes of that
  *  local event data.  Only events within the specified radius
  *  of (0,0,0) will be used.
  *
+ *  The covariance matrix can be easily constructed. X, Y, Z of each peak position are the variables we wish to determine
+ *  the covariance. The mean position in each dimension has already been calculated on subtracted, since this corresponds to the centre position of each
+ *  peak, which we knew aprori. The expected values of each correlation test X,X X,Y X,Z e.t.c form the elements of this 3 by 3 matrix, but since the
+ *  probabilities are equal, we can remove them from the sums of the expected values, and simply divide by the number of events for each matrix element.
+ *  Note that the diagonal elements form the variance X,X, Y,Y, Z,Z
+ *
  *  @param events    Vector of V3D objects containing the
  *                   Q vectors for a peak, with mean at (0,0,0).
  *  @param matrix    A 3x3 matrix that will be filled out with

Code/Mantid/docs/source/algorithms/IntegrateEllipsoids-v1.rst

@@ -110,7 +110,7 @@ added to the list of events for a peak provided that the fractional
 :math:`Q` -vector) is closer to the :math:`h,k,l` of that peak, 
 than to the :math:`h,k,l` of any
 other peak AND the :math:`Q` -vector for that event is within the specified
-radius of the :math:`Q` -vector for that peak.
+radius of the :math:`Q` -vector for that peak. This technique makes the algorithm suitable for nuclear peaks, but may not be suitable for magnetic peaks.
 
 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
@@ -155,6 +155,8 @@ ellipsoid. The outer surface of the background ellipsoidal shell is an
 ellipsoidal surface with the same relative axis lengths as the inner
 surface.
 
+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.
+
 Usage
 ------