Merge pull request #22835 from samueljackson92/update-docs-refine-satellite-peaks

Update RefineSatellitePeaks docs with diagrams & more info.

Framework/PythonInterface/plugins/algorithms/RefineSatellitePeaks.py

@@ -23,7 +23,8 @@ class RefineSatellitePeaks(DataProcessorAlgorithm):
         self.declareProperty(PeaksWorkspaceProperty(name="SatellitePeaks",
                                                     defaultValue="",
                                                     direction=Direction.Input),
-                             doc="Positions of seed satellite peaks. These will be used to define the q vectors for each satellite.")
+                             doc="Positions of seed satellite peaks. These will be used to define the modulation (q) \
+                             vectors for each satellite.")
 
         self.declareProperty(WorkspaceProperty(name="MDWorkspace",
                                                defaultValue="",
@@ -38,17 +39,18 @@ class RefineSatellitePeaks(DataProcessorAlgorithm):
 
         self.declareProperty('NumOfQs', -1, direction=Direction.Input,
                              doc="The number of satellite peaks to look for. If this option is not set to the default then all the \
-                             provided satellites will be grouped into exactly this number of q vectors")
+                             provided satellites will be grouped into exactly this number of modulation (q) vectors")
         self.declareProperty('ClusterThreshold', 1.5, direction=Direction.Input,
-                             doc="Threshold for automaticallty deciding on the number of q vectors to use. If NumOfQs found is set then this \
+                             doc="Threshold for automaticallty deciding on the number of modulation (q) vectors to use. If NumOfQs found is set then this \
                              is property is ignored.")
         self.declareProperty('PeakRadius', 0.1, direction=Direction.Input,
-                             doc="The peak radius used to integrate the satellite peaks. This is passed direclty to IntegratePeaksMD")
+                             doc="The peak radius used to integrate the satellite peaks. This is Euclidean distance in HKL space. \
+                             This is passed directly to IntegratePeaksMD")
         self.declareProperty('BackgroundInnerRadius', 0.1, direction=Direction.Input,
-                             doc="The inner background radius used to integrate the satellite peaks. This is passed direclty to \
+                             doc="The inner background radius used to integrate the satellite peaks. This is Euclidean distance in HKL space. This is passed directly to \
                              IntegratePeaksMD")
         self.declareProperty('BackgroundOuterRadius', 0.2, direction=Direction.Input,
-                             doc="The outer background radius used to integrate satellite peaks. This is passed direclty to \
+                             doc="The outer background radius used to integrate satellite peaks. TThis is Euclidean distance in HKL space. his is passed directly to \
                              IntegratePeaksMD")
         self.declareProperty('IOverSigma', 2, direction=Direction.Input,
                              doc="The I/sigma threshold use to identify if peaks exist. This is passed direclty to FilterPeaks")

docs/source/algorithms/RefineSatellitePeaks-v1.rst

@@ -14,6 +14,15 @@ takes a :ref:`MDWorkspace <MDWorkspace>` of experimental data, a
 integer HKL, and another PeaksWorkspace containing a subset of peaks found at
 fractional HKL. 
 
+.. figure:: /images/RefineSatellitePeaks-satellites.png
+   :align: center
+   :width: 600px
+   :alt: RefineSatellitePeaks-satellites.png
+
+   Satellite peaks exist at fractional HKL coordinates. The vector `q` is the
+   Euclidean distance from the nearest integer HKL peak to the satellite. A
+   schematic of this is shown in the HKL plane in the diagram above.
+
 For each satellite peak the euclidean distance between the nearest integer peak
 and satellite are computed in the HKL frame. Peaks are then grouped according
 to euclidean distance using using the properties `NumOfQs` and
@@ -24,6 +33,18 @@ this threshold.  The centroid of each cluster calculated for each group and is
 used as the offset to predict the location of fractional peaks everywhere in
 the :ref:`MDWorkspace <MDWorkspace>`.
 
+.. figure:: /images/RefineSatellitePeaks-clustering.png
+   :align: center
+   :width: 700px
+   :alt: RefineSatellitePeaks-clustering.png
+
+   Due to noise in the experimental data the `q` vector for every satellite may
+   vary slightly. This algorithm calculates the `q` vectors for all peaks passed
+   as starting points into distinct sets of `q` vectors. The centroid of each
+   cluster is then taken as the "true" value of `q` and is used to predict the
+   postion of all other fractional peaks with this `q`.
+   
+
 For each predicted fractional peak, the local centroid (the radius of which is
 defined by `PeakRadius`) in the MD data is found and this is taken as the actual
 position of the satellite peaks.
@@ -33,6 +54,54 @@ Finally the found satellite peaks are integerated using the
 `BackgroundInnerRadius`, and `BackgroundOuterRadius`. Satellite peaks are
 discarded if there I/sigma value is less than the parameter `IOverSigma`.
 
+.. figure:: /images/RefineSatellitePeaks-centroids.png
+   :align: center
+   :width: 700px
+   :alt: RefineSatellitePeaks-centroid.png
+
+   Finally, using the predicted satellite peak positions (green) the local
+   centroid is found and this is used as the true position of the experimental
+   satellite peak (orange). The area to search for the centroid is controlled by
+   the `PeakRadius` parameter. All centroids are integrated a filtered by
+   intensity and :math:`\frac{I}{\sigma}`. If the experimental satellite has
+   zero intesity or is below the :math:`\frac{I}{\sigma}` threshold then it is
+   discarded.
+
+
+The output of the algorithm is a peaks workspace containing all of the
+satellite peaks found by the algorithm in fractional coordinates. Each of the
+peaks will have an intensity value from the :ref:`IntegratePeaksMD
+<algm-IntegratePeaksMD-v2>` algorithm. 
+
+.. warning:: This integration is very approximate and may not produce the best
+    possible values. It is recommended that satellite peaks are reintegrated
+    using one of the many peak integration algorithms and to tune their
+    parameters to obtain the best possible peak integration. 
+
+For more information on superspace crystallography see:
+
+- Van Smaalen, Sander. "An elementary introduction to superspace 
+  crystallography." Zeitschrift für Kristallographie-Crystalline Materials 
+  219, no. 11 (2004): 681-691. 
+
+- Van Smaalen, Sander. "Incommensurate crystal structures." Crystallography 
+  Reviews 4, no. 2 (1995): 79-202. 
+
+Related Algorithms
+------------------
+- :ref:`PredictFractionalPeaks <algm-PredictFractionalPeaks-v1>` predicts the
+  postion of fractional peaks given a :ref:`PeaksWorkspace <PeaksWorkspace>` of
+  nuclear peaks and a set of HKL offsets.
+
+- :ref:`CentroidPeaksMD <algm-CentroidPeaksMD-v2>` is used to find the local 
+  centroid from a predicted peak position.
+
+- :ref:`IntegratePeaksMD <algm-IntegratePeaksMD-v2>` is used to integrate
+  satellite peaks to check if they actually exist at the predicted position.
+
+- :ref:`FilterPeaks <algm-FilterPeaks-v1>` is used to remove peaks with zero
+  intensity or a I/sigma below the desired threshold.
+
 Usage
 -----