Add usage examples to directtools sphinx docs. Re #21901

docs/source/techniques/DirecttoolsPythonModule.rst

@@ -4,22 +4,130 @@
 :mod:`directtools`
 ==================
 
-:literal:`directtools` is a Python module for quickly plotting standardized :math:`S(Q,E)` color fill plots as well as line profiles (cuts) in constant :math:`Q` and :math:`E`. The module also provides a few utility functions for inspecting and manipulating the :math:`S(Q,E)` workspace.
+:mod:`directtools` is a Python module for quickly plotting standardized :math:`S(Q,E)` color fill plots as well as line profiles (cuts) in constant :math:`Q` and :math:`E`. The module also provides a few utility functions for inspecting and manipulating the :math:`S(Q,E)` workspace.
 
 For a general introduction on using :mod:`matplotlib` with Mantid, see :ref:`this introduction <plotting>`
 
+The input workspaces are expected to have some specific sample logs, namely ``instrument.name``, ``Ei``, ``run_number``, ``start_time``, ``sample.temperature``.
+
+Examples
+########
+
+The default parameters for :func:`directtools.plotSofQW` give a view of the :math:`S(Q,E)` workspace around the elastic peak with sensible limits for the axes and intensity:
+
 .. plot::
    :include-source:
 
    import directtools as dt
    from mantid.simpleapi import *
 
-   DirectILLCollectData(Run='ILL/IN4/084447', OutputWorkspace='data')
+   DirectILLCollectData(Run='ILL/IN4/084447.nxs', OutputWorkspace='data')
    DirectILLReduction(InputWorkspace='data', OutputWorkspace='SofQW')
 
    fig, ax = dt.plotSofQW('SofQW')
    #fig.show()
 
+The :math:`Q`, :math:`E` and intensity limits can be changed using the optional parameters. The utility functions :func:`directtools.validQ` and :func:`directtools.nanminmax` might be helpful when determining suitable ranges:
+
+.. plot::
+   :include-source:
+
+   import directtools as dt
+   from mantid.simpleapi import *
+
+   DirectILLCollectData(Run='ILL/IN4/084447.nxs', OutputWorkspace='data')
+   DirectILLReduction(InputWorkspace='data', OutputWorkspace='SofQW')
+
+   EMin = -20.
+   QMax = dt.validQ('SofQW', EMin)[1]
+   VMax = 0.5 * dt.nanminmax('SofQW')[1]
+
+   fig, axes = dt.plotSofQW('SofQW', QMax=QMax, EMin=EMin, VMax=VMax)
+   #fig.show()
+
+An important aspect of examining the :math:`S(Q,E)` workspace is to plot cuts at constant :math:`Q` and :math:`E`. This can be done by :func:`directtools.plotconstQ` and :func:`directtools.plotconstE`:
+
+.. plot::
+   :include-source:
+
+   import directtools as dt
+   from mantid.simpleapi import *
+   
+   DirectILLCollectData(Run='ILL/IN4/084447.nxs', OutputWorkspace='data')
+   DirectILLReduction(InputWorkspace='data', OutputWorkspace='SofQW')
+   
+   Q = 2.
+   dQ = 0.2
+   fig, axes, cuts = dt.plotconstQ('SofQW', Q, dQ)
+   #fig.show()
+
+Any of the workspace, cut centre or cut width arguments can be a :class:`list` instead. This enables data comparison:
+
+.. plot::
+   :include-source:
+
+   import directtools as dt
+   from mantid.simpleapi import *
+   
+   DirectILLCollectData(Run='ILL/IN4/084447.nxs', OutputWorkspace='data')
+   DirectILLReduction(InputWorkspace='data', OutputWorkspace='SofQW')
+   
+   Q1 = 2.
+   Q2 = 3.
+   dQ = 0.2
+   fig, axes, cuts = dt.plotconstQ('SofQW', [Q1, Q2], dQ)
+   #fig.show()
+
+The :func:`directtools.plotconstQ` and :func:`directtools.plotconstE` functions use :func:`directtool.plotcuts` to do the actual line profiles and plotting. The profiles are made by the :ref:`algm-LineProfile` algorithm, and all three plotting functions return a list of the produced line profile workspace names.
+
+If a line profile already exists, it can be plotted using :func:`directtools.plotprofiles`. This also accepts either a single line profile workspace or a list of workspaces enabling comparison:
+
+.. plot::
+   :include-source:
+
+   import directtools as dt
+   from mantid.simpleapi import *
+   
+   DirectILLCollectData(Run='ILL/IN4/084447.nxs', OutputWorkspace='data')
+   DirectILLReduction(InputWorkspace='data', OutputWorkspace='SofQW')
+   
+   E1 = 8.
+   dE = 2.
+   cut1 = LineProfile('SofQW', E1, dE, 'Horizontal')
+   label1 = 'At E = {} meV'.format(E1)
+   E2 = E1 - 4.
+   cut2 = LineProfile('SofQW', E2, dE, 'Horizontal')
+   label2 = 'At E = {} meV'.format(E2)
+   fig, axes = dt.plotprofiles([cut1, cut2], [label1, label2], style='m')
+   axes.legend()
+   #fig.show()
+
+:class:`directtools.SampleLogs` is a convenience class to import the sample logs of a workspace into a 'struct' like object in Python:
+
+.. testcode:: SampleLogsEx
+
+   import directtools as dt
+   from mantid.simpleapi import *
+   
+   DirectILLCollectData(Run='ILL/IN4/084447.nxs', OutputWorkspace='data')
+   DirectILLReduction(InputWorkspace='data', OutputWorkspace='SofQW')
+   
+   # Works on any workspace, not just S(Q,E).
+   logs = dt.SampleLogs('SofQW')
+   print(logs.instrument.name)
+   print(logs.run_number)
+
+.. testcleanup:: SampleLogsEx
+
+   mtd.clear()
+
+Output:
+
+.. testoutput:: SampleLogsEx
+
+   IN4
+   84447
+
 Reference
 =========