IntegrateEllipsoids v2¶

See Also¶

IntegrateEllipsoidsTwoStep

Overview and similar algorithms¶

This algorithm will integrate disjoint single crystal Bragg peaks by summing the number of raw or weighted events in a 3D ellipsoidal peak region in reciprocal space (QLab frame) and subtracting an estimate of the background obtained from an ellipsoidal shell. In some ways it is similar to the IntegratePeaksMD v2 algorithm. In particular the size parameters to this algorithm are also specified in inverse Angstroms and the background subtraction is done in the same way for both the intensity and the estimated standard deviations. However, this algorithm differs from IntegratePeaksMD v2 in several critical ways.

• This algorithm works directly with raw or weighted events while IntegratePeaksMD v2 uses MDEvents from MDEventWorkspace.
• This algorithm uses 3D ellipsoidal regions with aspect ratios that are adapted to the set of events that are near the peak center, while IntegratePeaksMD v2 uses spherical or ellipsoidal regions.
• This algorithm includes an option to automatically choose the size of the ellipsoidal regions based on the statistics of the set of events near the peak.

The algorithm calculates the three principal axes of the events near a peak, and uses the standard deviations in the directions of the principal axes to determine the aspect ratio of ellipsoids used for the peak and background regions.

By default, the satellite peaks are processed through the same pipeline as the Bragg peaks. If desired, users can specify satellite peaks specific integration parameters so that a different integrator is used to integrate the satellite peaks.

Explanation of Inputs¶

• The event data to be integrated is obtained from an ordinary EventWorkspace with an X-axis in time-of-flight, as loaded from a NeXus event file. This algorithm maps the events to reciprocal space using PeaksWorkspace with indexed peaks to determine the parameters of the transformation into the reciprocal space
• The peaks to be integrated are are also obtained from a PeaksWorkspace. The peaks must be indexed, and any peaks indexed as (0,0,0) will be ignored.
• Only events that are near a peak are considered when constructing the ellipsoids. The RegionRadius specifies the maximum distance from the peak center to an event in reciprocal space, for that event to be used. See the figure below. Also, each event will be counted for at most one peak, the one with the nearest QLab value. The RegionRadius should be specified to be just slightly larger than the expected peak region to avoid overlap with other peaks, and to avoid including excessive background. As the size of the RegionRadius increases, the ellipsoids will become more spherical and less well adapted to the actual shape of the peak.

Integrate ellipsoids algorithm regions map.

• If the SpecifySize option is selected, then the user MUST specify the PeakSize, BackgroundInnerSize and BackgroundOuterSize. In this mode, the algorithm is similar to the IntegratePeaksMD v2 algorithm. As shown in the figure, these values determine the length of the major axis for the ellipsoidal peak region, and of the inner and outer ellipsoids bounding the background region. The same major axis lengths are used for all peaks, but the lengths of the other two axes of the ellipsoids are adjusted based on the standard deviations of the events in those directions. If SpecifySize is false, then the major axis length for each peak will be set to include a range of plus or minus three times the standard deviation of the events in that direction. That is, PeakSize is set to three times the standard deviation in the direction of the first principal axis. Also, in this case the BackgroundInnerSize is set to the PeakSize and the BackgroundOuterSize is set so that the background ellipsoidal shell has the same volume as the peak ellipsoidal region. If specified by the user, these parameters must be ordered correctly with: \(0 < PeakSize \leq BackgroundInnerSize\) and \(BackgroundInnerSize < BackgroundOuterSize \leq RegionRadius\)
• If UseOnePercentBackgroundCorrection is enabled, then the top 1% of the background events are removed so that there are no intensity spikes near the edges. This is enabled by default.
• AdaptiveQMultiplier can be used with SpecifySize for the radius to vary as a function of the modulus of Q. If the AdaptiveQBackground option is set to True, the background radius also changes so each peak has a different integration radius. Q includes the 2*pi factor.
  • PeakRadius + AdaptiveQMultiplier * |Q|
  • BackgroundOuterRadius + AdaptiveQMultiplier * |Q|
  • BackgroundInnerRadius + AdaptiveQMultiplier * |Q|
• The integrated intensities will be set in the specified OutputWorkspace. If this is different from the input PeaksWorkspace, the input peaks workspace will be copied to the OutputWorkspace before setting the integrated intensities.

Detailed Algorithm Description¶

This algorithm will integrate a list of indexed single-crystal diffraction peaks from a PeaksWorkspace, using events from an ( EventWorkspace ).

Given and input RegionRadius, QLab space is partitioned into a cubic lattice with unit cell of size RegionRadius. This guarantees that no two peaks can occupy the same cell. Events are distributed among the cells according to their QLab Q-vectors. Later, each of the cells containing one peak is inspected for the events it contains, as well as its 27 fist-neighbor cells. The events thus collected are inspected to determine which lie within RegionRadius of the peak Q-vector.

