\(\renewcommand\AA{\unicode{x212B}}\)

`directtools`¶

directtools is a Python module for quickly plotting standardized \(S(Q,E)\) color fill plots as well as line profiles (cuts) in constant \(Q\) and \(E\). The module also provides a few utility functions for inspecting and manipulating the \(S(Q,E)\) workspace.

For a general introduction on using matplotlib with Mantid, see this introduction

The input workspaces are expected to have some specific sample logs, namely instrument.name, Ei, run_number, start_time, sample.temperature.

Examples¶

Examples of some key functionality of directtools is presented below. For a full reference of all available function and classes, see the Reference section below.

plotSofQW¶

The default parameters for directtools.plotSofQW() give a view of the \(S(Q,E)\) workspace around the elastic peak with sensible limits for the axes and intensity:

Enable :plots: using DOCS_PLOTDIRECTIVE in CMake

The \(Q\), \(E\) and intensity limits can be changed using the optional parameters. The utility functions directtools.validQ() and directtools.nanminmax() might be helpful when determining suitable ranges:

Enable :plots: using DOCS_PLOTDIRECTIVE in CMake

Cuts in \(S(Q,E)\)¶

An important aspect of examining the \(S(Q,E)\) workspace is to plot cuts at constant \(Q\) and \(E\). This can be done by directtools.plotconstQ() and directtools.plotconstE():

Enable :plots: using DOCS_PLOTDIRECTIVE in CMake

Any of the workspace, cut centre or cut width arguments can be a list instead. This enables data comparison:

Enable :plots: using DOCS_PLOTDIRECTIVE in CMake

The directtools.plotconstQ() and directtools.plotconstE() functions use directtools.plotcuts() to do the actual line profiles and plotting. The profiles are made by the LineProfile v1 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 directtools.plotprofiles(). This also accepts either a single line profile workspace or a list of workspaces enabling comparison:

Enable :plots: using DOCS_PLOTDIRECTIVE in CMake

Plotting density of states¶

The density of states data calculated by ComputeIncoherentDOS can be plotted by the directtools.plotDOS() function. The function accepts a single workspace or a list of workspaces as its arguments. The example below shows a comparison of densities of states calculated from \(S(Q,E)\) and \(S(2\theta,E)\):

Enable :plots: using DOCS_PLOTDIRECTIVE in CMake

Convenience tools¶

directtools.SampleLogs is a convenience class to import the sample logs of a workspace into a ‘struct’ like object in Python:

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)

Output:

IN4
84447

Reference¶

Classes¶

class directtools.SampleLogs(workspace)¶

A convenience class to access the sample logs of 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':

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

__init__(workspace)¶

Initialize a SampleLogs object. Transform sample log entries from workspace into attributes of this object.

Parameters:: workspace (mantid.api.MatrixWorkspace) – the workspace from which to extract the sample logs

Functions¶

directtools.box2D(xs, vertAxis, horMin=-inf, horMax=inf, vertMin=-inf, vertMax=inf)¶

Return slicing for a 2D numpy array limited by given min and max values.

Parameters:

xs (a 2D numpy.ndarray) – the 2D X data of a workspace from mantid.api.MatrixWorkspace.extractX()
vertAxis (a 1D numpy.ndarray) – the vertical axis values of a workspace
horMin (float) – the left edge of the box
horMax (float) – the right edge of the box
vertMin (float) – the bottom edge of the box
vertMax (float) – the top edge of the box

Returns:

a tuple of two slice objects, the first one for vertical dimension, the second for horizontal.

directtools.defaultrcparams()¶

Return a dictionary of directtools default matplotlib rc parameters.

Returns:: a dict of default matplotlib rc parameters needed by directtools

directtools.dynamicsusceptibility(workspace, temperature, outputName=None, zeroEnergyEpsilon=1e-06)¶

Convert \(S(Q,E)\) to susceptibility \(\chi''(Q,E)\).

If the X units are not in DeltaE, the workspace is transposed
The Y data in workspace is multiplied by \(1 - e^{\Delta E / (kT)}\)
Y data in the bin closest to 0 meV and within -zeroEnergyEpsilon < \(\Delta E\) < zeroEnergyEpsilon is set to 0
If the input was transposed, transpose the output as well

