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

Rebin v1¶

Summary ¶

Rebins data with new X bin boundaries. For EventWorkspaces, you can very quickly rebin in-place by keeping the same output name and PreserveEvents=true.

Properties ¶

Name	Direction	Type	Default	Description
InputWorkspace	Input	MatrixWorkspace	Mandatory	Workspace containing the input data
OutputWorkspace	Output	MatrixWorkspace	Mandatory	The name to give the output workspace
Params	Input	dbl list	Mandatory	A comma separated list of first bin boundary, width, last bin boundary. Optionally this can be followed by a comma and more widths and last boundary pairs. Optionally this can also be a single number, which is the bin width. In this case, the boundary of binning will be determined by minimum and maximum TOF values among all events, or previous binning boundary, in case of event Workspace, or non-event Workspace, respectively. Negative width values indicate logarithmic binning.
PreserveEvents	Input	boolean	True	Keep the output workspace as an EventWorkspace, if the input has events. If the input and output EventWorkspace names are the same, only the X bins are set, which is very quick. If false, then the workspace gets converted to a Workspace2D histogram.
FullBinsOnly	Input	boolean	False	Omit the final bin if its width is smaller than the step size
IgnoreBinErrors	Input	boolean	False	Ignore errors related to zero/negative bin widths in input/output workspaces. When ignored, the signal and errors are set to zero
UseReverseLogarithmic	Input	boolean	False	For logarithmic intervals, the splitting starts from the end and goes back to the start, ie the bins are bigger at the start getting exponentially smaller until they reach the end. For these bins, the FullBinsOnly flag is ignored.
Power	Input	number	0	Splits the interval in bins which actual width is equal to requested width / (i ^ power); default is linear. Power must be between 0 and 1.
BinningMode	Input	string	Default	Optional. Binning behavior can be specified in the usual way through sign of binwidth and other properties (‘Default’); or can be set to one of the allowed binning modes. This will override all other specification or default behavior. Allowed values: [‘Default’, ‘Linear’, ‘Logarithmic’, ‘ReverseLogarithmic’, ‘Power’]

The algorithm rebins data with new bin boundaries. The ‘params’ property defines new boundaries in intervals \(x_i-x_{i+1}\,\). Positive \(\Delta x_i\,\) make constant width bins, whilst negative ones create logarithmic binning using the formula \(x(j+1)=x(j)(1+|\Delta x_i|)\,\)

If UseReverseLogarithmic is set to True, the negative values create reverse logarithmic binning, i.e. a binning whose bins are first big and then get exponentially smaller as they become close to the end of the specified interval. The bins are the same as those generated by a normal log with these parameters, but arranged in the reversed order. The first bin will be merged with the second one if the former is smaller than the latter.

If BinningMode is set to any value other than “Default”, the usual behavior will be overriden and only the specidied binning mode will be used. Options are “Linear”, “Logarithmic”, “ReverseLogarithmic”n and “Power”. When set, the algorithm will use the specified binning method regardless of how other parameters are set, and reset parameters to force consistency with specified binning mode. This can help reduce inadvertent sign errors in logarithmic binning calculations, or otherwise ensure expected behavior in calculations.

This algorithms is useful both in data reduction, but also in remapping ragged workspace to a regular set of bin boundaries.

Unless the FullBinsOnly option is enabled, the bin immediately before the specified boundaries \(x_2\), \(x_3\), … \(x_i\) is likely to have a different width from its neighbours because there can be no gaps between bins. Rebin ensures that any of these space filling bins cannot be less than 25% or more than 125% of the width that was specified.

In both cases, where a new bin only partially overlaps one or more input bins, the new counts are calculated as the sum of the old bins weighted by the fractional overlapping widths of the new bin over the old bin:

\[Y^{\mathrm{new}} = \sum_i Y^{\mathrm{old}}_i F_i\]

\[E^{\mathrm{new}} = \sqrt{\sum_i (E^{\mathrm{old}}_i)^2 F_i}\]

where \(F_i = w^{\mathrm{overlap}}_i / w^{\mathrm{old}}_i\) is the ratio of the overlap width of the new and old bin over the old bin width.

Example Rebin param strings ¶

“-0.0001”: from min(TOF) to max(TOF) among all events in Logarithmic bins of 0.0001
“*0,100,20000”: from 0 rebin in constant size bins of 100 up to 20,000
“2,-0.035,10”: from 10 rebin in Logarithmic bins of 0.035 up to 10
“0,100,10000,200,20000”: from 0 rebin in steps of 100 to 10,000 then steps of 200 to 20,000

For EventWorkspaces ¶

If the input is an EventWorkspace and the “Preserve Events” property is True, the rebinning is performed in place, and only the X axes of the workspace are set. The actual Y histogram data will only be requested as needed, for example, when plotting or displaying the data.

If “Preserve Events” is false., then the output workspace will be created as a Workspace2D, with fixed histogram bins, and all Y data will be computed immediately. All event-specific data is lost at that point.

For Data-Point Workspaces ¶

If the input workspace contains data points, rather than histograms, then Rebin will automatically use the ConvertToHistogram and ConvertToPointData algorithms before and after the rebinning has taken place.

FullBinsOnly option ¶

If FullBinsOnly option is enabled, each range will only contain bins of the size equal to the step specified. In other words, the will be no space filling bins which are bigger or smaller than the other ones.

This, however, means that specified bin boundaries might get amended in the process of binning. For example, if rebin Param string is specified as “0, 2, 4.5, 3, 11” and FullBinsOnly is enabled, the following will happen:

