EQ-SANS Data Reduction With drtsans

Quick Reference for the data reduction parameters

Editors: Changwoo Do, Gergely Nagy, William Heller

Date: 07/16/2020

Introduction

The various parameters required by drtsans are listed below with a brief description of their meaning, the acceptable values, and appropriate format for the information. An example is shown here.

{
  "schemaStamp": "2020-05-26T22:28:16.336908",
  "instrumentName": "EQSANS",
  "iptsNumber": "24184",
  "sample": {
    "runNumber": "111524",
    "thickness": 1,
    "transmission": {
      "runNumber": "111522",
      "value": ""
    }
  },
  "background": {
    "runNumber": "111523",
    "transmission": {
      "runNumber": "111521",
      "value": ""
    }
  },
  "emptyTransmission": {
    "runNumber": "111520",
    "value": null
  },
  "beamCenter": {
    "runNumber": "111520"
  },
  "outputFileName": "EQSANS_111524",
  "configuration": {
    "outputDir": "/SNS/EQSANS/shared/codereview/acceptance/wt3_final/ipts24184/",
    "useTimeSlice": false,
    "timeSliceInterval": 300,
    "useLogSlice": false,
    "logSliceName": null,
    "logSliceInterval": 10,
    "cutTOFmin": "500",
    "cutTOFmax": "1500",
    "wavelengthStep": "0.1",
    "wavelengthStepType": "constant Delta lambda",
    "sampleOffset": "314.5",
    "useDetectorOffset": true,
    "detectorOffset": 80.0,
    "sampleApertureSize": "10",
    "sourceApertureDiameter": null,
    "usePixelCalibration": null,
    "maskFileName": "/SNS/EQSANS/shared/codereview/acceptance/wt3_final/mask_bs60_morebanks2.nxs",
    "useDefaultMask": true,
    "defaultMask": null,
    "useMaskBackTubes": false,
    "darkFileName": "/SNS/EQSANS/shared/NeXusFiles/EQSANS/2019B_mp/EQSANS_108764.nxs.h5",
    "normalization": "Total charge",
    "fluxMonitorRatioFile": "/SNS/EQSANS/IPTS-24769/shared/EQSANS_110943.out",
    "beamFluxFileName": "/SNS/EQSANS/shared/instrument_configuration/bl6_flux_at_sample",
    "sensitivityFileName": "/SNS/EQSANS/shared/NeXusFiles/EQSANS/2019B_mp/Sensitivity_patched_thinPMMA_4m_108772.nxs",
    "useSolidAngleCorrection": true,
    "useThetaDepTransCorrection": true,
    "mmRadiusForTransmission": "25",
    "absoluteScaleMethod": "standard",
    "StandardAbsoluteScale": "5.0719320777245",
    "numQxQyBins": "80",
    "1DQbinType": "scalar",
    "QbinType": "log",
    "numQBins": "100",
    "LogQBinsPerDecade": null,
    "useLogQBinsDecadeCenter": false,
    "useLogQBinsEvenDecade": false,
    "WedgeMinAngles": "-30, 60",
    "WedgeMaxAngles": "30, 120",
    "autoWedgeQmin": null,
    "autoWedgeQmax": null,
    "autoWedgeQdelta": null,
    "autoWedgeAzimuthalDelta": null,
    "autoWedgePeakWidth": null,
    "autoWedgeBackgroundWidth": null,
    "autoWedgeSignalToNoiseMin": 2.0,
    "AnnularAngleBin": 5.0,
    "Qmin": null,
    "Qmax": null,
    "useErrorWeighting": false,
    "smearingPixelSizeX": null,
    "smearingPixelSizeY": null,
    "useSubpixels": null,
    "subpixelsX": null,
    "subpixelsY": null,
    "useSliceIDxAsSuffix": true
  },
  "dataDirectories": "/SNS/EQSANS/shared/codereview/acceptance/wt3_final/ipts24184/"
}

Parameter Descriptions

