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

MD Histogram Workspace

The MD Histogram Workspace[MDHistoWorkspace] is a simple multi-dimensional workspace. In contrast to the MDWorkspace, which contains points in space, the MDHistoWorkspace consists of a signal and error spread around space on a regular grid.

In a way, the MDHistoWorkspace is to a MDWorkspace is what the Workspace2D is to the EventWorkspace.

Creating a MDHistoWorkspace

MDHistoWorkspaces typically have 3 or 4 dimensions, although they can be created in up to 9 dimensions.

  • You can bin a MDWorkspace to a MDHistoWorkspace using the BinMD algorithm.
    • You can use CreateMDWorkspace to create a blank MDWorkspace first, if you do not have data to bin.

Viewing a MDHistoWorkspace

  • You can right-click on the workspace and select:
    • Plot MD: to perform a 1D plot of the signal in the workspace (only works on 1D MDHistoWorkspaces).
    • Show Slice Viewer: to open the Sliceviewer, which shows 2D slices of the multiple-dimension workspace.

Working with MD Histo Workspaces in Python

Accessing Workspaces

The methods for getting a variable to an MDHistoWorkspace is the same as shown in the Workspace help page.

If you want to check if a variable points to something that is an MDHistoWorkspace you can use this:

from mantid.api import IMDHistoWorkspace

ws=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
                        SignalInput=range(0,100),ErrorInput=range(0,100),\
                        NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')

if isinstance(ws, IMDHistoWorkspace):
 print(ws.name() + " is a " + ws.id())

Output:

ws is a MDHistoWorkspace

MD Histo Workspace Properties

For a full list of the available properties and operation look at the IMDHistoWorkspace api page.

ws=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
                              SignalInput=range(0,100),ErrorInput=range(0,100),\
                              NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')

print("Number of events = {}".format(ws.getNEvents()))
print("Number of dimensions = {}".format(ws.getNumDims()))
print("Normalization = {}".format(ws.displayNormalization()))
for i in range(ws.getNumDims()):
   dimension = ws.getDimension(i)
   print("\tDimension {0} Name: {1}".format(i,
      dimension.name))

Dimensions

As a generic multi dimensional container being able to access information about the dimensions is very important.

ws=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
                              SignalInput=range(0,100),ErrorInput=range(0,100),\
                              NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')

print("Number of dimensions = {}".format(ws.getNumDims()))
for i in range(ws.getNumDims()):
  dimension = ws.getDimension(i)
  print("\tDimension {0} Name: {1} id: {2} Range: {3}-{4} {5}".format(i,
      dimension.getDimensionId(),
      dimension.name,
      dimension.getMinimum(),
      dimension.getMaximum(),
      dimension.getUnits()))

print("The dimension assigned to X = {}".format(ws.getXDimension().name))
print("The dimension assigned to Y = {}".format(ws.getYDimension().name))
try:
  print("The dimension assigned to Z = " + ws.getZDimension().name)
except RuntimeError:
   # if the dimension does not exist you will get a RuntimeError
  print("Workspace does not have a Z dimension")

# you can also get a dimension by it's id
dim = ws.getDimensionIndexById("Dim1")
# or name
dim = ws.getDimensionIndexByName("Dim2")

Accessing the Data

ws=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
                           SignalInput=range(0,100),ErrorInput=range(0,100),\
                           NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')

# To get the signal and error at a prticular position
index = ws.getLinearIndex(5,5)
print(ws.signalAt(index))
print(ws.errorSquaredAt(index))

# To extract the whole signal array
signalArray =  ws.getSignalArray()
# or the whole error squared array
errorSquaredArray =  ws.getErrorSquaredArray()

Arithmetic Operations

The following algorithms allow you to perform simple arithmetic on the values:

These arithmetic operations propagate errors as described here. The formulas used are described in each algorithm’s wiki page.

The basic arithmetic operators are available from python. For example:

# Get two workspaces
A=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
                                 SignalInput=range(0,100),ErrorInput=range(0,100),\
                                 NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')
B = A.clone()

# Creating a new workspace
C = A + B
C = A - B
C = A * B
C = A / B
# Modifying a workspace in-place
C += A
C -= A
C *= A
C /= A
# Operators with doubles
C = A * 12.3
C *= 3.45

#Compound arithmetic expressions can be made, e.g:
E = (A - B) / (C * C)

Boolean Operations

The MDHistoWorkspace can be treated as a boolean workspace. In this case, 0.0 is “false” and 1.0 is “true”.

The following operations can create a boolean MDHistoWorkspace:

These operations can combine/modify boolean MDHistoWorkspaces:

These boolean operators are available from python. Make sure you use the bitwise operators: & | ^ ~ , not the “word” operators (and, or, not). For example:

# Get two workspaces
A=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
                                 SignalInput=range(0,100),ErrorInput=range(0,100),\
                                 NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')
B = A.clone()

# Create boolean workspaces by comparisons
C = A > B
D = B < 12.34
# Combine boolean workspaces using not, or, and, xor:
not_C = ~C
C_or_D = C | D
C_and_D = C & D
C_xor_D = C ^ D
C |= D
C &= D
C ^= D
# Compound expressions can be used:
D = (A > 123) & (A > B) & (A < 456)

Using Boolean Masks

The SetMDUsingMask algorithm allows you to modify the values in a MDHistoWorkspace using a mask created using the boolean operations above. See the algorithm wiki page for more details.

Category: Concepts