IntegratePeaksShapeMD v1#

Summary#

Integrate Single Crystal Diffraction Bragg peaks using the ellipsoidal peak shape already stored on each peak.

Properties#

Name	Direction	Type	Default	Description
InputWorkspace	Input	`MatrixWorkspace`	Mandatory	An input MatrixWorkspace with time-of-flight units along X-axis and defined instrument with defined sample
PeaksWorkspace	InOut	PeaksWorkspace	Mandatory	Workspace with peaks to be integrated. Each peak must already have an ellipsoidal shape set, e.g. from a previous IntegrateEllipsoids run.
RegionRadius	Input	number	0.35	Only events at most this distance from a peak will be considered when integrating. Must be at least as large as the largest background outer radius among the peaks being integrated, or the background shell will be truncated.
UseOnePercentBackgroundCorrection	Input	boolean	True	If this options is enabled, then the top 1% of the background will be removed before the background subtraction.
ProfileFit	Input	boolean	False	If true, integrate by maximizing the Poisson log-likelihood of a Gaussian peak plus a flat background rate fit against the raw events, instead of counting events inside/outside ellipsoidal boundaries. In this mode the peak radii are interpreted as the Gaussian’s standard deviations (1-sigma), and the background radii are unused.
AdjustCenter	Input	boolean	False	Only used if ProfileFit is true. If true, also refine each peak’s center by a bounded Gauss-Newton correction (capped at one standard deviation from the peak’s stored Q) as part of the profile fit, instead of keeping it fixed at the peak’s stored Q. The peak’s stored Q is not modified; the correction is used only for this integration.
OutputWorkspace	Output	PeaksWorkspace	Mandatory	The output PeaksWorkspace will be a copy of the input PeaksWorkspace with the peaks’ integrated intensities.

Description#

This algorithm integrates single crystal Bragg peaks by reusing the ellipsoidal peak shape already stored on each peak in the input PeaksWorkspace, instead of fitting a new shape from the events around each peak. It sums the raw or weighted events inside that fixed ellipsoid and subtracts a background estimate from the ellipsoidal shell already defined by the shape’s own background inner and outer radii – unlike IntegrateEllipsoidsTwoStep v1, this algorithm has no PeakSize, BackgroundInnerSize or BackgroundOuterSize properties of its own; every peak’s ellipsoid is used exactly as stored. This also differs from IntegratePeaksMD v2, which always integrates with a spherical (not ellipsoidal) region computed from user-specified radii rather than a shape stored on the peak.

The PeaksWorkspace must already have an ellipsoidal shape set on every peak to be integrated, for example from a previous run of IntegrateEllipsoids v3 or IntegrateEllipsoidsTwoStep v1. This makes the algorithm useful for re-integrating the same or a different event workspace (e.g. a rebinned, background-subtracted, or otherwise corrected dataset) without re-deriving the peak shapes each time, or for comparing intensities obtained with a shape held fixed across multiple datasets.

Peaks must be indexed with integral HKL values, in the same way as for IntegrateEllipsoidsTwoStep v1: the indexed peaks are used to determine a UB matrix, whose inverse is used to assign each event to the nearest peak in reciprocal space. Only events within RegionRadius of a peak’s Q-vector are considered; this should be at least as large as the largest background outer radius among the peaks being integrated, or the background shell will be truncated.

If UseOnePercentBackgroundCorrection is enabled (the default), the top 1% of the background events are removed before background subtraction, to reduce sensitivity to intensity spikes from nearby peaks.

Integration method#

By default (ProfileFit = False) each peak is integrated by counting raw or weighted events inside the peak ellipsoid, and subtracting a background estimate from the ellipsoidal shell, the same background-subtraction method IntegrateEllipsoidsTwoStep v1 uses (based on the ILL program Racer and Wilkinson, C., et al. “Integration of single-crystal reflections using area multidetectors.” Journal of Applied Crystallography 21.5 (1988): 471-478) – applied here to a supplied, rather than fitted, ellipsoid.

If ProfileFit is enabled, each peak is instead integrated by directly maximizing the (weighted) Poisson log-likelihood of an unbinned point process, fitting a Gaussian peak amplitude and a flat background rate against the raw events within RegionRadius of the peak. In this mode the peak radii are interpreted as the Gaussian’s standard deviations (1-sigma) along its principal axes rather than as hard integration boundaries, and the background radii are not used since the background rate is fit directly instead. This can make better use of the available events for weak peaks than a simple ellipsoidal count, at the cost of assuming the peak profile is well described by a Gaussian and that essentially all of its intensity falls within RegionRadius.

Any scaling or mosaic-broadening correction to a peak’s shape (e.g. derived from a resolution model, or refined per-sample) is expected to be applied by the caller before running this algorithm, by writing the corrected radii directly into the PeaksWorkspace’s stored shapes – this algorithm always uses the shape it is given exactly as supplied, with no adjustment of its own.

By default the peak center used is always the peak’s own stored Q-vector; neither integration method refines or re-centers it, matching IntegrateEllipsoidsTwoStep v1, which also never adjusts a peak’s center (weak peaks borrow a strong peak’s shape, but stay centered at their own stored Q). If ProfileFit and AdjustCenter are both enabled, the center is additionally refined by a bounded Gauss-Newton correction as part of the same fit, capped at one standard deviation of shift from the peak’s stored Q – a slight correction, not a free centroid search. This correction is only used for this integration; it is not written back to the peak’s stored position.

Usage#

# PeaksWorkspace already integrated once, so every peak has a shape
IntegrateEllipsoids(InputWorkspace='TOPAZ_3132_event', PeaksWorkspace='TOPAZ_3132_peaks',
                    OutputWorkspace='TOPAZ_3132_peaks')

# Reuse those shapes to integrate again, e.g. after correcting the events
IntegratePeaksShapeMD(InputWorkspace='TOPAZ_3132_event', PeaksWorkspace='TOPAZ_3132_peaks',
                      RegionRadius='0.25', OutputWorkspace='TOPAZ_3132_peaks_reintegrated')