\(\renewcommand\AA{\unicode{x212B}}\)
Fractional Rebinning (RebinnedOutput Workspaces)¶
In some instances of rebinning data, the information of the counts in the bins prior rebinning should be preserved in the output of rebinning in some way. This is because some algorithms depend on how the original data was treated. We achieve this by storing a weight for each bin that corresponds to the fraction between the area of the output bin and the area of the input bin (i.e. prior to rebinning). This kind of Workspace2D that contains information of the areas used during rebinning is called a RebinnedOutput. Some algorithms, such as SofQWNormalisedPolygon and ConvertToReflectometryQ, create this special type of Workspace2D workspace in which each bin contains both a value and the fractional overlap area of this bin over that of the original data. This fractional overlap area value is referred to as a fractional weight, since it has the role of controlling the proportion of the counts in output bins that underwent some coordinate transformation.
To illustrate why using these fractional weights is necessary we explain how rebinning works through the technique of NormalisedPolygon.
NormalisedPolygon Technique¶
NormalisedPolygon is the technique used by SofQWNormalisedPolygon algorithm and it performs a coordinate transformation (from scattering angle theta to momentum transfer Q) followed by the (fractional) rebinning in the new coordinate system.
The fractional rebinning is not unique to this technique, as it could be applied even if there was no coordinate transformation (this is what Rebin2D does). However, while in Rebin2D the input and output grid lines are parallel to each other (no coordinate transformation), the input and output grid lines for NormalisedPolygon are not parallel, resulting in parallelpiped output bins. The algorithm constructs the polygon using the boundaries of the input bin and transforming that polygon into the output coordinates. In the output coordinates, we look for the intersections between the transformed input bin and the output bin:
As shown in the figure, the input bin (pink-shaded parallelopiped) has been transformed to the output bin coordinates and so is not parallel to the output grid. This means the output bins will only ever partially overlap the input data. The resulting value of the output bin is proportional to the overlap between the purple area \(I_0\) and the pink-shaded area \(A_0\). In the general case where each output bin intersects several input bins, the signal \(Y\) and errors \(E\) in the new bins are calculated as:
And the fractional weight of the new bin is stored as the sum of all the weights with intersecting input areas:
The output data will be a workspace with type: RebinnedOutput, which means that it is a Workspace2D with the information of the weigthts on the bins. To see why this is needed, consider the case where another rebin is perfomed after the previous rebinning. This time the output bin sits on a larger grid:
If the fractional weight of the initial rebin were not stored, this rebin operation would have \(F_0=1\), and the resulting weight \(F_1\) would be overestimated. In other words, if the fractional weights are not chained as shown, then the area shaded in a lighter blue under \(A_1\) (where originally there was no data) would be included in the weights, which would lead to an overestimate of the actual weights, and ultimately to an overestimate of the signal and error.
Rebin2D on RebinnedOutput workspaces¶
As mentioned before, the distinction between Fractional Rebinning and normal Rebinning lies in the storage of the fractional weights relative to the original data.
RebinnedOutput workspaces have the fractional weight resulting from previous rebins stored for each input bin. When Rebin2D v1 is called on RebinnedOutput workspaces, the argument UseFractionalArea is always automatically turned on, to ensure the weight fractions are always propagated accross several rebins and that the best possible signal and error estimates are achieved.
When Rebin2D v1 is called on a Workspace2D workspace, by default the argument
UseFractionalArea is set to False, and no fractional weights relative to the original bins are used.
This is consistent with the original implementation of the algorithm, but can cause issues when
used on certain types of workspaces. Take for example a ToF-scattering angle workspace from an
instrument with two sets of detectors at similar scattering angles:
import numpy as np
sample_ws = CreateSampleWorkspace()
theta_tof = ConvertSpectrumAxis(sample_ws, "theta")
theta_tof_fa_false = Rebin2D(theta_tof, '100,400,20000', '0, 0.004, 1', UseFractionalArea=False)
theta_tof_fa_true = Rebin2D(theta_tof, '100,400,20000', '0, 0.004, 1', UseFractionalArea=True)
By default CreateSampleWorkspace v1 uses the “basic_rect” instrument which has two
detectors around the straight-through beam direction: one at 5m and one at 10m. You can see this
if you right click on the sample_ws workspace and select “Instrument View”.
When this workspace is converted to scattering angle (theta), the pixels on the 5m and 10m
detectors will overlap because they have similar theta values. You can see this by right clicking
the workspace and select “Show Data” and look along the row labels - you should see several labels
repeated and others at non-uniform gaps.
The theta_tof workspace thus has non-uniform bins in the theta axis, and if you use
Rebin2D v1 with UseFractionalArea=False these bins will not be correctly normalised.
To see this, plot the workspaces theta_tof, theta_tof_fa_false and theta_tof_fa_true using the
SliceViewer. You will see that theta_tof_fa_false looks distinctly different with random intensity spots
whilst theta_tof and theta_tof_fa_true looks similar with only a single ToF peak.
We would thus recommend to always use UseFractionalArea=True with Rebin2D v1.
One final consideration is that RebinnedOutput workspaces are always treated as distributions. That is, the output counts and uncertainties are always renormalised by the fractional weights:
If this is not done, then the output will look similarly to the case with UseFractionalArea=False with
random intensity spots. This means that internally the RebinnedOutput workspace stores
\(Y^{\mathrm{new}}\) and \(F^{\mathrm{new}}\) but when you plot the data,
or use “Show Data”, you will get \(Y^{\mathrm{output}}\).
Thus if you view the data of theta_tof_fa_true you will see that the values generally match that of
theta_tof whereas the data values of theta_tof_fa_false will be a factor of approximately 1/3 that of
theta_tof due to the new bin size being twice as large in the ToF axis and 1.5 times as large in the theta
axis.
Integration on RebinnedOutput workspaces¶
The Integration v1 algorithm operates differently on RebinnedOutput workspaces and Workspace2D workspaces. For Workspace2D workspaces, the integrated counts per spectra is simply the sum of the counts in the bins within the Integration range:
In the case of RebinnedOutput, we take into the accout the fractional area weights \(F_i\):
where \(Y_i\) and \(F_i\) are the values and fractions for the \(i^{\mathrm{th}}\)
bin and \(n\) is the number of bins in the range which is not NaN.
We can check that the factor \(1/n\) is needed by looking at the special case where the fractional
weights are all set to \(F_i = 1\). In this case, the result of the integral yields
\(\sum_i Y_i\), which is what we expect for an integral over bins with no fractional area weights.
Notes¶
Tip
For correct handling of the fractional weights in rebinning, the user is recommended to use the Rebin2D v1 algorithm in preference to Integration v1 or SumSpectra v1 although the other algorithms do account for the fractional weights.
Warning
All binary and unary operations on workspaces will ignore the fractional weights. Thus it is important to handle all background subtractions and scaling in the original reduced dataset(s) before conversion using SofQWNormalisedPolygon v1.
Category: Concepts