diff --git a/docs/source/techniques/Directtools Python module.rst b/docs/source/techniques/Directtools Python module.rst
deleted file mode 100644
index 6dcf5a66b8847f623cdb8cb439d3409d5daa4c26..0000000000000000000000000000000000000000
--- a/docs/source/techniques/Directtools Python module.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-.. _Directtools Python module:
-
-==================
-: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.
-
-Reference
-=========
-
-.. autoclass:: directtools.SampleLogs
- :members: __init__
-
-.. automodule:: directtools
- :members: dynamicsusceptibility, nanminmax, plotcuts, plotprofiles, plotconstE,
- plotconstQ, plotSofQW, subplots, validQ, wsreport
-
-.. categories:: Techniques
diff --git a/docs/source/techniques/DirecttoolsPythonModule.rst b/docs/source/techniques/DirecttoolsPythonModule.rst
new file mode 100644
index 0000000000000000000000000000000000000000..0f78bf1aea744bae77fbdfd061040d169c13d7ec
--- /dev/null
+++ b/docs/source/techniques/DirecttoolsPythonModule.rst
@@ -0,0 +1,147 @@
+.. _Directtools Python module:
+
+==================
+:mod:`directtools`
+==================
+
+: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.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:`directtools.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
+=========
+
+Classes
+#######
+
+.. autoclass:: directtools.SampleLogs
+ :members: __init__
+
+Functions
+#########
+
+.. automodule:: directtools
+ :members: box2D, defaultrcParams, dynamicsusceptibility, nanminmax, plotconstE,
+ plotconstQ, plotcuts, plotprofiles, plotSofQW, subplots, validQ, wsreport
+
+.. categories:: Techniques
diff --git a/scripts/directtools/__init__.py b/scripts/directtools/__init__.py
index 6aea8a736947533a55793b7dccd3310b84b34e1d..bc91cfe55510da98e534397566ee564ac17794e9 100644
--- a/scripts/directtools/__init__.py
+++ b/scripts/directtools/__init__.py
@@ -33,6 +33,11 @@ def _clearlatex(s):
return s
+def _configurematplotlib(params):
+ """Set matplotlib rc parameters from the params dictionary."""
+ matplotlib.rcParams.update(params)
+
+
def _finalizeprofileE(axes):
"""Set axes for const E axes."""
axes.set_xlim(xmin=0.)
@@ -111,6 +116,11 @@ def _binCentres(edges):
return (edges[:-1] + edges[1:]) / 2
+def _mantidsubplotsetup():
+ """Return the Mantid projection setup."""
+ return {'projection': 'mantid'}
+
+
def _profiletitle(workspaces, scan, units, cuts, widths, figure):
"""Add title to line profile figure."""
workspaces = _normwslist(workspaces)
@@ -180,7 +190,22 @@ def _SofQWtitle(workspace, figure):
def box2D(xs, vertAxis, horMin=-numpy.inf, horMax=numpy.inf, vertMin=-numpy.inf, vertMax=numpy.inf):
- """Return slicing for a 2D numpy array limited by given min and max values."""
+ """Return slicing for a 2D numpy array limited by given min and max values.
+
+ :param xs: the 2D X data of a workspace from :func:`mantid.api.MatrixWorkspace.extractX`
+ :type xs: a 2D :class:`numpy.ndarray`
+ :param vertAxis: the vertical axis values of a workspace
+ :type vertAxis: a 1D :class:`numpy.ndarray`
+ :param horMin: the left edge of the box
+ :type horMin: float
+ :param horMax: the right edge of the box
+ :type horMax: float
+ :param vertMin: the bottom edge of the box
+ :type vertMin: float
+ :param vertMax: the top edge of the box
+ :type vertMax: float
+ :returns: a tuple of two :class:`slice` objects, the first one for vertical dimension, the second for horizontal.
+ """
if len(vertAxis) > xs.shape[0]:
vertAxis = _binCentres(vertAxis)
horBegin = numpy.argwhere(xs[0, :] >= horMin)[0][0]
@@ -190,13 +215,11 @@ def box2D(xs, vertAxis, horMin=-numpy.inf, horMax=numpy.inf, vertMin=-numpy.inf,
return slice(vertBegin, vertEnd), slice(horBegin, horEnd)
-def configurematplotlib(params):
- """Set matplotlib rc parameters from the params dictionary."""
- matplotlib.rcParams.update(params)
-
-
def defaultrcParams():
- """Return a dictionary of directtools default matplotlib rc parameters."""
+ """Return a dictionary of directtools default matplotlib rc parameters.
+
+ :returns: a :class:`dict` of default :mod:`matplotlib` rc parameters needed by :mod:`directtools`
+ """
params = {
'legend.numpoints': 1,
'text.usetex': True,
@@ -205,7 +228,23 @@ def defaultrcParams():
def dynamicsusceptibility(workspace, temperature, outputName=None, zeroEnergyEpsilon=1e-6):
- """Convert :math:`S(Q,E)` to susceptibility :math:`\chi''(Q,E)`."""
+ """Convert :math:`S(Q,E)` to susceptibility :math:`\chi''(Q,E)`.
+
+ #. If the X units are not in DeltaE, the workspace is transposed
+ #. The Y data in *workspace* is multiplied by :math:`1 - e^{\Delta E / (kT)}`
+ #. Y data in the bin closest to 0 meV and within -*zeroEnergyEpsilon* < :math:`\Delta E` < *zeroEnergyEpsilon* is set to 0
+ #. If the input was transposed, transpose the output as well
+
+ :param workspace: a :math:`S(Q,E)` workspace to convert
+ :type workspace: :class:`mantid.api.MatrixWorkspace`
+ :param temperature: temperature in Kelvin
+ :type temperature: float
+ :param outputName: name of the output workspace. If :class:`None`, the output will be given some generated name.
+ :type outputName: str or None
+ :param zeroEnergyEpsilon: if a bin center is within this value from 0, the bin's value is set to zero.
+ :type zeroEnergyEpsilon: float
+ :returns: a :class:`mantid.api.MatrixWorkspace` containing :math:`\chi''(Q,E)`
+ """
workspace = _normws(workspace)
horAxis = workspace.getAxis(0)
horUnit = horAxis.getUnit().unitID()
@@ -224,13 +263,24 @@ def dynamicsusceptibility(workspace, temperature, outputName=None, zeroEnergyEps
return outWS
-def mantidsubplotsetup():
- """Return a dict for the matplotlib.pyplot.subplots()."""
- return {'projection': 'mantid'}
-
-
def nanminmax(workspace, horMin=-numpy.inf, horMax=numpy.inf, vertMin=-numpy.inf, vertMax=numpy.inf):
- """Return min and max intensities of a workspace."""
+ """Return min and max intensities of a workspace ignoring NaNs.
+
+ The search region can be limited by *horMin*, *horMax*, *vertMin* and *vertMax*.
+
+ :param workspace: a workspace
+ :type workspace: :class:`mantid.api.MatrixWorkspace`
+ :param horMin: the left edge of the search region
+ :type horMin: float
+ :param horMax: the right edge of the search region
+ :type horMax: float
+ :param vertMin: the bottom edge of the search region
+ :type vertMin: float
+ :param vertMax: the top edge of the search region
+ :type vertMax: float
+
+ :returns: a tuple containing the minimum and maximum
+ """
workspace = _normws(workspace)
xs = workspace.extractX()
ys = workspace.extractY()
@@ -245,7 +295,26 @@ def nanminmax(workspace, horMin=-numpy.inf, horMax=numpy.inf, vertMin=-numpy.inf
def plotconstE(workspaces, E, dE, style='l', keepCutWorkspaces=True):
- """Plot line profiles at constant energy."""
+ """Plot line profiles at constant energy transfer from :math:`S(Q,E)` workspace.
+
+ Creates cut workspaces using :ref:`algm-LineProfile`, then plots the cuts. A list of workspaces,
+ constant energy transfers, or cut widths, or any combination thereof can be given as parameters.
+
+ The last entry in the returned tuple is a list of cut workspace names. This will be an empty list
+ is *keeCutWorkspaces* is set to `False` as the workspaces will not appear in the ADS.
+
+ :param workspaces: a single :math:`S(Q,E)` workspace or list of workspaces to cut
+ :type workspaces: str, :class:`mantid.api.MatrixWorkspace` or a list thereof
+ :param E: a constant energy transfer or a :class:`list` thereof
+ :type E: float or :class:`list` of floats
+ :param dE: width of the cut or a list of widths
+ :type dE: float or :class:`list` of floats
+ :param style: plot style: 'l' for lines, 'm' for markers, 'lm' for both
+ :type style: str
+ :param keepCutWorkspaces: whether or not keep the cut workspaces in the ADS
+ :type keepCutWorkspaces: bool
+ :returns: A tuple of (:class:`matplotlib.Figure`, :class:`matplotlib.Axes`, a :class:`list` of names)
+ """
figure, axes, cutWSList = plotcuts('Horizontal', workspaces, E, dE, '$E$', 'meV', style, keepCutWorkspaces)
_profiletitle(workspaces, '$E$', 'meV', E, dE, figure)
axes.legend()
@@ -258,7 +327,26 @@ def plotconstE(workspaces, E, dE, style='l', keepCutWorkspaces=True):
def plotconstQ(workspaces, Q, dQ, style='l', keepCutWorkspaces=True):
- """Plot line profiles at constant momentum transfer."""
+ """Plot line profiles at constant momentum transfer from :math:`S(Q,E)` workspace.
+
+ Creates cut workspaces using :ref:`algm-LineProfile`, then plots the cuts. A list of workspaces,
+ constant momentum transfers, or cut widths, or any combination thereof can be given as parameters.
+
+ The last entry in the returned tuple is a list of cut workspace names. This will be an empty list
+ is *keeCutWorkspaces* is set to `False` as the workspaces will not appear in the ADS.
+
+ :param workspaces: a single :math:`S(Q,E)` workspace or list of workspaces to cut
+ :type workspaces: str, :class:`mantid.api.MatrixWorkspace` or a list thereof
+ :param Q: a constant momentum transfer or a :class:`list` thereof
+ :type Q: float or :class:`list` of floats
+ :param dQ: width of the cut or a list of widths
+ :type dQ: float or :class:`list` of floats
+ :param style: plot style: 'l' for lines, 'm' for markers, 'lm' for both
+ :type style: str
+ :param keepCutWorkspaces: whether or not keep the cut workspaces in the ADS
+ :type keepCutWorkspaces: bool
+ :returns: A tuple of (:class:`matplotlib.Figure`, :class:`matplotlib.Axes`, a :class:`list` of names)
+ """
figure, axes, cutWSList = plotcuts('Vertical', workspaces, Q, dQ, '$Q$', '\\AA$^{-1}$', style, keepCutWorkspaces)
_profiletitle(workspaces, '$Q$', '\\AA$^{-1}$', Q, dQ, figure)
axes.legend()
@@ -272,7 +360,32 @@ def plotconstQ(workspaces, Q, dQ, style='l', keepCutWorkspaces=True):
def plotcuts(direction, workspaces, cuts, widths, quantity, unit, style='l', keepCutWorkspaces=True):
- """Cut and plot multiple line profiles."""
+ """Cut and plot multiple line profiles.
+
+ Creates cut workspaces using :ref:`algm-LineProfile`, then plots the cuts. A list of workspaces,
+ cut centres, or cut widths, or any combination thereof can be given as parameters.
+
+ The last entry in the returned tuple is a list of cut workspace names. This will be an empty list
+ is *keeCutWorkspaces* is set to `False` as the workspaces will not appear in the ADS.
+
+ :param direction: Cut direction. Only ``'Horizontal'`` and ``'Vertical'`` are accepted
+ :type direction: str
+ :param workspaces: a single workspace or a list thereof
+ :type workspaces: str, :class:`mantid.api.MatrixWorkspace` or a :class:`list` thereof
+ :param cuts: the center of the cut or a list of centers
+ :type cuts: float or a :class:`list` thereof
+ :param widths: the width of the cut or a list of widths
+ :type widths: float or a :class:`list` thereof
+ :param quantity: name of the physical quantity along which the cut is made, used for legend label
+ :type quantity: str
+ :param unit: unit of *quantity*
+ :type unit: str
+ :param style: plot style: 'l' for lines, 'm' for markers, 'lm' for both
+ :type style: str
+ :param keepCutWorkspaces: whether or not keep the cut workspaces in the ADS
+ :type keepCutWorkspaces: bool
+ :returns: A tuple of (:class:`matplotlib.Figure`, :class:`matplotlib.Axes`, a :class:`list` of names)
+ """
workspaces = _normwslist(workspaces)
if not isinstance(cuts, collections.Iterable):
cuts = [cuts]
@@ -308,7 +421,18 @@ def plotcuts(direction, workspaces, cuts, widths, quantity, unit, style='l', kee
def plotprofiles(workspaces, labels=None, style='l'):
- """Plot given line profile workspaces."""
+ """Plot line profile workspaces.
+
+ Plots the first histograms from given workspaces.
+
+ :param workspaces: a single workspace or a list thereof
+ :type workspaces: str, :class:`mantid.api.MatrixWorkspace` or a :class:`list` thereof
+ :param labels: a list of cut labels for the plot legend
+ :type labels: str, a :class:`list` of strings or None
+ :param style: plot style: 'l' for lines, 'm' for markers, 'lm' for both
+ :type style: str
+ :returns: a tuple of (:mod:`matplotlib.Figure`, :mod:`matplotlib.Axes`)
+ """
workspaces = _normwslist(workspaces)
if not isinstance(labels, collections.Iterable) or isinstance(labels, str):
if labels is None:
@@ -336,7 +460,26 @@ def plotprofiles(workspaces, labels=None, style='l'):
def plotSofQW(workspace, QMin=0., QMax=None, EMin=None, EMax=None, VMin=0., VMax=None, colormap='jet'):
- """Plot a 2D plot with given axis limits and return the plotting layer."""
+ """Plot a 2D :math:`S(Q,E)` workspace.
+
+ :param workspace: a workspace to plot
+ :type workspace: str or :class:`mantid.api.MatrixWorkspace`
+ :param QMin: minimum :math:`Q` to include in the plot
+ :type QMin: float or None
+ :param QMax: maximum :math:`Q` to include in the plot
+ :type QMax: float or None
+ :param EMin: minimum energy transfer to include in the plot
+ :type EMin: float or None
+ :param EMax: maximum energy transfer to include in the plot
+ :type EMax: float or None
+ :param VMin: minimum intensity to show on the color bar
+ :type VMin: float or None
+ :param VMax: maximum intensity to show on the color bar
+ :type VMax: float or None
+ :param colormap: name of the colormap
+ :type colormap: str
+ :returns: a tuple of (:mod:`matplotlib.Figure`, :mod:`matplotlib.Axes`)
+ """
# Accept both workspace names and actual workspaces.
workspace = _normws(workspace)
isSusceptibility = workspace.YUnit() == 'Dynamic susceptibility'
@@ -378,12 +521,28 @@ def plotSofQW(workspace, QMin=0., QMax=None, EMin=None, EMax=None, VMin=0., VMax
def subplots(**kwargs):
- """Return matplotlib figure and axes."""
- return pyplot.subplots(subplot_kw=mantidsubplotsetup(), **kwargs)
+ """Return matplotlib figure and axes with Mantid projection.
+
+ The returned figure and axes have the proper projection to plot Mantid workspaces directly.
+
+ :param kwargs: keyword arguments that are directly passed to :func:`matplotlib.pyplot.subplots`.
+ :type kwargs: dict
+ :returns: a tuple of (:class:`matplotlib.Figure`, :class:`matplotlib.Axes`)
+ """
+ return pyplot.subplots(subplot_kw=_mantidsubplotsetup(), **kwargs)
def validQ(workspace, E=0.0):
- """Return a :math:`Q` range at given energy transfer where :math:`S(Q,E)` is defined."""
+ """Return a :math:`Q` range at given energy transfer where :math:`S(Q,E)` is defined.
+
+ :math:`S(Q,E)` is undefined when Y = NaN
+
+ :param workspace: A :math:`S(Q,E)` workspace to investigate
+ :type workspace: str or :class:`mantid.api.MatrixWorkspace`
+ :param E: energy transfer at which to evaluate the range
+ :type E: float
+ :returns: a tuple of (:math:`Q_{min}`, :math:`Q_{max}`)
+ """
workspace = _normws(workspace)
vertBins = workspace.getAxis(1).extractValues()
if len(vertBins) > workspace.getNumberHistograms():
@@ -401,7 +560,14 @@ def validQ(workspace, E=0.0):
def wsreport(workspace):
- """Print some useful information from sample logs."""
+ """Print some useful information from sample logs.
+
+ The logs are expected to contain some ILL specific fields.
+
+ :param workspace: a workspace from which to extract the logs
+ :type workspace: str or :class:`mantid.api.MatrixWorkspace`
+ :returns: None
+ """
workspace = _normws(workspace)
print(str(workspace))
logs = SampleLogs(workspace)
@@ -420,8 +586,27 @@ def wsreport(workspace):
class SampleLogs:
+ """A convenience class to access the sample logs of :class:`mantid.api.MatrixWorkspace`.
+
+ Upon initialization, this class adds the sample logs as data attributes to itself. The
+ attributes get their names from the logs. Log names containing dots result in nested
+ log objects. Thus, if a workspace contains logs ``'a'`` and ``'b.c'``:
+
+ .. code::
+
+ logs = SampleLogs(workspace)
+ # This is equivalent of calling workspace.run().getProperty('a').value
+ logs.a
+ # This is equivalent of calling workspace.run().getProperty('b.c').value
+ logs.b.c
+ """
def __init__(self, workspace):
- """Transform sample log entries from workspace into attributes of this object."""
+ """Initialize a `SampleLogs` object.
+ Transform sample log entries from workspace into attributes of this object.
+
+ :param workspace: the workspace from which to extract the sample logs
+ :type workspace: :class:`mantid.api.MatrixWorkspace`
+ """
class Log:
pass
workspace = _normws(workspace)
@@ -442,4 +627,4 @@ class SampleLogs:
# Set default matplotlib rc parameters.
-configurematplotlib(defaultrcParams())
+_configurematplotlib(defaultrcParams())
diff --git a/scripts/test/directtools/DirectToolsTest.py b/scripts/test/directtools/DirectToolsTest.py
index 82b22d58bd8813f4e2ab5c4f6f68ceb6ad932c7b..a1877a98dcc3f476ce0b0ccd153783290a6c093d 100644
--- a/scripts/test/directtools/DirectToolsTest.py
+++ b/scripts/test/directtools/DirectToolsTest.py
@@ -56,7 +56,7 @@ class DirectTest(unittest.TestCase):
def test_configurematplotlib(self):
defaultParams = directtools.defaultrcParams()
- directtools.configurematplotlib(defaultParams)
+ directtools._configurematplotlib(defaultParams)
for key in defaultParams:
self.assertTrue(key in matplotlib.rcParams)
self.assertEqual(matplotlib.rcParams[key], defaultParams[key])
@@ -98,7 +98,7 @@ class DirectTest(unittest.TestCase):
self.assertEqual(outEs[2], 0.)
def test_mantidsubplotsetup(self):
- result = directtools.mantidsubplotsetup()
+ result = directtools._mantidsubplotsetup()
self.assertEqual(result, {'projection': 'mantid'})
def _nanminmaxSetup(self):