4.0

BinMD v1

../_images/BinMD-v1_dlg.png

BinMD dialog.

Summary

Take a MDEventWorkspace and bin into into a dense, multi-dimensional histogram workspace (MDHistoWorkspace).

Properties

Name Direction Type Default Description
InputWorkspace Input IMDWorkspace Mandatory An input MDWorkspace.
AxisAligned Input boolean True Perform binning aligned with the axes of the input MDEventWorkspace?
AlignedDim0 Input string   Binning parameters for the 0th dimension. Enter it as a comma-separated list of values with the format: ‘name,minimum,maximum,number_of_bins’. Leave blank for NONE.
AlignedDim1 Input string   Binning parameters for the 1th dimension. Enter it as a comma-separated list of values with the format: ‘name,minimum,maximum,number_of_bins’. Leave blank for NONE.
AlignedDim2 Input string   Binning parameters for the 2th dimension. Enter it as a comma-separated list of values with the format: ‘name,minimum,maximum,number_of_bins’. Leave blank for NONE.
AlignedDim3 Input string   Binning parameters for the 3th dimension. Enter it as a comma-separated list of values with the format: ‘name,minimum,maximum,number_of_bins’. Leave blank for NONE.
AlignedDim4 Input string   Binning parameters for the 4th dimension. Enter it as a comma-separated list of values with the format: ‘name,minimum,maximum,number_of_bins’. Leave blank for NONE.
AlignedDim5 Input string   Binning parameters for the 5th dimension. Enter it as a comma-separated list of values with the format: ‘name,minimum,maximum,number_of_bins’. Leave blank for NONE.
BasisVector0 Input string   Description of the basis vector of the 0th output dimension.Format: ‘name, units, x,y,z,..’. name : string for the name of the output dimension. units : string for the units of the output dimension. x,y,z,...: vector definining the basis in the input dimensions space. Leave blank for NONE.
BasisVector1 Input string   Description of the basis vector of the 1th output dimension.Format: ‘name, units, x,y,z,..’. name : string for the name of the output dimension. units : string for the units of the output dimension. x,y,z,...: vector definining the basis in the input dimensions space. Leave blank for NONE.
BasisVector2 Input string   Description of the basis vector of the 2th output dimension.Format: ‘name, units, x,y,z,..’. name : string for the name of the output dimension. units : string for the units of the output dimension. x,y,z,...: vector definining the basis in the input dimensions space. Leave blank for NONE.
BasisVector3 Input string   Description of the basis vector of the 3th output dimension.Format: ‘name, units, x,y,z,..’. name : string for the name of the output dimension. units : string for the units of the output dimension. x,y,z,...: vector definining the basis in the input dimensions space. Leave blank for NONE.
BasisVector4 Input string   Description of the basis vector of the 4th output dimension.Format: ‘name, units, x,y,z,..’. name : string for the name of the output dimension. units : string for the units of the output dimension. x,y,z,...: vector definining the basis in the input dimensions space. Leave blank for NONE.
BasisVector5 Input string   Description of the basis vector of the 5th output dimension.Format: ‘name, units, x,y,z,..’. name : string for the name of the output dimension. units : string for the units of the output dimension. x,y,z,...: vector definining the basis in the input dimensions space. Leave blank for NONE.
Translation Input dbl list   Coordinates in the INPUT workspace that corresponds to (0,0,0) in the OUTPUT workspace. Enter as a comma-separated string. Default: 0 in all dimensions (no translation).
OutputExtents Input dbl list   The minimum, maximum edges of space of each dimension of the OUTPUT workspace, as a comma-separated list
OutputBins Input int list   The number of bins for each dimension of the OUTPUT workspace.
NormalizeBasisVectors Input boolean True Normalize the given basis vectors to unity. If true, then a distance of 1 in the INPUT dimensions = 1 in the OUTPUT dimensions. If false, then a distance of norm(basis_vector) in the INPUT dimension = 1 in the OUTPUT dimensions.
ForceOrthogonal Input boolean False Force the input basis vectors to form an orthogonal coordinate system. Only works in 3 dimension!
ImplicitFunctionXML Input string   XML string describing the implicit function determining which bins to use.
IterateEvents Input boolean True Alternative binning method where you iterate through every event, placing them in the proper bin. This may be faster for workspaces with few events and lots of output bins.
Parallel Input boolean False Temporary parameter: true to run in parallel. This is ignored for file-backed workspaces, where running in parallel makes things slower due to disk thrashing.
TemporaryDataWorkspace Input IMDHistoWorkspace   An input MDHistoWorkspace used to accumulate results from multiple MDEventWorkspaces. If unspecified a blank MDHistoWorkspace will be created.
OutputWorkspace Output Workspace Mandatory A name for the output MDHistoWorkspace.

Description

This algorithm performs dense binning of the events in multiple dimensions of an input MDWorkspace and places them into a dense MDHistoWorkspace with 1-4 dimensions.

The input MDWorkspace may have more dimensions than the number of output dimensions. The names of the dimensions in the DimX, etc. parameters are used to find the corresponding dimensions that will be created in the output.

An ImplicitFunction can be defined using the ImplicitFunctionXML parameter; any points NOT belonging inside of the ImplicitFunction will be set as NaN (not-a-number).