Note that all key:value pairs use quotes around both the key and value unless the value is null or a mathematical constant. Also note that the file has a hierarchical structure, where {} are used to denote groupings. The descriptions of the parameters below reflect the structure of the hierarchy.

"schemaStamp": "2020-05-26T22:28:16.336908" : This particular parameter is autogenerated by the scripting method for reducing data and when using MantidWorkbench. It should not be changed, even when hand-modifying the contents of the configuration file.

"instrumentName": "EQSANS" : The instrument name is used by drtsans to know how to use some of the specified parameters. It must be consistent with the instrument used for the data collection (i.e. do not try to reduce data from EQ-SANS if this parameter is set to "BIOSANS"). Note that there is no dash in the name of the instrument in the drtsans parameter file.

"iptsNumber": "24184" : The proposal number for the experiment allows drtsans to quickly find the data to be reduced, rather than using tools to find the data based solely on the run number. It can be left blank (i.e. "").

"sample": : This is the first parameter that contains a set of parameters grouped using {}. The various parameters in the group follow.

a. "runNumber": "111524" : This is the run number for the sample scattering to be reduced. It can be found via OnCat or using the catalog in MantidWorkbench. It is possible to specify a set of scattering runs for a single sample that are to be summed together into a single data set for reduction. To do so, use the following format, which uses a single pair of quotes to enclose the list: "runNumber":{"XXXXXX, YYYYYY"}

b. "thickness": 1 : This parameter specifies the sample thickness in millimeters. Note that the value is not enclosed in quotes.

c. "transmission": : This is the start of another level of the hierarchical structure. Of the two key:value pairs in this grouping, only one can have an actual value: either the run number or the value of the transmission to use for the reduction. One rarely specifies a simple value for the transmission for EQ-SANS data because the transmission is wavelength-dependent.

"runNumber": "111522" : This is the run number of the transmission for the sample. There can only be a single run number specified here.
"value": "" : This would be a numerical value for the transmission to use for the reduction, which would normally only be done for quick qualitative checks if the data needs to be viewed prior to the completion of the transmission measurement for a sample. Note that the value must be enclosed in quotes ("").

"background": : The set of parameters that follow specify information required to identify the background to use for the reduction. It is possible to reduce data without a background by leaving the run numbers in this set of parameters empty (i.e. "").

a. "runNumber": "111523", : The run number of the background data to subtract from the sample scattering.

b. "transmission": : The following set of parameters are used to specify either the run number for the background's transmission measurement or to specify a value for the transmission of the background.

"runNumber": "111521" : The run number for the background's transmission measurement. If no background is specified, then this run number should not be specified (i.e. set to "").
"value": "" : This would be a numerical value for the transmission to use for the reduction, which would normally only be done for quick qualitative checks if the data needs to be viewed prior to the completion of the transmission measurement for a sample. Note that the value must be enclosed in quotes ("").

"emptyTransmission": : This grouping of parameters is used to specify the reference measurement, or value, used to calculate the transmission from the other specified measurements or values. If the transmissions are specified as values, the value specified here should be "1.0".

a. "runNumber": "111520" : The run number for the background's transmission measurement.

b. "value": null : A value can be specified for the reference transmission. If used, it should be "1.0", if not specify it as null, as shown above.

"beamCenter": : The beam center is specified by providing a run number for an empty beam or a transmission measurement to calculate the beam center from.

a. "runNumber": "111520" : This is the run number of an empty beam or a transmission measurement. It cannot be left blank.

"outputFileName": "EQSANS_111524" : This is the base used to construct all of the file names that result from the data reduction process. In this example, all of the files will be named "EQSANS_111524*.*". The filename can be any valid string that is acceptable for filenames for a unix operating system.

"configuration": : A large number of parameters are specified within this hierarchical grouping, most of which directly impact the reduction process and results produced. Many of these parameters will be provided by your local contact and should not be changed without discussing the reasons for the change with him or her. When using the scripting or MantidWorkbench methods for data reduction, some of these parameters may not be presented to you. If they are not presented to you in either the scripts that your local contact helps set up for you or in the tool in MantidWorkbench, then you do not need to provide them directly.

