4.0

ReflectometryILLPreprocess v1

../_images/ReflectometryILLPreprocess-v1_dlg.png

ReflectometryILLPreprocess dialog.

Summary

Loads, merges, normalizes and subtracts background from ILL reflectometry data.

Properties

Name Direction Type Default Description
Run Input list of str lists   A list of input run numbers/files. Allowed values: [‘nxs’]
InputWorkspace Input MatrixWorkspace   An input workspace (units TOF) if no Run is specified.
OutputWorkspace Output MatrixWorkspace Mandatory The preprocessed output workspace (unit wavelength), single histogram.
TwoTheta Input number Optional A user-defined scattering angle 2 theta (unit degrees).
LinePosition Input number Optional A workspace index corresponding to the beam centre between 0.0 and 255.0.
DirectLineWorkspace Input MatrixWorkspace   A pre-processed direct beam workspace.
SubalgorithmLogging Input string Logging OFF Enable or disable child algorithm logging. Allowed values: [‘Logging OFF’, ‘Logging ON’]
Cleanup Input string Cleanup ON Enable or disable intermediate workspace cleanup. Allowed values: [‘Cleanup ON’, ‘Cleanup OFF’]
WaterWorkspace Input MatrixWorkspace   A (water) calibration workspace (unit TOF).
SlitNormalisation Input string Slit Normalisation OFF Enable or disable slit normalisation. Allowed values: [‘Slit Normalisation OFF’, ‘Slit Normalisation ON’]
FluxNormalisation Input string Normalise To Time Neutron flux normalisation method. Allowed values: [‘Normalise To Time’, ‘Normalise To Monitor’, ‘Normalisation OFF’]
ForegroundHalfWidth Input int list   Number of foreground pixels at lower and higher angles from the centre pixel.
FlatBackground Input string Background Constant Fit Flat background calculation method for background subtraction. Allowed values: [‘Background Constant Fit’, ‘Background Linear Fit’, ‘Background OFF’]
LowAngleBkgOffset Input number 7 Distance of flat background region towards smaller detector angles from the foreground centre, in pixels.
LowAngleBkgWidth Input number 5 Width of flat background region towards smaller detector angles from the foreground centre, in pixels.
HighAngleBkgOffset Input number 7 Distance of flat background region towards larger detector angles from the foreground centre, in pixels.
HighAngleBkgWidth Input number 5 Width of flat background region towards larger detector angles from the foreground centre, in pixels.
FitStartWorkspaceIndex Input number 0 Start workspace index used for peak fitting.
FitEndWorkspaceIndex Input number 255 Last workspace index used for peak fitting.
FitRangeLower Input number Optional Minimum x value (unit Angstrom) used for peak fitting.
FitRangeUpper Input number Optional Maximum x value (unit Angstrom) used for peak fitting.

Description

This algorithm is the first step in the ILL reflectometry reduction workflow. It:

  1. loads data from disk by using LoadAndMerge (LoadILLReflectometry, MergeRuns)
  2. merges the numors
  3. determines the peak position by using FindReflectometryLines
  4. moves the detector (of name detector) by using SpecularReflectionPositionCorrect (optional, if DirectLineWorkspace is given)
  5. normalizes to a (water) reference (optional)
  6. normalizes to slit sizes (optional)
  7. normalizes to experiment time or monitor counts (optional)
  8. subtracts time-independent background (optional)
  9. converts to wavelength

The algorithm can be thought as an ‘advanced loader’, and should be used to load both direct beam and reflected beam measurements.

The OutputWorkspace can be further fed to ReflectometryILLSumForeground.

The algorithm adds the following sample log entries to the OutputWorkspace:

  • reduction.foreground.centre_workspace_index
  • reduction.foreground.last_workspace_index
  • reduction.foreground.first_workspace_index
  • reduction.line_position : the peak position (workspace index) used to define the 2\theta angles (detector positions)

The workflow diagram below gives an overview of the algorithm:

../_images/ReflectometryILLPreprocess-v1_wkflw.png

