.. _Reduction for ORNL SANS: .. role:: xml(literal) :class: highlight Reduction for ORNL SANS ======================= 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 :ref:`SANSReduction ` algorithm documentation. For HFIR reduction specifically, you can also see the :ref:`HFIRSANSReduction ` algorithm documentation. Contents - `Reduction script`_ - `Reduction commands`_ - `Instrument selection`_ - `Beam center`_ - `Normalization options`_ - `Absolute normalization`_ - `Dark current subtraction`_ - `Pixel masking`_ - `Sensitivity correction`_ - `Solid angle correction`_ - `Transmission correction`_ - `Background subtraction`_ - `I(Q) calculation`_ - `Wedge calculation`_ - `Data stitching`_ - `General commands`_ .. _`Reduction script`: Reduction script ---------------- .. code-block:: python 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 to 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. .. _`Reduction commands`: Reduction commands ------------------ The following is a list of reduction commands to apply corrections to the data and produce :math:`I(Q)`. .. _`Instrument selection`: Instrument Selection ^^^^^^^^^^^^^^^^^^^^ Since each instrument has its own configuration parameters, the first command called is the name of the instrument. ``GPSANS()`` Sets up the GPSANS reduction options. ``BIOSANS()`` Sets up the BIOSANS reduction options. ``EQSANS()`` Sets up the EQSANS reduction options. .. _`Beam center`: Beam Center ^^^^^^^^^^^ Options for finding the beam center ``SetBeamCenter(x,y)`` Sets the beam center location to be used, in pixel coordinates. ``DirectBeamCenter(datafile)`` Finds the beam center using the direct beam method. The position of the beam center p is given by :math:`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. :math:`I_i` is the detector count for pixel ``i``, and :math:`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)`` Finds the beam center using the scattered beam method. The process is identical to the direct beam method, with the only difference being that the pixels within a distance R (the ``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='')`` [**EQSANS only**] Specifies that we want to normalize by the total proton charge, using the specified ``beam_file`` for the beam profile. ``BeamMonitorNormalization(reference_flux_file)`` [**EQSANS only**] Specifies that we want to normalize by the beam monitor, using the specified reference flux file. .. _`Normalization options`: Normalization options ^^^^^^^^^^^^^^^^^^^^^ ``TimeNormalization()`` Tells the reducer to normalize the data to counting time. ``MonitorNormalization()`` Tells the reducer to normalize the data to the beam monitor. ``NoNormalization()`` Tells the reducer not to normalize the data. .. _`Absolute normalization`: Absolute Normalization ^^^^^^^^^^^^^^^^^^^^^^ ``SetAbsoluteScale(factor=1.0)`` Sets a multiplicative scale factor to obtain I(Q) in absolute scale. ``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: :math:`d\Sigma/d\Omega = \frac{I(Q)}{KD}` where *D* is the sample thickness in *cm* and *K* is given by :math:`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 :math:`\Delta\Omega` is the square of the ratio of the pixel size to the sample-detector distance. .. _`Dark current subtraction`: Dark current subtraction ^^^^^^^^^^^^^^^^^^^^^^^^ ``NoDarkCurrent()`` Lets the reducer know that no dark current should be subtracted. ``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: :math:`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). .. _`Pixel masking`: Pixel masking ^^^^^^^^^^^^^ ``Mask(nx_low=0, nx_high=0, ny_low=0, ny_high=0, component_name=None)`` A band of pixels on each side of the detector is masked according to the input parameters. By default this is done only for the main detector (See IDF tag 'detector-name'). For Biosans one can specify 'component_name="wing_detector"'. ``MaskRectangle(x_min, x_max, y_min, y_max)`` Masks a rectangular region on the detector defined by the given pixel numbers. ``MaskDetectors(det_list)`` Masks the given detector IDs. ``MaskDetectorSide(side_to_mask=None)`` Masks a detector plane. Choices are 'Front', 'Back', and 'None'. ``MaskComponent(component_name)`` Masks the given component_name. See the instrument IDF for the correct component name. Useful for BIOSANS to mask the 'wing_detector'. .. _`Sensitivity correction`: Sensitivity correction ^^^^^^^^^^^^^^^^^^^^^^ ``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 :math:`S(x,y) = \frac{I_{flood}(x,y)}{1/N_{pixels} \ \sum_{i,j} \ I_{flood}(i,j)}` where :math:`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 :math:`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()`` Tells the reducer not to correct for detector sensitivity. ``SetSensitivityBeamCenter(x,y)`` Sets the beam center for the flood data (may be different from the sample data). ``SensitivityDirectBeamCenter(datafile)`` Tells the reducer to use the direct beam center finding method for the flood data (see DirectBeamCenter for details). ``SensitivityScatteringBeamCenter(datafile, beam_radius=3.0)`` Tells the reducer to use the scattering beam center finding method for the flood data (see ScatteringBeamCenter for details). .. _`Solid angle correction`: Solid angle correction ^^^^^^^^^^^^^^^^^^^^^^ ``SolidAngle(detector_tubes=False, detector_wing=False)`` Tells the reducer to apply the solid angle correction. The solid angle correction is applied as follows: :math:`I'(x,y) = \frac{I(x,y)}{\cos^3(2\theta)}` :math:`\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: :math:`\cos^3(2\theta) \rightarrow \cos^2(2\theta) \cos(\alpha)` where :math:`\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. .. figure:: /images/sans_solid_angle_correction.png :figwidth: 10 cm :align: right :alt: Definition of angles for tube solid angle correction. ``NoSolidAngle()`` Tells the reducer not to apply the solid angle correction. .. _`Transmission correction`: Transmission correction ^^^^^^^^^^^^^^^^^^^^^^^ ``SetTransmission(trans, error)`` [**HFIR only**] Sets the sample transmission. For each detector pixel, the transmission correction is applied as follows: .. math:: I'(x,y) = \frac{I(x,y)}{T^{[1+\sec(2\theta)]/2}} \sigma_{I'(x,y)} = \left[ \left[ \frac{\sigma_I}{T^{[1+\sec(2\theta)]/2}} \right]^2 + \left[ \frac{I(x,y)\sigma_T\left( \frac{1+\sec(2\theta)}{2}\right)}{T^{[\sec(2\theta)-1]/2}} \right]^2 \right]^{1/2} ``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: :math:`T=\frac{\sum_{i; \ d(i,j)