a. "outputDir":"/SNS/EQSANS/shared/codereview/acceptance/wt3_final/ipts24184/" : The directory to write the data reduction result to is listed here. Normally, it would be the shared directory for the particular proposal, which allows other team members and the local contact to view the results. However, it is also possible to specify a location in a user's home directory. It is left to the discretion of the user.

b. "useTimeSlice": false : If the user wishes to parse the event stream contained in the run specified in the "sample:" parameter set, then set this value to true. If this value is true, then the parameter **"useLogSlice"*, below, must be false.

c. "timeSliceInterval": 300 : This is the interval in seconds to use for the time slicing of the event stream. The event stream will be cut into as many consecutive portions of the event stream as exist in the file, with a final bin that contains as much time as remains in the stream. In this case, the various slices are for the following intervals: 0 ≤ t < 300 seconds, 300 ≤ t < 600 seconds, etc. Note that the value is not contained in quotation marks.

d. "useLogSlice": false, : It is possible to divide an event stream into bins that derive from another parameter that is saved by EPICS in the NeXus file, such as temperature, pressure, magnetic field, or even a motor that continuously moves during data collection. If a user wishes to do so, set the value to true. Note that useLogSlice and useTimeSlice cannot both be true. Discuss the use of log slicing with your local contact.

e. "logSliceName": null : This is the name of the instrument log to use for log slicing. If useLogSlice is true, change this to the name of the EPICS parameter that you wish to employ. Discuss the use of log slicing with your local contact.

f. "logSliceInterval": 10 : This parameter sets the interval of the instrument log specified in logSliceName to use. It must be in the units of the device, be it degrees, millimeters, Celcius, etc. Discuss the use of log slicing with your local contact. Note that the value is not enclosed in quotation marks.

g. "cutTOFmin": "500" : This is an expert parameter, specified in microseconds, that makes it possible to discard neutron events that arrive between the start of the 30 or 60 Hz time window at the plane of the detector from the data reduction. This is normally set by the local contact or instrument team in the default configuration parameter sets. If you would like more information, please consult your local contact. Note that the value is enclosed in quotation marks.

h. "cutTOFmax": "1500" : This is an expert parameter, specified in microseconds, that makes it possible to discard neutron events that arrive within this number of microseconds of the end of the 30 or 60 Hz time window at the plane of the detector from the data reduction. This is normally set by the local contact or instrument team in the default configuration parameter sets. If you would like more information, please consult your local contact. Note that the value is enclosed in quotation marks.

i. "wavelengthStep": "0.1" : During data reduction, the time-of-flight of the events are converted to wavelength. Neutrons are then binned into 2D patterns as a function of wavelength. The width of the wavelength bins in Å is specified by this parameter. Note that the value is enclosed in quotation marks.

j. "wavelengthStepType": "constant Delta lambda" : This particular parameter is not actually used. Do not change the value.

k. "sampleOffset": "314.5" : This parameter specifies the distance, in mm, that the actual sample position differs from the central axis of the large sample environment flange that can be seen on the ceiling of the downstairs sample environment enclosure of EQ-SANS. A positive number means that the sample position is offset from this axis in the direction of the detector, while a negative number means that it is offset towards the SNS target. Your local contact has either determined this number for the sample environment that you are using for your experiment, or they will work with you to determine the correct value. Note that this value is contained in quotation marks.

l. "useDetectorOffset": true : This parameter is an expert parameter and should not be changed without consulting your local contact. If you have any questions, ask your local contact.

m. "detectorOffset": 80.0 : This parameter is an expert parameter and should not be changed without consulting your local contact. If you have any questions, ask your local contact. Note that this value is not enclosed in quotation marks.

n. "sampleApertureSize": "10" : This parameter specifies the diameter of the sample aperture used in millimeters. While it is possible to specify the diameter of this aperture during data acquisition, specifying a different value here allows you to over-write the incorrect value saved in the data files. The sampleApertureSize impacts the calculation of the resolution information for the instrument (i.e. the uncertainty in Q), which is required to accurately analyze your data. Note that the value is enclosed in quotation marks.