Parameters:

workspace (mantid.api.MatrixWorkspace) – a \(S(Q,E)\) workspace to convert
temperature (float) – temperature in Kelvin
outputName (str or None) – name of the output workspace. If None, the output will be given some generated name.
zeroEnergyEpsilon (float) – if a bin center is within this value from 0, the bin’s value is set to zero.

Returns:

a mantid.api.MatrixWorkspace containing \(\chi''(Q,E)\)

directtools.nanminmax(workspace, horMin=-inf, horMax=inf, vertMin=-inf, vertMax=inf)¶

Return min and max intensities of a workspace ignoring NaNs.

The search region can be limited by horMin, horMax, vertMin and vertMax.

Parameters:

workspace (mantid.api.MatrixWorkspace) – a workspace
horMin (float) – the left edge of the search region
horMax (float) – the right edge of the search region
vertMin (float) – the bottom edge of the search region
vertMax (float) – the top edge of the search region

Returns:

a tuple containing the minimum and maximum

directtools.plotDOS(workspaces, labels=None, style='l', xscale='linear', yscale='linear')¶

Plot density of state workspaces.

Plots the given DOS workspaces.

Parameters:

workspaces (str, mantid.api.MatrixWorkspace or a list thereof) – a single workspace or a list thereof
labels (str, a list of strings or None) – a list of labels for the plot legend
style (str) – plot style: ‘l’ for lines, ‘m’ for markers, ‘lm’ for both
xscale (str) – horizontal axis scaling: ‘linear’, ‘log’, ‘symlog’, ‘logit’
yscale (str) – vertical axis scaling: ‘linear’, ‘log’, ‘symlog’, ‘logit’

Returns:

a tuple of (matplotlib.Figure, matplotlib.Axes)

directtools.plotSofQW(workspace, QMin=0.0, QMax=None, EMin=None, EMax=None, VMin=0.0, VMax=None, colormap='jet', colorscale='linear')¶

Plot a 2D \(S(Q,E)\) workspace.

Parameters:

workspace (str or mantid.api.MatrixWorkspace) – a workspace to plot
QMin (float or None) – minimum \(Q\) to include in the plot
QMax (float or None) – maximum \(Q\) to include in the plot
EMin (float or None) – minimum energy transfer to include in the plot
EMax (float or None) – maximum energy transfer to include in the plot
VMin (float or None) – minimum intensity to show on the color bar
VMax (float or None) – maximum intensity to show on the color bar
colormap (str) – name of the colormap
colorscale (str) – color map scaling: ‘linear’, ‘log’

Returns:

a tuple of (matplotlib.Figure, matplotlib.Axes)

directtools.plotconstE(workspaces, E, dE, style='l', keepCutWorkspaces=True, xscale='linear', yscale='linear')¶

Plot line profiles at constant energy transfer from \(S(Q,E)\) workspace.

Creates cut workspaces using LineProfile v1, 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.

Parameters:

workspaces (str, mantid.api.MatrixWorkspace or a list thereof) – a single \(S(Q,E)\) workspace or list of workspaces to cut
E (float or list of floats) – a constant energy transfer or a list thereof
dE (float or list of floats) – width of the cut or a list of widths
style (str) – plot style: ‘l’ for lines, ‘m’ for markers, ‘lm’ for both
keepCutWorkspaces (bool) – whether or not keep the cut workspaces in the ADS
xscale (str) – horizontal axis scaling: ‘linear’, ‘log’, ‘symlog’, ‘logit’
yscale (str) – vertical axis scaling: ‘linear’, ‘log’, ‘symlog’, ‘logit’

Returns:

A tuple of (matplotlib.Figure, matplotlib.Axes, a list of names)

directtools.plotconstQ(workspaces, Q, dQ, style='l', keepCutWorkspaces=True, xscale='linear', yscale='linear')¶

Plot line profiles at constant momentum transfer from \(S(Q,E)\) workspace.

