Merge pull request #666 from mantidproject/9726_documentation

Documentation for 7 algorithms including usage examples

Code/Mantid/Framework/Crystal/src/ShowPeakHKLOffsets.cpp

@@ -32,7 +32,7 @@ void ShowPeakHKLOffsets::init() {
                                                         Direction::Input),
                   "Workspace of Peaks with UB loaded");
 
-  declareProperty(new WorkspaceProperty<TableWorkspace>("HKLIntegerOffsets",
+  declareProperty(new WorkspaceProperty<ITableWorkspace>("HKLIntegerOffsets",
                                                         "HKLIntegerOffsets",
                                                         Direction::Output),
                   "Workspace with the Results");

Code/Mantid/Framework/Crystal/test/ShowPeakHKLOffsetsTest.h

@@ -8,10 +8,10 @@
 #ifndef SHOWPEAKHKLOFFSETSTEST_H_
 #define SHOWPEAKHKLOFFSETSTEST_H_
 #include <cxxtest/TestSuite.h>
+#include "MantidAPI/ITableWorkspace.h"
 #include "MantidCrystal/LoadIsawPeaks.h"
 #include "MantidCrystal/LoadIsawUB.h"
 #include "MantidCrystal/ShowPeakHKLOffsets.h"
-#include "../../DataObjects/inc/MantidDataObjects/TableWorkspace.h"
 
 using Mantid::Crystal::LoadIsawPeaks;
 using Mantid::Crystal::LoadIsawUB;
@@ -48,7 +48,7 @@ class ShowPeakHKLOffsetsTest: public CxxTest::TestSuite
      TS_ASSERT(show.execute())
      TS_ASSERT(show.isExecuted())
      show.setProperty("HKLIntegerOffsets","offsets");
-     boost::shared_ptr<TableWorkspace> Offsets= show.getProperty("HKLIntegerOffsets");
+     boost::shared_ptr<Mantid::API::ITableWorkspace> Offsets= show.getProperty("HKLIntegerOffsets"); 
 
 
      TS_ASSERT_DELTA( Offsets->Double(3,1), 0.0186555,.1)

Code/Mantid/Testing/Data/DocTest/SXD23767.peaks.md5

@@ -0,0 +1 @@
+4ee45970b3107254198f7b132fbfacf9

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

@@ -10,7 +10,38 @@ Description
 -----------
 
 Clears the OrientedLattice of each ExperimentInfo attached to the intput
-:ref:`Workspace <Workspace>`. Works with both single ExperimentInfos and
+`Workspace <http://www.mantidproject.org/Workspace>`_. Works with both single ExperimentInfos and
 MultipleExperimentInfo instances.
 
+Usage 
+-----
+
+.. testcode:: ExClearUB
+
+   # create a workspace (or you can load one)
+   ws=CreateSingleValuedWorkspace(5)
+
+   #set a UB matrix using the vector along k_i as 1,1,0, and the 0,0,1 vector in the horizontal plane
+   SetUB(ws,a=5,b=6,c=7,alpha=90, beta=90, gamma=90, u="1,1,0", v="0,0,1")
+
+   #check that we do have a UB matrix
+   from numpy import *
+   mat=array(ws.sample().getOrientedLattice().getUB())
+   print "UB matrix size", mat.size 
+
+   ClearUB(ws)
+
+   #check that it removed UB matrix & orientated lattice
+   if( ws.sample().hasOrientedLattice() ):
+	print "ClearUB has not removed the orientated lattice."
+   else:
+	print "ClearUB has removed the oriented lattice."
+
+Output:
+
+.. testoutput:: ExClearUB
+
+   UB matrix size 9
+   ClearUB has removed the oriented lattice.
+
 .. categories::

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

@@ -17,4 +17,30 @@ only in their phi rotation.
 If the phi angles are known, this algorithm attempts to find the common
 chi and omega rotations.
 
+Usage
+-----
+
+.. include:: ../usagedata-note.txt
+
+.. testcode:: exGoniometerAnglesFromPhiRotation 
+
+   # Load Peaks found in SXD23767.raw 
+   ws1 =Load(Filename='SXD23767.peaks')
+   ws2 = ws1.clone()
+
+   #Set orientated lattice
+   ublist = [-0.06452276,  0.2478114,  -0.23742194, 0.29161678, -0.00914316, -0.12523779, 0.06958942, -0.1802702,  -0.14649001]
+   SetUB(Workspace=ws1,UB=ublist)
+
+   # Run Algorithm 
+   result = GoniometerAnglesFromPhiRotation(ws1,ws2,Tolerance=0.5,MIND=0,MAXD=2)
+
+   print "Chi: %.1f, Omega: %.1f, Indexed: %i, AvErrIndex: %.4f AvErrAll: %.4f" % (  result[0], result[1], result[2], result[3], result[4] )
+
+Output:
+
+.. testoutput:: exGoniometerAnglesFromPhiRotation
+
+   Chi: 90.0, Omega: 90.0, Indexed: 300, AvErrIndex: 0.2114 AvErrAll: 0.2114
+
 .. categories::

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

@@ -25,4 +25,31 @@ from an integer will have its (h,k,l) set to (0,0,0). The calculated
 Miller indices can either be rounded to the nearest integer value, or
 can be left as decimal fractions.
 
+Usage
+-----
+
+**Example - a simple example of IndexPeaks**
+
+.. include:: ../usagedata-note.txt
+
+.. testcode:: ExIndexPeaksSimple
+
+   # Load Peaks found in SXD23767.raw 
+   Load(Filename='SXD23767.peaks',OutputWorkspace='peaks_qLab')
+
+   #Set orientated lattice
+   ubMatrix = [-0.06452276,  0.2478114,  -0.23742194, 0.29161678, -0.00914316, -0.12523779, 0.06958942, -0.1802702,  -0.14649001]
+   SetUB('peaks_qLab',UB=ubMatrix)
+
+   # Run Algorithm 
+   indexed =IndexPeaks(PeaksWorkspace='peaks_qLab',Tolerance=0.12,RoundHKLs=1)
+
+   print "Number of Indexed Peaks: ", indexed[0]
+
+Output:
+
+.. testoutput:: ExIndexPeaksSimple
+
+   Number of Indexed Peaks:  147
+
 .. categories::

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

@@ -19,4 +19,30 @@ This tool is useful as many algorithms in Mantid only apply to
 Workspace2D. After conversion with MDHistoToWorkspace2D such algorithms
 can also be applied to MD data.
 
+Usage
+-----
+
+**Example - Flatten a small workspace:**
+
+.. testcode:: ExMDHistoToWorkspace2D
+
+   # Create input workspace
+   CreateMDWorkspace(Dimensions=3, Extents='-10,10,-10,10,-10,10', Names='A,B,C', Units='U,U,U', OutputWorkspace='demo')
+   FakeMDEventData(InputWorkspace='demo', PeakParams='32,0,0,0,1')
+   input = BinMD(InputWorkspace='demo', AlignedDim0='A,-2,2,4', AlignedDim1='B,-2,2,4', AlignedDim2='C,-2,2,4')
+
+   # Run the algorithm 
+   output = MDHistoToWorkspace2D(InputWorkspace='input')
+
+   # print 6th group of 4 bins in both input and output workspaces
+   print "part of MD workspace",input.getSignalArray()[1,1]
+   print "corresponding part of 2D workspace",output.dataY(5) 
+
+Output:
+
+.. testoutput:: ExMDHistoToWorkspace2D
+
+   part of MD workspace [ 0.  4.  5.  0.]
+   corresponding part of 2D workspace [ 0.  4.  5.  0.]
+
 .. categories::

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

@@ -17,4 +17,42 @@ The maximum of these offsets is also included.
 Histograms, scatterplots, etc. of this data can be used to detect
 problems.
 
+Usage
+-----
+
+**Example - Run LoadprofResolution for both TableWorkspace and workspace with MUSR Instrument**
+
+.. include:: ../usagedata-note.txt
+
+.. testcode:: ExShowHKLOffsetsSimple
+
+   #
+   # Load Peaks found in SXD23767.raw 
+   #
+   Load(Filename='SXD23767.peaks',OutputWorkspace='peaks_qLab')
+
+   #Set orientated lattice
+   ublist = [-0.06452276,  0.2478114,  -0.23742194, 0.29161678, -0.00914316, -0.12523779, 0.06958942, -0.1802702,  -0.14649001]
+   SetUB('peaks_qLab',UB=ublist)
+
+   # Run Algorithm 
+   table = ShowPeakHKLOffsets('peaks_qLab')
+
+   #Print part of first four rows
+   for i in [0,1,2,3]:
+      row = table.row(i)
+      #print row
+      print "{H offset from int: %.3f, K offset from int: %.3f, L offset from int: %.3f }" % ( row["H offset from int"],  row["K offset from int"], row["L offset from int"])
+
+
+Output:
+
+.. testoutput:: ExShowHKLOffsetsSimple
+
+   {H offset from int: -0.003, K offset from int: 0.012, L offset from int: 0.063 }
+   {H offset from int: -0.220, K offset from int: 0.431, L offset from int: -0.193 }
+   {H offset from int: -0.105, K offset from int: -0.066, L offset from int: -0.232 }
+   {H offset from int: 0.174, K offset from int: 0.095, L offset from int: 0.440 }
+
+
 .. categories::

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

@@ -12,7 +12,6 @@ Description
 This algorithm is for producing rocking curves from alignment scan runs.
 It is for use only with ADARA-style SNS datasets as it requires the
 'scan\_index' log variable.
-
 The algorithm optionally uses the :ref:`algm-MaskDetectors`
 and/or :ref:`algm-FilterByXValue` algorithms to restrict the
 region of data included. **N.B. If these options are used, then this
@@ -22,5 +21,17 @@ The :ref:`algm-SumEventsByLogValue` algorithm is then
 called, with 'scan\_index' as the log to sum against. The row of the
 resulting table pertaining to scan\_index=0 (which indicates 'not a scan
 point') is then removed.
+
+Before then it will call other algorithms as shown in the flowchart,
+if the relevent inputs have been set.
+:ref:`algm-MaskDetectors` will be called if a MaskWorkspace is supplied.
+If either Xmin or Xmax or both are supplied, 
+then :ref:`algm-FilterByXValue` algorithm is run to restrict the
+region of data included and if RangeUnit is not TOF,
+:ref:`algm-ConvertUnits` is run beforehand.  
+
+If necessary, the imput workspace is cloned, to save it from being modified.
+
+.. image:: ../images/StepScanWorkflow.png
 
 .. categories::

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

@@ -9,7 +9,71 @@
 Description
 -----------
 
-Threshold an MDHistoWorkspace to overwrite values below or above the
-defined threshold.
+This algorithm applies a simple linear transformation to a
+:ref:`MDWorkspace <MDWorkspace>` or
+:ref:`MDHistoWorkspace <MDHistoWorkspace>`. This could be used, for
+example, to scale the Energy dimension to different units.
+
+Each coordinate is tranformed so that :math:`x'_d = (x_d * s_d) + o_d`
+where:
+
+-  d : index of the dimension, from 0 to the number of dimensions
+-  s : value of the Scaling parameter
+-  o : value of the Offset parameter.
+
+You can specify either a single value for Scaling and Offset, in which
+case the same m\_scaling or m\_offset are applied to each dimension; or
+you can specify a list with one entry for each dimension.
+
+Notes
+#####
+
+The relationship between the workspace and the original
+:ref:`MDWorkspace <MDWorkspace>`, for example when the MDHistoWorkspace is
+the result of :ref:`algm-BinMD`, is lost. This means that you cannot
+re-bin a transformed :ref:`MDHistoWorkspace <MDHistoWorkspace>`.
+
+No units are not modified by this algorithm.
+
+Performance Notes
+#################
+
+-  Performing the operation in-place (input=output) is always faster
+   because the first step of the algorithm if NOT in-place is to clone
+   the original workspace.
+-  For :ref:`MDHistoWorkspaces <MDHistoWorkspace>` done in-place,
+   TransformMD is very quick (no data is modified, just the
+   coordinates).
+-  For :ref:`MDWorkspaces <MDWorkspace>`, every event's coordinates gets
+   modified, so this may take a while for large workspaces.
+-  For file-backed :ref:`MDWorkspaces <MDWorkspace>`, you will find much
+   better performance if you perform the change in-place (input=output),
+   because the data gets written out to disk twice otherwise.
+
+Usage
+-----
+
+**Example - Threshold a small workspace:**
+
+.. testcode:: ExThresholdMD
+
+   # Create input workspace
+   CreateMDWorkspace(Dimensions=3, Extents='-10,10,-10,10,-10,10', Names='A,B,C', Units='U,U,U', OutputWorkspace='demo')
+   FakeMDEventData(InputWorkspace='demo', PeakParams='32,0,0,0,1')
+   threshold_input = BinMD(InputWorkspace='demo', AlignedDim0='A,-2,2,4', AlignedDim1='B,-2,2,4', AlignedDim2='C,-2,2,4')
+
+   # Run the algorithm to set all values greater than 4 to zero
+   threshold_output = ThresholdMD(InputWorkspace='threshold_input', Condition='Greater Than', ReferenceValue=4)
+
+   # Print selection before and after
+   print "selected bins before threshold greater than 4",threshold_input.getSignalArray()[1,1]
+   print "same bins after threshold greater than 4",threshold_output.getSignalArray()[1,1]
+
+Output:
+
+.. testoutput:: ExThresholdMD
+
+   selected bins before threshold greater than 4 [ 0.  4.  5.  0.]
+   same bins after threshold greater than 4 [ 0.  4.  0.  0.]
 
 .. categories::

Code/Mantid/docs/source/diagrams/StepScanWorkflow.xml

@@ -0,0 +1 @@
+<mxfile userAgent="Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; InfoPath.3; .NET4.0C; .NET4.0E)" type="device"><diagram>3Zldb9o8FMc/DZcPAhzeLtf0ZZNWrVq1lV09shITrDoxcgyFffrayTGJ43RNm4BKuUDk2HGO//75+JzQQ368uxF4vbrlIWG90SDc9dBlbzSao5n61oZ9bvBm49wQCRrmpmFhuKd/CRgHYN3QkKRWR8k5k3RtGwOeJCSQlm3Jmf2INY7M8IXhPsDMtT7QUK5y62w0KexfCY1W5jHDyTxvSeXejBGSJd4w+V9mUm26OcZmrGxW6EoJJjhXw+hf8c4nTItmBMmnfv1C68FJQRJw5N83gBNbzDbg47dkvZHK9MDFY7rGAXFmkUrBHw8iKJcv0hVe68Z4F+mF7i8ZfwpWWMh+KtX3/0PVZ0kZ8znjIhsEXauP77vuwgy2REgCnGQmcP+G8JhIsVddoBUNABqAaAojPBWLNBwDMKvSAk1heTCwEh1GLuRSP0CxevWQo57PeNJOsbXgAUmVU1XFfF9r1oViwIRRTLHqSmb6WJKBrY1kQ9jzJc0cuUgSfhGCP6mrgOE0pYFWzNLQU5YXpUj5Rihuy4CT0NrdrjaCMCzp1t7sdROFW+84VU8tNJ29oKkZQu2DiEi4qyLXwY1GCpqVKSl4i9PHSyJVjOMiPTP6EDohfQd329LXBD2IDqdGD6GKUB2i5x4XGr1zOSrM0WCE8mrI82rIm3RBnntWNCNPTVfsF8o0MBd/9EV/PJ4awx0RVDlEtF66V1X1RnESuuWw2JHm5ASbBx+BYNi65SObJxqhXwmVHz922rmOZ2gtE2yy4zLBXgfJjnl2C4L7Y4vhZvw2C7YGGYtfuPUz8QvlRmkRfuIkIpreDx5953b09ZCncHDoHRwr/k7fRW8j9GBNPjt6buZ+TZnatRf7xe/MdvTg6cBWszaNg+fY0/HodOETxugm9axw9TqjcJ/FaLag3SNZSfDH1cS9OyRNplvS9H4TX22VEunF/juPzoHL0RRSQ9BrUpOWqlcYLpWHWNnqFUanFdGbsYSYUsYyX9SzxtItk35spHqtdsJCqV2oHNpITs3ZXQ6UqAbJeRdEtq+U3pVn1r8per3Kr0k8cwDOGmG3TlrENPng3M5hDY0+ZoQStlOIOGVqURevgt3qaBHj3ZkJZoB6RTBTdrYSzK1kGifkb96jGc3H34/VQqXD/diifHmzWhnKZxS91GXxj1nevfi/EV09Aw==</diagram></mxfile>