o. "sourceApertureDiameter": null : This can be used to specify the diameter of the source aperture in millimeters used for a measurement. Normally, this parameter is actually taken from the positions of the motors of the three fixed slit wheels of the instrument. If you feel that you need to change this value, which you would specify as a number enclosed in quotation marks, consult your instrument scientist.

p. "usePixelCalibration": null : At present, this is an unused parameter for reducing data on EQ-SANS. It is not recommended that a user changes the value of this parameter.

q. "maskFileName":"/SNS/EQSANS/shared/codereview/acceptance/wt3_final/mask_bs60_morebanks2.nxs" : This is the name of a hand-drawn mask. Several default options are normally available during any given run cycle of the SNS, but masks may also be drawn for each experiment, such as when a non-standard sample environment is employed. Speak to your local contact about what mask to use or if a new one should be prepared.

r. "useDefaultMask": true : On EQ-SANS, the instrument team prepares a default mask that contains information about linear position sensitive detectors that are not performing well. If this parameter is true, drtsans automatically determines the correct version of the default mask to use and applies it. This mask is applied in addition to the user-specified mask from the maskFileName parameter. If the value is set to false, any mask specified with the "defaultMask" parameter, below, will be applied.

s. "defaultMask": null : This parameter is used to select an alternative mask in place of the file that would normally be used. It is recommended to leave this value set to null unless told to do otherwise by your local contact.

t. "useMaskBackTubes": false : The EQ-SANS detector, like the Bio-SANS and GP-SANS detectors, consists of an array of linear position sensitive detectors that are arranged in two planes that are offset to ensure complete coverage across the area of the detector. When this parameter is set to true, the back plane of tubes, being those furthest away from the sample, are all masked. Typically, this is only done when the detector is positioned close to the sample.

u. "darkFileName":"/SNS/EQSANS/shared/NeXusFiles/EQSANS/2019B_mp/EQSANS_108764.nxs.h5" : This parameter specifies the name of the file that contains the "dark current" measurement, which for EQ-SANS is normally a measurement performed during regular calibrations with the facility running but the instrument shutter closed. It is a measure of cosmic radiation and detector electronic noise. Your local contact will provide the correct file to use.

v. "normalization": "Total charge" The data can either be normalized by the measurement time ("Time"), the total proton charge accumulated during the measurement ("Totalcharge") or the beam monitor ("Monitor"), which is only appropriate when data has been collected with the choppers running at 60 Hz. The normal method for normalizing EQ-SANS data is "Total charge", which is also how the length of a measurement is normally specified. If "Total charge" is used, then the beamFluxFileName must be provided. Another option is "Monitor", which requires that the flux file and the fluxMonitorRatioFile parameter be provided. Speak to your local contact about the correct files to use.

w. "fluxMonitorRatioFile": "/SNS/EQSANS/IPTS-24769/shared/EQSANS_110943.out" : This is a measure of the beam flux, as measured on the primary detector, relative to the beam monitor. It accounts for the different wavelength efficiencies of the two detectors. It is only used when data are to be normalized by the beam monitor. Consult with your local contact about the correct file to use.

x. "beamFluxFileName": "/SNS/EQSANS/shared/instrument_configuration/bl6_flux_at_sample" : This file contains the instrument flux as a function of wavelength as measured using the primary detector that is used for data normalization during data reduction. Consult with your local contact for the correct file to use.

y. "sensitivityFileName": "/SNS/EQSANS/shared/NeXusFiles/EQSANS/2019B_mp/Sensitivity_patched_thinPMMA_4m_108772.nxs" : The file name of the pre-processed relative pixel response of the detector is specified with this parameter. These calibration files are measured during instrument commissioning each cycle and are prepared by staff for use in data reduction. Consult your local contact for the correct file to use.

z. "useSolidAngleCorrection": true : This parameter specifies whether or not to correct the data for the solid angle subtended by each pixel, which can be a considerable effect for configurations with the detector positioned close to the sample. It is recommended to leave this parameter set to true.

