HFIRGoniometerIndependentBackground v1#

Summary#

Generates a background from a 3 dimensional MDHistoWorkspace.

Properties#

Name	Direction	Type	Default	Description
InputWorkspace	Input	IMDHistoWorkspace	Mandatory	Input workspace, must be a 3 dimensional MDHistoWorkspace
BackgroundLevel	Input	number	50	Percentile in the range 0 to 100 defining the background level (default 50, median filter)
BackgroundWindowSize	Input	number	Optional	Background window size, only applies to the rotation axis, assumes the detectors are already grouped. Leave unset to use every value along the rotation axis
FilterMode	Input	string	nearest	Mode should be ‘nearest’ if the rotation is incomplete or ‘wrap’ if complete within a reasonable tolerance. Allowed values: [‘nearest’, ‘wrap’]
NormalizeBy	Input	string	None	Normalize the input by per-rotation duration or monitor count before calculating the background. Allowed values: [‘None’, ‘Time’, ‘Monitor’]
NormalizeOutput	Input	boolean	False	Keep the output normalized when True; otherwise multiply the calculated normalized background by the duration or monitor count of each rotation
OutputWorkspace	Output	`Workspace`	Mandatory

Description#

This algorithm is used to generate a background for HFIR monochromatic diffraction data. For every detector pixel it takes a percentile of the intensities recorded along the rotation axis. Bragg scattering illuminates a pixel for only part of the scan while the background persists, so a percentile rejects the peaks and retains the goniometer-independent level.

When BackgroundWindowSize is set, the percentile is taken over a sliding window of that many rotation steps, allowing the background to vary slowly with rotation angle. It selects a ranked value in the same way as Scipy.ndimage.percentile_filter. When the property is left unset, the percentile is taken over the whole rotation axis and the background is constant in rotation for each pixel; the value is interpolated linearly between order statistics, as Numpy.percentile does.

BackgroundLevel is a percentile and must lie between 0 and 100. It defaults to 50, which takes the median along the rotation axis.

The optional NormalizeBy property can be set to Time or Monitor to divide each rotation by its duration or monitor count before calculating the percentile. None does no normalization. NormalizeOutput controls the units of the result. When it is True, the output background remains normalized when the user chooses Time or Monitor. When it is False (the default), the result is multiplied by time duration or monitor count of each rotation. The corresponding error variances are scaled consistently.

For WAND (HB2C), the duration and monitor_count sample logs are used. For DEMAND (HB3A), the corresponding logs are named time and monitor. Normalization is not supported for other instruments.

Uncertainties#

The percentile is an estimator built from the rotation steps that contribute to it, not a single measurement, so it is more precise than the value it selects. For \(n\) contributing rotations whose values have standard deviation \(\sigma\), the output variance is

\[\mathrm{Var}(\hat{q}_p) = \frac{p(1-p)}{\phi(z_p)^2} \frac{\sigma^2}{n}\]

where \(p\) is BackgroundLevel expressed as a fraction, \(z_p\) is the standard normal quantile at \(p\) and \(\phi\) its density. The leading factor is \(\pi/2\) for the median, giving the familiar \(1.2533\,\sigma/\sqrt{n}\). Here \(n\) is the length of the rotation axis when BackgroundWindowSize is unset, and BackgroundWindowSize otherwise, while \(\sigma^2\) is the input variance of the value the percentile selected. Taking \(\sigma\) at the percentile rather than across all contributing rotations keeps the estimate free of the Bragg peaks that the percentile is chosen to reject.

A BackgroundLevel of 0 or 100 selects the smallest or largest value, for which this limit does not apply; those cases keep the variance of the selected value, which is a conservative upper bound.

Two limitations are worth noting. Where the sliding window is padded at the ends of an incomplete rotation, it repeats values, so fewer than BackgroundWindowSize independent rotations contribute and the variance is slightly underestimated. More importantly, the output uncertainties are strongly correlated - completely so across the rotation axis when BackgroundWindowSize is unset, and between neighbouring rotations otherwise, since their windows overlap. A MDHistoWorkspace cannot represent that correlation, so any subsequent operation that combines these values along the rotation axis will underestimate the resulting uncertainty.

Usage#

# create workspace
import numpy as np
signal = np.random.randint(low=0, high=10, size=(100,100,100))
workspace = CreateMDHistoWorkspace(SignalInput=signal,
                                   ErrorInput=np.ones_like(signal),
                                   Dimensionality=3,
                                   Extents='0,10,0,10,0,10',
                                   Names='x,y,z',
                                   NumberOfBins='100,100,100',
                                   Units='number,number,number',
                                   OutputWorkspace='output')



# Perform the background interpolation
outputWS = HFIRGoniometerIndependentBackground(workspace, BackgroundWindowSize=10)

# Check output
print("Shape of the resulting Signal is: {}".format(outputWS.getSignalArray().shape))

Output:

Shape of the resulting Signal is: (100, 100, 100)

Categories: AlgorithmIndex | Diffraction\Reduction | Diffraction\Utility

Source#

Python: HFIRGoniometerIndependentBackground.py