\(\renewcommand\AA{\unicode{x212B}}\)
This document explains how to use Mantid to perform reduction of ORNL SANS data. Information about the underlying Mantid algorithms involved can be found in the SANSReduction algorithm documentation. For HFIR reduction specifically, you can also see the HFIRSANSReduction algorithm documentation.
Contents
import mantid
from mantid.simpleapi import *
from reduction_workflow.instruments.sans.hfir_command_interface import *
GPSANS()
SetSampleDetectorDistance(1802.5)
SetWavelength(4.86, 0.13)
NoSolidAngle()
NoNormalization()
SetAbsoluteScale(1)
AzimuthalAverage(n_bins=100, n_subpix=1, log_binning=False)
IQxQy(nbins=100)
SetWedges(number_of_wedges=2, wedge_angle=5, wedge_offset=0)
SetBeamCenter(95.5, 127.5)
NoSensitivityCorrection()
SetTransmission(1, 0)
ThetaDependentTransmission(False)
TransmissionDarkCurrent("HiResSANS_exp5_scan0032_0001.xml")
DataPath("/SNS/users/m2d")
AppendDataFile(["/SNS/users/m2d/scan30test1.xml"])
SaveIq()
Reduce()
The hfir_command_interface import statement gives us access the the various commands we will use to set up the reduction process.
The first important part of the script is to declare which instrument you are using.
This will define the general flow of the reduction process. In this particular case, this is done by calling GPSANS().
The DataPath() command sets the directory where the data file will be found.
Once this has been done, only the name of the data files need to be supplied to the various reduction commands.
The rest of the commands are setting up options for the reduction. Those commands do not need to be typed in any particular order. They only set options and define the reduction process that will be used later when processing each data file. See the list of commands for more details.
The AppendDataFile() command appends a data file to the list of files to be reduced. The reducer can process any number of data files, and the same reduction process will be applied to each of them.
The Reduce() command tell the reducer to start the reduction process. Since this command does the actual execution, it needs to be the last command in the reduction script.
The following is a list of reduction commands to apply corrections to the data and produce \(I(Q)\).
Since each instrument has its own configuration parameters, the first command called is the name of the instrument.
GPSANS()BIOSANS()EQSANS()Options for finding the beam center
SetBeamCenter(x,y)DirectBeamCenter(datafile)Finds the beam center using the direct beam method. The position of the beam center p is given by
\(p(x,y) = \frac{\sum_i I_i \ d_i(x,y)}{\sum_i I_i}\)
where i runs over all pixels within the largest square detector area centered on the initial guess for the beam center position. The initial guess is the center of the detector. \(I_i\) is the detector count for pixel i, and \(d_i(x,y)\) is the pixel coordinates. The calculation above is repeated iteratively by replacing the initial guess with the position found with the previous iteration. The process stops when the difference between the positions found with two consecutive iterations is smaller than 0.25 pixel.
ScatteringBeamCenter(datafile, beam_radius=3.0)beam_radius parameter) of the beam center guess are excluded from the calculation. The direct beam is thus excluded and only the scattered data is used.TotalChargeNormalization(normalize_to_beam=True, beam_file='')beam_file for the beam profile.BeamMonitorNormalization(reference_flux_file)TimeNormalization()MonitorNormalization()NoNormalization()SetAbsoluteScale(factor=1.0)SetDirectBeamAbsoluteScale(direct_beam, beamstop_radius=None, attenuator_trans=1.0, sample_thickness=None, apply_sensitivity=False)Tells the reducer to use the direct beam method to compute the absolute scale factor. The direct_beam parameter is a valid file path to the direct beam data file. attenuator_trans is the attenuator transmission. The sample_thickness should be given in cm. If apply_sensitivity=True, the sensitivity correction will be applied to the direct beam data before the absolute scale factor is computed.
The absolute cross-section in 1/cm is computed after all corrections including the transmission correction have been applied to the sample data. It is given by:
\(d\Sigma/d\Omega = \frac{I(Q)}{KD}\)
where D is the sample thickness in cm and K is given by
\(K=N \ \Delta\Omega\)
where N is the total empty beam detector counts per monitor count divided by the attenuation factor at the used wavelength, and \(\Delta\Omega\) is the square of the ratio of the pixel size to the sample-detector distance.
NoDarkCurrent()DarkCurrent(datafile)Specifies which data file to use for the dark current. The dark current is subtracted pixel by pixel by normalizing the dark current data by counting time, as follows:
\(I'(x,y) = I_{data}(x,y) - \frac{T_{data}}{T_{dc}} \ I_{dc}(x,y)\)
where the T-values are the counting times for the data set and the dark current (dc).
Mask(nx_low=0, nx_high=0, ny_low=0, ny_high=0, component_name=None)MaskRectangle(x_min, x_max, y_min, y_max)MaskDetectors(det_list)MaskDetectorSide(side_to_mask=None)MaskComponent(component_name)SensitivityCorrection(flood_data, min_sensitivity=0.5, max_sensitivity=1.5, dark_current=None, use_sample_dc=False)The relative detector efficiency is computed the following way
\(S(x,y) = \frac{I_{flood}(x,y)}{1/N_{pixels} \ \sum_{i,j} \ I_{flood}(i,j)}\)
where \(I_{flood}(x,y)\) is the pixel count of the flood data in pixel (x,y). If a minimum and/or maximum sensitivity is given, the pixels having an efficiency outside the given limits are masked and the efficiency is recomputed without using those pixels. The sample data is then corrected by dividing the intensity in each pixels by the efficiency S
\(I'_{sample}(x,y) = \frac{I_{sample}(x,y)}{S(x,y)}\)
The pixels found to have an efficiency outside the given limits are also masked in the sample data so that they don’t enter any subsequent calculations.
If use_sample_dc is set to True, the dark current data that was chosen to be subtracted from the sample data will also be subtracted from the flood data. The subtraction is done before the sensitivity is calculated. Alternatively, a different file can be selected by specifying the dark_current parameter.
If the user chose to use the solid angle correction for the reduction process, that correction will be applied to the flood data before the sensitivity is calculated.
Note: The solid angle correction is either not applied at all, or applied to both the flood data to calculate the sensitivity correction and applied to the sample data as part of the reduction process.
NoSensitivityCorrection()SetSensitivityBeamCenter(x,y)SensitivityDirectBeamCenter(datafile)SensitivityScatteringBeamCenter(datafile, beam_radius=3.0)SolidAngle(detector_tubes=False, detector_wing=False)Tells the reducer to apply the solid angle correction. The solid angle correction is applied as follows:
\(I'(x,y) = \frac{I(x,y)}{\cos^3(2\theta)}\)
\(\sigma_{i'(x,y)} = \frac{\sigma_{I(x,y)}}{|\cos^3(2\theta)|}\)
If detector_tubes is selected, the correction is calculated according to a tube geometry. The cosine term above then becomes:
\(\cos^3(2\theta) \rightarrow \cos^2(2\theta) \cos(\alpha)\)
where \(\alpha\): is the angle between the sample-to-pixel vector and its projection on the X-Z plane.
detector_wing=True is used only for BioSANS wing detector.
NoSolidAngle()SetTransmission(trans, error)DirectBeamTransmissionsample_file, empty_file, beam_radius=3.0, theta_dependent=True, use_sample_dc=True)Tells the reducer to use the direct beam method to calculate the sample transmission. The transmission is calculated as follows:
\(T=\frac{\sum_{i; \ d(i,j)<R} \sum_j{\frac{I_{sample}(i,j)}{T_{sample}}}}{\sum_{i; \ d(i,j)<R} \sum_j{\frac{I_{beam}(i,j)}{T_{beam}}}}\)
where \(I_{sample}\) and \(I_{beam}\) are the pixel counts for the sample data set and the direct beam data set, respectively. The sums for each data set runs only over the pixels within a distance R=beam_radium of the beam center. \(T_{sample}\) and \(T_{sample}\) are the counting times for each of the two data sets. If the user chose to normalize the data using the beam monitor when setting up the reduction process, the beam monitor will be used to normalize the sample and direct beam data sets instead of the timer.
If use_sample_dc is set to True, the dark current data that was chosen to be subtracted from the sample data will also be subtracted from the flood data.
Once the transmission is calculated, it is applied to the input data set in the same way as described for SetTransmission().
BeamSpreaderTransmission(sample_spreader, direct_spreader, sample_scattering, direct_scattering, spreader_transmission=1.0, spreader_transmission_err=0.0, theta_dependent=True)Tells the reducer to use the beam spreader (“glassy carbon”) method to calculate the sample transmission. The transmission is calculated as follows:
\(T=\frac{N_{gc, sample}/T_{gc, sample} - T_{gc}N_{sample}/T_{sample}}{N_{gc, empty}/T_{gc, empty} - T_{gc}N_{empty}/T_{empty}}\)
where \(N_{gc, sample}\) and \(N_{gc, empty}\) are the sums of all pixel counts for the sample and direct beam data sets with glass carbon, and \(N_{sample}\) and \(N_{empty}\) are the sums of all the pixel counts for the sample and direct beam without glassy carbon. The T values are the corresponding counting times. If the user chose to normalize the data using the beam monitor when setting up the reduction process, the beam monitor will be used to normalize all data sets instead of the timer.
If the user chose to use a dark current data set when starting the reduction process, that dark current data will be subtracted from all data sets before the transmission is calculated.
Once the transmission is calculated, it is applied to the input data set in the same way as described for SetTransmission().
NoTransmission()TransmissionDarkCurrent(dark_current)ThetaDependentTransmission(theta_dependence=True)SetTransmissionBeamCenter(x, y)TransmissionDirectBeamCenter(datafile)Background(datafile)NoBackground()NoBckTransmission()SetBckTransmission(trans, error, theta_dependent=True)BckDirectBeamTransmission(sample_file, empty_file, beam_radius=3.0, theta_dependent=True)DirectBeamTransmission, this command sets the options to measure the background transmission.BckBeamSpreaderTransmission(sample_spreader, direct_spreader, sample_scattering, direct_scattering, spreader_transmission=1.0, spreader_transmission_err=0.0, theta_dependent=True)BeamSpreaderTransmission, this command sets the options to measure the background transmission.BckTransmissionDarkCurrent(dark_current)TransmissionDarkCurrent, this command sets the dark current for the background.BckThetaDependentTransmission(theta_dependence=True)ThetaDependentTransmission, this command sets the theta-dependence option of the transmission correction for the background.SetBckTransmissionBeamCenter(x, y)SetTransmissionBeamCenter, sets the beam center position to be used when applying the transmission correction. The beam center position of the background data is otherwise used.BckTransmissionDirectBeamCenter(datafile)TransmissionDirectBeamCenter, specifies a direct beam data file to use to determine a beam center to use when applying the transmission correction. The beam center position of the background data is otherwise used.AzimuthalAverage(binning=None, suffix="_Iq", error_weighting=False, n_bins=100, n_subpix=1, log_binning=False, align_log_with_decades=False)Sets the options for azimuthal averaging. The binning parameter sets the binning of the output I(q) distribution in the following format: \(Q_{min}, \Delta Q, Q_{max}\) (the binning will be found automatically if the binning parameter is not supplied). When letting the binning be calculated automatically, setting log_binning=True will tell the reducer to find the best log binning. Setting align_log_with_decades=True will ensure that q points fall on decades. The suffix parameter sets the suffix appended to the I(q) workspace name. If error_weighting is set to True, the pixel counts will be weighted by a function of the error when computing I(q) (see below).
The binning of the output I(Q) distribution is defined by the user. It runs from \(Q_{min}\) to \(Q_{max}\) in steps of \(\Delta Q\). Each pixel is divided in \(N_{sub} \times N_{sub}\) sub-pixels. Each sub-pixel is assigned a count equal to of the original pixel count.
The intensity I(Q) in each Q bin is given by
\(I(Q_j) = \frac{1}{\sum_i \ w} \ \sum_i \ wI_i\)
where the sum runs over all sub-pixels i such that \(Q_j < q_i < Q_{j+1}\), where \(q_i\) is the q-value of the given sub-pixel:
\(q_i = \frac{4\pi \ \sin(\theta)}{\lambda}\)
The w factor is a weight that is set to 1 by default. Alternatively, pixels can be weighted as a function of their error by setting \(w=1/\Delta I_i\).
The resolution in Q is computed using Mildner-Carpenter.
IQxQy(nbins=100, log_binning=False)NoIQxQy()SaveIq(output_dir)NoSaveIq()Wedge calculation is done as part of the azimuthal averaging algorithm. The image below shows how the wedges are defined. A wedge includes both the forward and backward direction relative to the beam center. Any number of wedges can be used. They will be uniformly distributed around \(2\pi\). Each wedge is computed independently, so overlapping wedges are possible. As shown on the figure below, the angular offset is definited with respect to the x-axis.
SetWedges(number_of_wedges=2, wedge_angle=30.0, wedge_offset=0.0)Specifies I(q) wedges to compute.
number_of_wedges: number of wedges to calculatewedge_angle: opening angle of each wedge, in degreeswedge_offset: angular offset relative to the x-axis, defining the first wedge.Data stitching can be done using the SANS reduction UI, or by calling the underlying command directly. The stitching process lets you pick an overlap region that will be used to scale data sets to each other. For any number of input data sets, the data sets are scaled to the first set in the input series. The second set is scaled to the first set, then the third set is scaled to the modified second set. The process continues in pairs until all the data sets are rescaled.
In the process of scaling two data sets, all the points of the lower Q set with a Q value lower than the higher bound of the overlap region are kept. All the points of the higher Q set with a Q value higher than the lower bound of the overlap region are kept (see image). All data points in the overlap region are kept.
Stitch(data_list=[], q_min=None, q_max=None, output_workspace=None, scale=None, save_output=False)Stitches a set of SANS data sets
data_list: List of workspaces to stitch.q_min: Minimum Q-value of the overlap between two consecutive data sets. The q_min argument must be an array when stitching more than two data sets. The length of the array should be 1 less than the number of data sets.q_max: Maximum Q-value of the overlap between two consecutive data sets (must be an array for more than two data sets). The q_max argument must be an array when stitching more than two data sets. The length of the array should be 1 less than the number of data sets.output_workspace: Name of the output workspace containing the stitched data.scale: Scaling factor. The scaling factor should either be a single number or a list of length equal to the number of data sets. The former will scale everything by the given factor, while the latter will assign the given scaling factors to the data sets.save_output: If true, the output will be saved in the current working directory.DataPath(path)Reduce()AppendDataFile(datafile, workspace=None)SetSampleDetectorOffset(distance)SetSampleDetectorDistance(distance)SetWavelength(wavelength, spread)ResetWavelength()DivideByThickness(thickness=1.0)PerformFlightPathCorrection(do_correction=True)SetTOFTailsCutoff(low_cut=0.0, high_cut=0.0)UseConfigTOFTailsCutoff(use_config=True)SkipTOFCorrection(skip=True)UseConfigMask(use_config=True)SetWavelengthStep(step=0.1)UseConfig(use_config=True)CombineTransmissionFits(combine_frames=True)BckCombineTransmissionFits(combine_frames=True)CombineTransmissionFits, but for the background.Resolution(sample_aperture_diameter=10.0)LoadNexusInstrumentXML(True)LoadNexusInstrumentXML(False) to make sure the local IDF is read.Category: Concepts