aa. "useThetaDepTransCorrection": true : When set to true, the data reduction will correct the data in each pixel for the actual distance that the neutrons travel through the sample when performing the correction for the transmission. The effect increases with scattering angle and can be considerable when the detector is positioned near the sample. It is recommended to leave this parameter set to true.

bb. "mmRadiusForTransmission": "25" : This parameter allows the user to specify the radius in millimeters to use when integrating the attenuated direct beam measurements for calculating the transmissions. The instrument team has found 25 mm to perform well under most circumstances, but it is possible that certain sample environments or instrument configurations may benefit from the use of a different value. Consult your local contact if you feel that another value may be required.

cc. "absoluteScaleMethod": "standard" : At present, the only method available for scaling data collected on EQ-SANS into absolute units of 1/cm is by using a calibrated standard. Do not change the value of this parameter. Presently, the standard is a well-characterized sample of porous silica that your local contact will provide to you during your experiment. A measurement of the standard is used to derive the absolute scale factor, which is specified with the StandardAbsoluteScale parameter, described below.

dd. "StandardAbsoluteScale": "5.0719320777245" : This is the scale factor that must be applied to the data to place it into absolute units of 1/cm. Your local contact can help you derive it from a measurement of a standard.

ee. "numQxQyBins": "80" : This parameter specifies the number of Q-bins in the 2D reduced data, which is always output by drtsans. Note that only a single value may be provided, which implies that the 2D reduced data is on a regular, square grid that covers the Q-range in 2D measured by the detector. The beam center is not necessarily in the center of the output data. The grid in Q-space is always linear.

f. "1DQbinType": "scalar" : Three options exist for the kind of 1D data that are output by drtsans. Possible values are "scalar", which is used for 1D azimuthally averaged data that most people are familiar with; "wedge" makes it possible to define wedges to perform scalar binning within, as one might do for anisotropic data and utilize the WedgeMinAngles, WedgeMaxAngles and the various autoWedge parameters described below, although automatic wedge determination is not enabled for EQ-SANS at this point in time. The "annular" binning makes it possible to visualize how data varies around the beam center within a Q-range specified by the user and requires that the parameters AnnularAngleBin, Qmin, and Qmax, described below, be provided.

gg. "QbinType": "log" : This parameter dictates whether the Q-spacing of the intensity profiles calculated when performing scalar or wedge binning is logarithmic or linear. The possible values of this parameter are "log" and "linear". The choice of binning determines how the numQBins, LogQBinsPerDecade, and useLogQBinsEvenDecade parameters work.

hh. "numQBins": "100" : This parameter must be set to an integer value if QbinType is "linear", but can also be used if it is "log". The value is the number of Q-values that are in the 1D data that is binned as "scalar" or "wedge" and their spacing is determined by the value of QbinType. This parameter must be null if LogQBinsPerDecade is set to an integer value. Note that the value is enclosed in quotation marks.

ii. "LogQBinsPerDecade": null : This parameter only works when QbinType is "log". The value specified here will be the number of Q-bins that are present within each decade between the minimum and maximum Q values that the reduced data contain. For example, if the value is "25", then there are 25 Q-bins between 0.01 Å^-1 and 0.10 Å^-1 and 25 Q-bins between 0.10 Å^-1 and 1.0 Å^-1 or any other decade in Q that are present in the reduced data. The parameter useLogQBinsEvenDecade must be set to true to enable this option and numQBins must be null.

jj. "useLogQBinsDecadeCenter": false : At present, this option is no longer enabled. The Q-values when using an even number of Q-bins per decade by setting useLogQBinsEvenDecade to true and providing a value for logQBinsPerDecade to a non-zero, positive integer always have a bin centered on 0.001 Å^-1, 0.010 Å^-1, 0.100 Å^-1, etc.

kk. "useLogQBinsEvenDecade": false : This parameter tells drtsans to use a fixed number of Q-bins per decade when binning the result. The logQBinsPerDecade parameter must have a non-zero integer value and numQBins must be null.