Creates cut workspaces using LineProfile v1, 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.

Parameters:

workspaces (str, mantid.api.MatrixWorkspace or a list thereof) – a single \(S(Q,E)\) workspace or list of workspaces to cut
Q (float or list of floats) – a constant momentum transfer or a list thereof
dQ (float or list of floats) – width of the cut or a list of widths
style (str) – plot style: ‘l’ for lines, ‘m’ for markers, ‘lm’ for both
keepCutWorkspaces (bool) – whether or not keep the cut workspaces in the ADS
xscale (str) – horizontal axis scaling: ‘linear’, ‘log’, ‘symlog’, ‘logit’
yscale (str) – vertical axis scaling: ‘linear’, ‘log’, ‘symlog’, ‘logit’

Returns:

A tuple of (matplotlib.Figure, matplotlib.Axes, a list of names)

directtools.plotcuts(direction, workspaces, cuts, widths, quantity, unit, style='l', keepCutWorkspaces=True, xscale='linear', yscale='linear')¶

Cut and plot multiple line profiles.

Creates cut workspaces using LineProfile v1, 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.

Parameters:

direction (str) – Cut direction. Only 'Horizontal' and 'Vertical' are accepted
workspaces (str, mantid.api.MatrixWorkspace or a list thereof) – a single workspace or a list thereof
cuts (float or a list thereof) – the center of the cut or a list of centers
widths (float or a list thereof) – the width of the cut or a list of widths
quantity (str) – name of the physical quantity along which the cut is made, used for legend label
unit (str) – unit of quantity
style (str) – plot style: ‘l’ for lines, ‘m’ for markers, ‘lm’ for both
keepCutWorkspaces (bool) – whether or not keep the cut workspaces in the ADS
xscale (str) – horizontal axis scaling: ‘linear’, ‘log’, ‘symlog’, ‘logit’
yscale (str) – vertical axis scaling: ‘linear’, ‘log’, ‘symlog’, ‘logit’

Returns:

A tuple of (matplotlib.Figure, matplotlib.Axes, a list of names)

directtools.plotprofiles(workspaces, labels=None, style='l', xscale='linear', yscale='linear')¶

Plot line profile workspaces.

Plots the given single histogram cut workspaces.

Parameters:

workspaces (str, mantid.api.MatrixWorkspace or a list thereof) – a single workspace or a list thereof
labels (str, a list of strings or None) – a list of cut labels for the plot legend
style (str) – plot style: ‘l’ for lines, ‘m’ for markers, ‘lm’ for both
xscale (str) – horizontal axis scaling: ‘linear’, ‘log’, ‘symlog’, ‘logit’
yscale (str) – vertical axis scaling: ‘linear’, ‘log’, ‘symlog’, ‘logit’

Returns:

a tuple of (matplotlib.Figure, matplotlib.Axes)

directtools.subplots(**kwargs)¶

Return matplotlib figure and axes with Mantid projection.

The returned figure and axes have the proper projection to plot Mantid workspaces directly.

Parameters:: kwargs (dict) – keyword arguments that are directly passed to matplotlib.pyplot.subplots().
Returns:: a tuple of (matplotlib.Figure, matplotlib.Axes)

directtools.validQ(workspace, E=0.0)¶

Return a \(Q\) range at given energy transfer where \(S(Q,E)\) is defined.

\(S(Q,E)\) is undefined when Y = NaN

Parameters:

workspace (str or mantid.api.MatrixWorkspace) – A \(S(Q,E)\) workspace to investigate
E (float) – energy transfer at which to evaluate the range

Returns:

a tuple of (\(Q_{min}\), \(Q_{max}\))

directtools.wsreport(workspace)¶

Print some useful information from sample logs.

The logs are expected to contain some ILL specific fields.

Parameters:: workspace (str or mantid.api.MatrixWorkspace) – a workspace from which to extract the logs
Returns:: None

Category: Techniques

directtools¶

Examples¶

plotSofQW¶

Cuts in \(S(Q,E)\)¶

Plotting density of states¶

Convenience tools¶

Reference¶

Classes¶

Functions¶

`directtools`¶