3.10

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.

Viewing a MDHistoWorkspace

  • MDHistoWorkspaces can be created and visualized directly within Paraview and the Vates Simple Interface when rebinning along a regular grid.
  • 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 Slice Viewer, 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 =", ws.getNEvents()
print "Number of dimensions =", ws.getNumDims()
print "Normalization =", 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 =", 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 =", ws.getXDimension().name
print "The dimension assigned to Y =", 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 aray
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