ll. "WedgeMinAngles": "-30, 60" mm. "WedgeMaxAngles": "30, 120" : The WedgeMinAngles and WedgeMaxAngles are only used when QbinType is set to "wedge". The arrays provide a matched set of angles, specified in degrees and indexed from the Qx axis, within which to perform 1D Q-binning. In this particular example, 1D Q-binning will be performed in two wedges: from -30° to 30° and from 60° to 120°. The angles need not be the same size and need not be symmetric. It is also possible for the angles to overlap, should the user desire it. The only requirement is that both arrays have the same number of elements and that the minimum angle for a wedge be lower than the maximum value for that wedge.

nn. "autoWedgeQmin": null oo. "autoWedgeQmax": null pp. "autoWedgeQdelta": null qq. "autoWedgeAzimuthalDelta": null rr. "autoWedgePeakWidth": null ss. "autoWedgeBackgroundWidth": null tt. "autoWedgeSignalToNoiseMin": 2.0 : Parameters shown in points nn through tt are required for the drtsans methods for automatically determining the correct wedges to use for binning reduced data into 1D. Development of these routines was driven by the Bio-SANS instrument team. At present, automatic wedge determination is not available for data collected using EQ-SANS.

uu. "AnnularAngleBin": 5.0 : When the 1DQbinType parameter is set to "annular" this parameter specifies the size of the bins in degrees that are to be used for binning. Annular binning takes the data in a ring of Q-values and creates a profile as a function of angle around the beam center. Annular binning also requires that Qmin and Qmax, described below, be specified.

vv. "Qmin": null ww. "Qmax": null : When performing annular binning this is the minimum and maximum Q-values, specified in Å^-1, to use during the binning. These parameters are only used when 1DQbinType is set to "annular".

xx. "useErrorWeighting": false : If weighting by the experimental uncertainty is desired when binning the reduced data and propagating the corresponding uncertainties, set the value of this parameter to true.

yy. "smearingPixelSizeX": null zz. "smearingPixelSizeY": null : The detectors used in the SANS instruments at ORNL are gas detectors. The pixel sizes are determined from parameters supplied to the hardware that determines where a neutron is detected and can be varied by changing said parameters. In actuality, there is intrinsic uncertainty in the position of the event along the tube. Further, the arrangements of the tubes in the detector makes it possible to have a neutron in the region of overlap between a tube in the front panel and a tube in the back panel be detected in either, which also creates uncertainty in the position in which an event is encoded. The smearingPixelSizeX and smearingPixelSizeY parameters make it possible to account for this uncertainty when calculating the uncertainty in Q. The effect is small for most Q-values, but can impact data analysis when sharp features are present. Your local contact can provide suitable values for the parameters. Note that specifying values for these two parameters does not change the calculation of the value of Q or the intensity profile that results after reduction. It only alters the uncertainty in Q of the result.

aaa. "useSubpixels": null : In cases where there are sharp features in the data, or a need to use as much data near the beamstop as possible, it is possible to divide the pixels defined on the detector into sub pixels to improve the quality of the results from the 1D binning process. Subpixels, if specified, will also be used in the 2D binning. To enable this feature, set useSubpixels to true and set subpixelsX and subpixelsY, described below, to positive integers.

bbb. "subpixelsX": null ccc. "subpixelsY": null : Set these two parameters to a non-zero, positive integer to use subpixels when binning the data. The real pixels will then be divided into subpixels for the binning in the data reduction. If subpixelsX is set to 2 and subpixelsY is set to 3, then each pixel will be divided into a 2 by 3 grid for the binning process.

ddd. "useSliceIDxAsSuffix": true : At present, this option is not implemented. In the future, when performing time or log slicing of an event stream during data reduction, setting the value of this parameter to true will mean that each slice is assigned a consecutive numerical value that is used to construct the output file name. If the value is set to false, the beginning and ending values of the slice will be used to construct the output file names.

"dataDirectories": "/SNS/EQSANS/shared/codereview/acceptance/wt3_final/ipts24184/"

Quick Reference for the data reduction parameters

Introduction

Parameter Descriptions

Up: Index