From 0 rebin in bins of size 2 up to 4. 4.5 is ignored, because otherwise we would need to create a filling bin of size 0.5.
From 4 rebin in bins of size 3 up to 10.

Hence the actual Param string used is “0, 2, 4, 3, 10”.

This flag is ignored if UseReverseLogarithm is checked.

Power option ¶

If a value between 0 (excluded) and 1 (included) is provided in the Power field, the binning will follow an inverse power pattern, each bin having a width of

\[w_i = \frac{F}{i^{\mathrm{power}}}\]

where F is the factor provided between the boundaries. Since, even though these series diverge and will reach whatever bounds are given, they might take an exponentially slow time to reach them, and thus an exponential number of bins, a check ensure that the total number of bins is not greater than 10000.

Usage ¶

Example - simple rebin of a histogram workspace:

# create histogram workspace
dataX = [0,1,2,3,4,5,6,7,8,9] # or use dataX=range(0,10)
dataY = [1,1,1,1,1,1,1,1,1] # or use dataY=[1]*9
ws = CreateWorkspace(dataX, dataY)

# rebin from min to max with size bin = 2
ws = Rebin(ws, 2)

print("The rebinned X values are: {}".format(ws.readX(0)))
print("The rebinned Y values are: {}".format(ws.readY(0)))

Output:

The rebinned X values are: [0. 2. 4. 6. 8. 9.]
The rebinned Y values are: [2. 2. 2. 2. 1.]

Example - logarithmic rebinning:

# create histogram workspace
dataX = [1,2,3,4,5,6,7,8,9,10] # or use dataX=range(1,11)
dataY = [1,2,3,4,5,6,7,8,9] # or use dataY=range(1,10)
ws = CreateWorkspace(dataX, dataY)

# rebin from min to max with logarithmic bins of 0.5
ws = Rebin(ws, -0.5)

print("The 2nd and 3rd rebinned X values are: {}".format(ws.readX(0)[1:3]))

Output:

The 2nd and 3rd rebinned X values are: [1.5  2.25]

Example - Reverse logarithmic rebinning:

# create histogram workspace
dataX = [1,2,3,4,5,6,7,8,9,10] # or use dataX=range(1,11)
dataY = [1,2,3,4,5,6,7,8,9] # or use dataY=range(1,10)
ws = CreateWorkspace(dataX, dataY)

# rebin from min to max - 1 with reverse logarithmic bins of growth factor 1
ws = Rebin(ws, "1, -1, 9", UseReverseLogarithmic=True)

print("The rebinned X values are: {}".format(ws.readX(0)))

Output:

The rebinned X values are: [1. 6. 8. 9.]

Example - Inverse power rebinning:

import numpy as np
# create histogram workspace
dataX = [1,2,3,4,5,6,7,8,9,10] # or use dataX=range(1,11)
dataY = [1,2,3,4,5,6,7,8,9] # or use dataY=range(1,10)
ws = CreateWorkspace(dataX, dataY)

# rebin from min to max - 1 with square root
ws = Rebin(ws, "1, 3, 10", Power=0.5)

print("The rebinned X values are: {}".format(np.array_str(ws.readX(0), precision=5)))

Output:

The rebinned X values are: [ 1.       4.       6.12132  7.85337  9.35337 10.     ]

Example - custom two regions rebinning:

# create histogram workspace
dataX = [0,1,2,3,4,5,6,7,8,9] # or use dataX=range(0,10)
dataY = [0,1,2,3,4,5,6,7,8] # or use dataY=range(0,9)
ws = CreateWorkspace(dataX, dataY)

# rebin from 0 to 3 in steps of 2 and from 3 to 9 in steps of 3
ws = Rebin(ws, "1,2,3,3,9")

print("The rebinned X values are: {}".format(ws.readX(0)))

Output:

The rebinned X values are: [1. 3. 6. 9.]

Example - use option FullBinsOnly:

# create histogram workspace
dataX = [0,1,2,3,4,5,6,7,8,9] # or use dataX=range(0,10)
dataY = [1,1,1,1,1,1,1,1,1] # or use dataY=[1]*9
ws = CreateWorkspace(dataX, dataY)

# rebin from min to max with size bin = 2
ws = Rebin(ws, 2, FullBinsOnly=True)

print("The rebinned X values are: {}".format(ws.readX(0)))
print("The rebinned Y values are: {}".format(ws.readY(0)))

Output:

The rebinned X values are: [0. 2. 4. 6. 8.]
The rebinned Y values are: [2. 2. 2. 2.]

Example - use option PreserveEvents:

# create some event workspace
ws = CreateSampleWorkspace(WorkspaceType="Event")

print("What type is the workspace before 1st rebin: {}".format(ws.id()))
# rebin from min to max with size bin = 2 preserving event workspace (default behaviour)
ws = Rebin(ws, 2)
print("What type is the workspace after 1st rebin: {}".format(ws.id()))
ws = Rebin(ws, 2, PreserveEvents=False)
print("What type is the workspace after 2nd rebin: {}".format(ws.id()))
# note you can also check the type of a workspace using: print(isinstance(ws, IEventWorkspace))

Output:

What type is the workspace before 1st rebin: EventWorkspace
What type is the workspace after 1st rebin: EventWorkspace
What type is the workspace after 2nd rebin: Workspace2D

Categories: AlgorithmIndex | Transforms\Rebin

Source ¶

C++ header: Rebin.h

C++ source: Rebin.cpp

Rebin v1¶

Summary ¶

See Also ¶

Properties ¶

Description ¶

Example Rebin param strings ¶

For EventWorkspaces ¶

For Data-Point Workspaces ¶

FullBinsOnly option ¶

Power option ¶

Usage ¶

Source ¶