Editors: Lisa DeBeer-Schmitt, Lilin He, Ken Littrell
Date: 07/22/2020
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-04-15T21:09:52.745905",
"instrumentName": "GPSANS",
"iptsNumber": 25849,
"dataDirectories": null,
"sample": {
"runNumber": "11038",
"thickness": 0.1,
"transmission": {
"runNumber": "11028",
"value": null
}
},
"background": {
"runNumber": "11001",
"transmission": {
"runNumber": "10991",
"value": null
}
},
"emptyTransmission": {
"runNumber": "10991",
"value": null
},
"beamCenter": {
"runNumber": "10991"
},
"outputFileName": "s16high_q",
"configuration": {
"outputDir": "/HFIR/CG2/IPTS-25849/shared/LDS/",
"wavelength": null,
"wavelengthSpread": null,
"useTimeSlice": false,
"timeSliceInterval": null,
"useLogSlice": false,
"logSliceName": null,
"logSliceInterval": null,
"sampleOffset": null,
"useDetectorOffset": true,
"detectorOffset": 0.0,
"sampleDetectorDistance": null,
"sampleToSi": null,
"sampleApertureSize": null,
"sourceApertureDiameter": null,
"usePixelCalibration": false,
"maskFileName": "/HFIR/CG2/IPTS-25849/shared/high_q_mask.nxs",
"useDefaultMask": true,
"defaultMask": [
{
"Pixel": "1-10,247-256"
}
],
"useMaskBackTubes": true,
"darkFileName": null,
"normalization": "Monitor",
"sensitivityFileName": "/HFIR/CG2/shared/drt_sensitivity/sens_c487_bar.nxs",
"useSolidAngleCorrection": true,
"blockedBeamRunNumber": "11054",
"useThetaDepTransCorrection": true,
"DBScalingBeamRadius": 80.0,
"mmRadiusForTransmission": 80.0,
"absoluteScaleMethod": "direct_beam",
"StandardAbsoluteScale": 1.0,
"numQxQyBins": 256,
"1DQbinType": "scalar",
"QbinType": "log",
"numQBins": null,
"LogQBinsPerDecade": 33,
"useLogQBinsDecadeCenter": true,
"useLogQBinsEvenDecade": true,
"WedgeMinAngles": null,
"WedgeMaxAngles": null,
"autoWedgeQmin": 0.003,
"autoWedgeQmax": 0.04,
"autoWedgeQdelta": 0.01,
"autoWedgeAzimuthalDelta": 1.0,
"autoWedgePeakWidth": 0.25,
"autoWedgeBackgroundWidth": 1.5,
"autoWedgeSignalToNoiseMin": 2.0,
"AnnularAngleBin": 1.0,
"Qmin": null,
"Qmax": null,
"useErrorWeighting": false,
"smearingPixelSizeX": null,
"smearingPixelSizeY": null,
"useSubpixels": true,
"subpixelsX": 5,
"subpixelsY": 5,
"wedges": null,
"symmetric_wedges": true
},
"logslice_data": {}
}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. The juypter notebook reduction scripts used by GP-SANS convert these schemas into python dictionaries. This means that true/false must be changed to True/False and null to None otherwise the script will throw errors.
"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": "GPSANS" : 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": "25849" : 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": "11038" : 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": 0.1 : This parameter specifies the sample thickness in centimeters. 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.
"runNumber": "11028" : 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": "11001", : 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": "10991" : 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": "10991" : 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. This data is also used to calculate the absolute scaling on GP-SANS when the direct beam method is selected in "absoluteScaleMethod":"direct_beam"
a. "runNumber": "10991" : This is the run number of an empty beam or a transmission measurement. It cannot be left blank.
"outputFileName": "s16high_q" : 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 "s16high_q*.*". The filename can be any valid string that is acceptable for filenames for a Linux 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 juypter notebook for data reduction, some of these parameters may not be presented to you.
a. "outputDir": "/HFIR/CG2/IPTS-25849/shared/LDS" : 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. "wavelength":null : This is a place where if the wavelength saved to the metadata needs to be overwritten. This should only be done with your local contact
c. "wavelength_spread":null : This is a place where if the wavelength spread saved to the metadata needs to be overwritten. This should only be done with your local contact.
d. "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.
e. "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.
f. "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.
g. "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.
h. "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.
i. "sampleOffset": null : 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.
j. "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.
k. "detectorOffset": 0.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.
l. "sampleDetectorDistance": null, : This parameter is to overwrite the sample to detector distance saved in the metadata in case it is incorrect. This number should not be changed without the help of your local contact.
m. "sampleToSi": null, : This parameter is to overwrite the sample to silicone window distance saved in the metadata in case it is incorrect. This number is usually set at the beginning of your experiment after your sample environment is installed and the distance from the sample to the front of the detector is known. This number should not be changed without the help of your local contact.
n. "sampleApertureSize": null : 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 taken position of the aperture in the collimator boxes. It is usually in the box after the last guide in the beam. For maximum resolution on GP-SANS, there is 20 mm source diameter that can be used in box 1 otherwise this number is usually 40 mm for all other settings.
p. "usePixelCalibration": true : This parameter is using a pixel map that takes into account the center of pixel on the detector along with its corresponding width and height. This calibration takes into account the nonlinearity of the detector tubes.
q. "maskFileName":"/HFIR/CG2/IPTS-25849/shared/high_q_mask.nxs" : This is the name of a hand-drawn mask. Your local contact can help you prepare a mask for your specific experiment.
r. "useDefaultMask": true : On GP-SANS, the instrument applies a default mask that will remove the top and bottom 10 pixels of the detector since these are not truly active regions of the detector.
s. " defaultMask": [{"Pixel": "1-10,247-256"}], : This how the default top and bottom pixels are masked. If more are needed, discuss this with your local contact.
t. "useMaskBackTubes": false : The GP-SANS detector, like the
Bio-SANS and EQ-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 <2
m.
u. "darkFileName": null : This parameter specifies the name of the file that contains the "dark current" measurement, which for GP-SANS is normally a measurement performed either during regular calibrations with the facility running but the instrument shutter closed or during your experiment in case non-standard instrument configurations is used. It is a measure of cosmic radiation and detector electronic noise. Your local contact will help you find the correct file to use.
v. "normalization": "Monitor" : The data can either be normalized by
the measurement time ("Time") or the beam monitor
("Monitor"). The normal method for normalizing GP-SANS data
is "Monitor" so that the constant increase of the flux from
the reactor can be taken into account. "Time" can be used
but only if the data is being compared is within 2 to 3 days of each
other.
w. "sensitivityFileName": "/HFIR/CG2/shared/drt_sensitivity/sens_c487_bar.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.
x. "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.
y. "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.
z. "DBScalingBeamRadius": 40.0, : This parameter allows users to specify the radius in millimeters to use when integrating the attenuated beam center data for calculating the scaling factor for putting the data on an absolute scale (See bb). The instrument team has found 40 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.
aa. "mmRadiusForTransmission": "40" : 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 40 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.
bb. "absoluteScaleMethod": "direct_beam" : There are two methods available for scaling data collected on GP-SANS into absolute units of 1/cm. The first is by the "direct_beam" method which takes attenuated beam center data specified earlier and calculates the total intensity at the beam center by taking into account the known attenuation rates of the attenuator. This number is then used by the reduction script to divide the intensity to put it on an absolute scale. The other method is "standard" which uses 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 if needed. A measurement of the standard is used to derive the absolute scale factor, which is specified with the StandardAbsoluteScale parameter, described below. GP-SANS uses the direct beam by default since large sample environments that cannot always allow for measurement of the standard are used.
cc. "StandardAbsoluteScale": "1.0" : 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. If using "direct_beam" method, this number is
ignored but it is always safe to leave it at 1.0
dd. "numQxQyBins": "160" : 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.
ee. "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 GP-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.
ff. "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.
gg. "numQBins": null : 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.
hh. "LogQBinsPerDecade": 33 : 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.
ii. "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.
jj. "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.
kk. "WedgeMinAngles": "-30, 60" ll. "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.
mm. "autoWedgeQmin": null nn. "autoWedgeQmax": null oo. "autoWedgeQdelta": null pp. "autoWedgeAzimuthalDelta": null qq. "autoWedgePeakWidth": null rr. "autoWedgeBackgroundWidth": null ss. "autoWedgeSignalToNoiseMin": 2.0 : Parameters shown in points mm through ss, 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 GP-SANS.
tt. "AnnularAngleBin": 1.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.
uu. "Qmin": null vv. "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".
ww. "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.
xx. "smearingPixelSizeX": null yy. "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.
zz. "useSubpixels": true : 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.
aaa. "subpixelsX": 5 bbb. "subpixelsY": 5 : 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.
ccc. "wedges": null : This is the output of automatic wedges. It shows the wedges used by the function.