Axis-Aligned Binning

This is binning where the output axes are aligned with the original workspace. Specify each of the AlignedDim0, etc. parameters with these values, separated by commas:

  • First, the name of the dimension in the original workspace
  • Next, the start and end position along that dimension
  • Finally, the number of bins to use in that dimensions.

If you specify fewer output dimensions, then events in the remaining dimensions will be integrated along all space. If you wish to integrate only within a range, then specify the start and end points, with only 1 bin.

Non-Axis Aligned Binning

This allows rebinning to a new arbitrary space, with rotations, translations, or skewing. This is given by a set of basis vectors and other parameters

The BasisVector0... parameters allow you to specify the basis vectors relating the input coordinates to the output coordinates. They are string with these parameters, separated by commas: ‘name, units, x,y,z,..,’:

  • Name: of the new dimension
  • Units: string giving the units
  • x, y, z, etc.: a vector, matching the number of dimensions, giving the direction of the basis vector

The Translation parameter defines the translation between the spaces. The coordinates are given in the input space dimensions, and they correspond to 0,0,0 in the output space.

The OutputExtents parameter specifies the min/max coordinates in the output coordinate space. For example, if you the output X to range from -5 to 5, and output Y to go from 0 to 10, you would have: “-5,5, 0,10”.

The OutputBins parameter specifies how many bins to use in the output workspace for each dimension. For example, “10,20,30” will make 10 bins in X, 20 bins in Y and 30 bins in Z.

If the NormalizeBasisVectors parameter is True, then the distances in the input space are the same as in the output space (no scaling).

  • For example, if BasisVector0=(1,1), a point at (1,1) transforms to x=\sqrt{2}, which is the same as the distance in the input dimension.

If the NormalizeBasisVectors parameter is False, then the algorithm will take into account the length of each basis vector.

  • For example, if BasisVector0=(1,1), a point at (1,1) transforms to x=1. The distance was scaled by 1/\sqrt{2}

Finally, the ForceOrthogonal parameter will modify your basis vectors if needed to make them orthogonal to each other. Only works in 3 dimensions!

Binning a MDHistoWorkspace

It is possible to rebin a MDHistoWorkspace. Each MDHistoWorkspace holds a reference to the MDWorkspace that created it, as well as the coordinate transformation that was used. In this case, the rebinning is actually performed on the original MDWorkspace, after suitably transforming the basis vectors.

Only the non-axis aligned binning method can be performed on a MDHistoWorkspace! Of course, your basis vectors can be aligned with the dimensions, which is equivalent.

For more details on the coordinate transformations applied in this case, please see BinMD Coordinate Transformations.

BinMD_Coordinate_Transforms_withLine.png

Usage

Axis Aligned Example

mdws = CreateMDWorkspace(Dimensions=3, Extents='-10,10,-10,10,-10,10', Names='A,B,C', Units='U,U,U')
FakeMDEventData(InputWorkspace=mdws, PeakParams='500000,0,0,0,3')
binned_ws = BinMD(InputWorkspace=mdws, AlignedDim0='A,0,10,100', AlignedDim1='B,-10,10,100', AlignedDim2='C,-10,10,100')
print("Number of events = {}".format(binned_ws.getNEvents()))

Output:

Number of events = 250734

The output looks like the following in the SliceViewer:

The sliceveiwer with the axis aligned cut

Non Axis Aligned Example

import math
mdws = CreateMDWorkspace(Dimensions=3, Extents='-10,10,-10,10,-10,10', Names='A,B,C', Units='U,U,U')
FakeMDEventData(InputWorkspace=mdws, PeakParams='100000,-5,-5,0,1')
FakeMDEventData(InputWorkspace=mdws, PeakParams='100000,0,0,0,1')
FakeMDEventData(InputWorkspace=mdws, PeakParams='100000,5,5,0,1')
binned_ws = BinMD(InputWorkspace=mdws, AxisAligned=False, BasisVector0='a,unit,1,1,0',BasisVector1='b,unit,-1,1,0',BasisVector2='c,unit,0,0,1',NormalizeBasisVectors=True,Translation=[-10,-10,0], OutputExtents=[0,math.sqrt(2*20*20),-2,2,-10,10], OutputBins=[100, 100, 1] )
print("Number of events = {}".format(binned_ws.getNEvents()))

Output:

Number of events = 300000

The output looks like the following in the SliceViewer:

The sliceveiwer with the non axis aligned cut

Accumulation Example

binned_ws=None
for x in range(3):
    mdws = CreateMDWorkspace(Dimensions=2, Extents='-10,10,-10,10', Names='A,B', Units='U,U')
    FakeMDEventData(InputWorkspace=mdws, PeakParams='500000,'+str(x)+',0,3')
    binned_ws = BinMD(InputWorkspace=mdws, AlignedDim0='A,-10,10,100', AlignedDim1='B,-10,10,100', TemporaryDataWorkspace=binned_ws)
print("Number of events = {}".format(binned_ws.getNEvents()))

Output:

Number of events = 1500000

Categories: Algorithm Index | MDAlgorithms\Slicing

Source

C++ source: BinMD.cpp (last modified: 2018-10-05)

C++ header: BinMD.h (last modified: 2018-10-05)