When the lists of events near the peaks have been built, the three principal axes of the set of events near each peak are found, and the standard deviations of the projections of the events on each of the three principal axes are calculated. The principal axes and standard deviations for the events around a peak in the directions of the principal axes are used to determine an ellipsoidal region for the peak and an ellipsoidal shell region for the background. The number of events in the peak ellipsoid and background ellipsoidal shell are counted and used to determine the net integrated intensity of the peak.

The ellipsoidal regions used for the peak and background can be obtained in two ways. First, the user may specify the size of the peak ellipsoid and the inner and outer size of the background ellipsoid. If these are specified, the values will be used for half the length of the major axis of an ellipsoid centered on the peak. The major axis is in the direction of the principal axis for which the standard deviation in that direction is largest. The other two axes for the ellipsoid are in the direction of the other two principal axes and are scaled relative to the major axes in proportion to their standard deviations. For example if the standard deviations in the direction of the other two principal axes are .8 and .7 times the standard deviation in the direction of the major axis, then the ellipse will extend only .8 and .7 times as far in the direction of those axes, as in the direction of the major axis. Overall, the user specified sizes for the PeakSize, BackgroundInnerSize and BackgroundOuterSize are similar to the PeakRadius, BackgroundInnerRadius and BackgrounOuterRadius for the IntegratePeaksMD v2 algorithm. The difference is that the regions used in this algorithm are not spherical, but are ellipsoidal with axis directions obtained from the principal axes of the events near a peak and the ellipsoid shape (relative axis lengths) is determined by the standard deviations in the directions of the principal axes.

Second, if the user does not specify the size of the peak and background ellipsoids, then the three axes of the peak ellipsoid are again set to the principal axes of the set of nearby events but in this case their axis lengths are set to cover a range of plus or minus three standard deviations in the axis directions. In this case, the background ellipsoidal shell is chosen to have the same volume as the peak ellipsoid and it’s inner surface is the outer surface of the peak ellipsoid. The outer surface of the background ellipsoidal shell is an ellipsoidal surface with the same relative axis lengths as the inner surface.

By default, the algorithm does not distinguish satellite peaks from Bragg peaks by using identical integrators for two different type of peaks. However, users can specify SatelliteRegionRadius, SatellitePeakSize, SatelliteBackgroundInnerSize and SatelliteBackgroundOuterSize such that the integrator used for satellite peaks are different from the one used for Bragg Peaks.

This algorithm uses principle component analysis to determine the principle axis for each peak. For the event list (QLab) associated with each peak, the algorithm determines a covariance matrix, and uses that to establish eigenvectors corresponding to the principle axis (all orthogonal). The sizes of each principle axis are used define the region of which events will be counted/integrated from those already associated with each peak.

IntegrateIfOnEdge=False option¶

Edges for each bank or pack of tubes of the instrument are defined by masking the edges in the PeaksWorkspace instrument. e.g. For CORELLI, tubes 1 and 16, and pixels 0 and 255. Q in the lab frame for every peak is calculated, call it C For every point on the edge, the trajectory in reciprocal space is a straight line, going through:

\(\vec{O}=(0,0,0)\)

Calculate a point at a fixed momentum, say k=1. Q in the lab frame:

\(\vec{E}=(-k \cdot \sin(\theta) \cdot \cos(\phi), -k \cdot \sin(\theta) \cdot \sin(\phi), k - k \cdot \cos(\phi))\)

Normalize E to 1:

\(\vec{E}=\vec{E} \cdot (1./\left|\vec{E}\right|)\)

The distance from C to OE is given by:

\(dv=\vec{C}-\vec{E} \cdot (\vec{C} \cdot \vec{E})\)

If:

\(\left|dv\right|<PeakRadius\)

for the integration, one of the detector trajectories on the edge is too close to the peak This method is also applied to all masked pixels. If there are masked pixels trajectories inside an integration volume, the peak must be rejected. If there are masked pixel trajectories inside the background volume, the background events are scaled by estimating the volume of the ellipsoid on the detector.

ShareBackground option¶

With this option enabled, satellite peaks will share the integrated background intensity and volume of its corresponding Bragg peak. The integrated intensity of satellite peaks will still use the radii set with SatelliteRegionRadius and SatelitePeakSize though its background intensity will be borrowed from its Bragg peak.

In cases where a Bragg peak could not be found for a satellite peak, then the background for the satellite peak is determined as normal using the values of SatelliteBackgroundInnerSize and SatelliteBackgroundOuterSize for background subtraction.

Sigma from the background¶

The sigma from the background could be too small because the background contains events from other peaks. In an effort to reduce this, all the background events are sorted and the top 1% are removed. Note that this behaviour is optional and can be enabled if the property UseOnePercentBackgroundCorrection is enabled. It is enabled by default.