Detector angles

A fitting of the present peak position takes place in order to determine the detector angles. For preventing fitting of the present peak position, the property LinePosition allows to provide a peak position. A use case is to enter a direct peak position, which can be obtained from the direct beam workspaces sample logs, when the Run is a reflected beam.

Alternatively, the properties TwoTheta and the sample log reduction.line_position affect the pixel 2\theta angle.

Foreground and backgrounds

Foreground is a set of pixels intensities of which will be summed in ReflectometryILLSumForeground. However, foreground needs to be defined already in this algorithm as the information is needed for the background pixels. The foreground pixel information is stored in the sample logs of OutputWorkspace under the entries starting with foreground..

Background, on the other hand, is a set of pixels which are be used for fitting a constant or linear background by CalculatePolynomialBackground.

The foreground pixels are defined by the foreground centre and ForegroundHalfWidth property. In normal use cases, the foreground center (workspace index) is taken from the fitting in LoadILLReflectometry. This can be overridden by giving the pixel as BeamCentre. Fractional values are rounded to nearest integer. The full process of deciding the foreground centre is as follows:

  • If Run is given then data is loaded using LoadILLReflectometry:
  • If InputWorkspace is given:
    • If sample log entry reduction.line_position is given, round it to nearest integer and use as the foreground centre.
    • If LinePosition is given, round the value to nearest integer and use as the foreground centre.
    • Otherwise fit the beam centre using similar method to LoadILLReflectometry and use the rounded result as the foreground centre.

ForegroundHalfWidth is a list of one or two values. If a single value is given, then this number of pixels on both sides of the centre pixel are included in the foreground. For example, ForegroundHalfWidth=[3] means three pixel on both sides are included, making the foreground seven pixels wide in total. ForegroundHalfWidth=[0] means that only the centre pixel is included. When two values are given, then the foreground is asymmetric around the centre. For instance, ForegroundHalfWidth[2,5] indicates that two pixel at lower \theta and five pixels at higher \theta are included in the foreground.

LowAngleBkgWidth and HighAngleBkgWidth define the number of the background fitting pixels at low and high \theta. Either one or both widths can be defined. The distance between the background pixels and the foreground can in turn be given by LowAngleBkgOffset and HighAngleBkgOffset.

The following figure exemplifies the foreground and background for the D17 instrument at ILL. Note, that in this particular case, the pixel indices increase with decreasing \theta.

(Source code, png, hires.png, pdf)

../_images/ReflectometryILLPreprocess-v1-1.png

InputWorkspace

The InputWorkspace and DirectBeamWorkspace can be used instead of Run if the data is already loaded into Mantid for example using LoadILLReflectometry. This option exists mainly for testing purposes.

Usage

Example - Load direct and reflected beams

from directtools import SampleLogs

# Use same foreground and background settings for direct and reflected
# beams.
# Python dictionaries can be passed to algorithms as 'keyword arguments'.
settings = {
    'ForegroundHalfWidth':[5],
    'LowAngleBkgOffset': 10,
    'LowAngleBkgWidth': 20,
    'HighAngleBkgOffset': 10,
    'HighAngleBkgWidth': 50
}

direct = ReflectometryILLPreprocess(
    Run='ILL/D17/317369.nxs',
    **settings
)

reflected = ReflectometryILLPreprocess(
    Run='ILL/D17/317370.nxs',
    DirectLineWorkspace=direct,
    **settings
)

# Check foreground settings from sample logs
logs = SampleLogs(reflected)
print('Reflected line position: {}'.format(logs.reduction.foreground.centre_workspace_index))
# Half widths + centre pixel
width = logs.reduction.foreground.last_workspace_index - logs.reduction.foreground.first_workspace_index + 1
print('Foreground width: {}'.format(width))

Output:

Reflected line position: 202
Foreground width: 11

Categories: Algorithm Index | ILL\Reflectometry | Workflow\Reflectometry

Source

Python: ReflectometryILLPreprocess.py (last modified: 2019-02-21)