slaw - convert neutron scattering histograms to scattering laws S(q,w)
slaw [-s] [-v|-d level] [-b] [-i | -f file | -e "commands"]
Slaw converts raw data from inelastic neutron scattering into a scattering law S(2th,w) or S(q,w).
Slaw supports several spectrometers and a variety of output formats. It also supports four-dimensional data sets S(q,w,T) or S(q,w,t) obtained in inelastic temperature scans or kinetic measurements.
Slaw processes data through the following steps:
read raw data files, adding or subtracting subscans as needed;
divide by monitor count;
subtract empty-can measurement, possibly correcting for self-absorption [NOT YET IMPLEMENTED];
determine the energy scale, and normalize neutron counts to energy channel width, if necessary adjusting the energy scale to the elastic line of a reference measurement;
suppress data from defect detectors as determined from a reference measurement;
divide counts by elastic intensity of a reference measurement (usually vanadium);
optionally, convert S(2th,w) into S(q,w) [NOT YET IMPLEMENTED];
save the scattering law.
Not all steps apply to all spectrometers; some steps are optional.
Slaw can be invoked in four different ways:
Read commands from file Slawfile in the present working directory.
Read commands from stdin.
Read commands from file.
Execute semicolon-separated commands from the command line argument. The double quotes are necessary to prevent shell expansion.
In the above commands, options may include any of the following:
Silent: don't print progress report to stderr.
Verbose: echoes input commands and low-level commands to stderr.
Debug: even more verbose, if level = 2,3,...
Break pipe: do not invoke the low-level data processing routine; just write the low-level commands to stdout.
Syntax.
Commands are separated by line breaks, except in -e mode where ";" serves as command separator.
Comments start with "#" and extend to the end of line.
There are four types of commands: control command, global parameter setting, register command, production.
At present, the only control command is
Do not read the command script beyond this point. Useful for debugging.
A global parameter setting sets the default value of a parameter. Examples:
Set the global parameter "input path" to directory
Set the global parameter "output overwrite" to "off": do not overwrite existing output files.
Registers hold more complex data than parameters. A register command outside a production ("at global scope") can be used to dump, to load, or to set a register. Examples:
Dump the normalization register to the default file slaw.norm.
Load zero-energy settings from file
A production reads a raw data set, performs conversions, corrections and calibrations, and almost always writes the so obtained scattering law to an output file. Optionally instrument parameters can be determined and stored in registers for use in the following productions.
A production command consists of a raw data list, which must always come first, optionally followed by embedded parameter commands and register commands in arbitrary order, separated by blanks. Embedded parameter commands overwrite global settings for the duration of the current production. Register commands are intrinsically global or local.
Example for a production:
Here, "42-47" is a raw data specification, "of van" is a local parameter setting, and ">N" sets a register.
Raw Data Specification.
Raw data file names have the form path/subscan. The path is controlled by the parameters 'ip' and 'ie'. The susbscan identifier is assumed to start with a digit; it must not contain ",", "-", or "!".
Every production command starts with a subscan list. A subscan list is a comma-separated list of subscan ranges subscan[-subscan].
At SPHERES, the local file organization allows for more expressive raw data specifications. For instance, raw data files 12u0-12u7 make up scan 12. Within this scan, subscan ranges are specified as follows:
12 # short for 12u0-12u7 (entire scan) 12u2! # range consisting of one single subscan 12u2-12u5 # subrange within scan 12u2-5 # short for 12u2-12u5 -12u2 # short for 12u0-12u2 (from beginning of scan) 12u3- # short for 12u3-12u7 (to end of scan)
To avoid mistakes, single-subscan ranges must be followed by an exclamation mark.
Parameters.
Parameters may have boolean, integer, floating-point or string values. In the following, boolean parameters are marked by the suffix "+-".
Boolean parameters are switched on or off by the commands
parameter+, parameter-.
All other parameters are set by the command
parameter value.
Input specification parameters:
This parameter must be set at the beginning of each command script. Allowed values: see section "supported instruments" below.
Common part of the raw data file name. This maybe just a directory path (in this case, it should terminate with a slash), but it may also include the common part of a run number. Default: ./ (current working directory).
If input files contain several temperature readings, this parameter indicates which one shall be used. Allowed values at SPHERES: Tsam, Tset, none; for legacy data (up to S85) T0 and T1. Default: Tsam.
Sample temperature (in K). Overwrites the temperature record in the raw data file. Used when that record is missing or incorrect.
Output specification parameters:
Save processed scattering law in an output file ? Default = yes.
Overwrite existing output files ? Default = yes.
Absolute or relative path to the output directory. Default: current working directory.
Name of the output file, relative to the path set by op. If missing, a file name is generated automatically, based on raw data file names [IMPLEMENTED ?]. Special value "STDOUT": write to stdout.
Allowed values: see section "supported output formats" below. Using a comma-separated list, it is possible to specify more than one format.
Set the energy/frequency scale to <unit>, and the scattering law scale to <unit>^-1. Allowed values: ueV.
Output standard errors along with S(q,w) ? Default = yes.
Output elastic scattering wave number q0 instead of scattering angle 2th. Default = no.
Treat data set as a time scan ? Default = no.
In time-scan mode, the output file will contain a sequence of scattering laws. Otherwise, in regular-scan mode, all input scans will be summed to yield just one output scattering law.
Requested in time-scan mode to characterize the single scans within a time scan. Allowed values: T (temperature), t (time), Mon (monitor flux).
These data are from an elastic scan. Default = no.
Data processing parametes:
Parameter value must be a comma-separated list of detectors that shall be deleted. This deletion is carried out before the one governed by register D. Immediately after the deletion, the remaining detectors are renumbered starting with 0.
Bin energy channels. Parameter value must be an integer, indicating how many input channels will be binned into one output channel. Default: switched off (bc-, equivalent to bc 1).
Parameter value must be a comma-separated list of the detectors that start a bin. Example: "0,3,8" forms groups 0-2, 3-7, 8-end. Immediately after execution, the binned detectors are renumbered starting with 0. Default: switched off (bd-).
For elastic scans, or spectral time-scans. Parameter value must be an integer, indicating how many raw time intervals will be binned into one. Default: switched off (bt-, equivalent to bt 1).
Normalize to monitor ? Default: yes.
Half width of the normalization interval: The "vanadium" normalization is done by integration from w0-wnor to w0+wnor, where w0 is the frequency/energy of elastically scattered neutrons. Units as set by ou. Required when register N is in use.
These two parameters can be used to restrict the frequency/energy range of the output spectra. Units as set by ou.
Constant noise in cnts/sec. Default: 0. To be subtracted prior to any energy-dependent normalisation. MAY BE MODIFIED OR REMOVED IN THE NEAR FUTURE. Should be replaced by a background register, since noise is detector dependent.
Registers.
Register commands control background subtraction, detector selection, intensity normalization, and energy zero adjustment:
C Container scattering, for background subtraction D Detector selection, for elimination of deficient ones N Normalization intensity, e.g. from vanadium scattering Z Zero-point location, for time-of-flight to energy conversion
Commands (where R may be one or several of CDNZ):
For use in a production. Use current data to set R. Starting with the present production, use R for data processing.
Load R from file [NOT YET IMPLEMENTED].
Load R from default file (see "files" section below) [NOT YET IMPLEMENTED].
Dump R to file [NOT YET IMPLEMENTED].
Dump R to default file [NOT YET IMPLEMENTED].
Do not apply R in the current production (automatically for C).
As an experimental feature, several of these commands may be combined into shorthands like >>BZ->.
We consider an idealized time-of-flight experiment that has produced the following data:
files 0- 9: vanadium files 10-19: empty cell files 20-29: sample at 220K files 30-32: sample at 340K files 33-34: junk files 35-39: sample at 340K, continued
For these data, we use the following batch file:
ii TOFTOF # initialize instrument
ot y08 # select "y08" output format
0-9 >>DNZ o- # read vanadium data;
# apply correction C (subtract container data);
# from now on, use the current data
# - for automatic detector selection (D),
# - for intensity normalization (N),
# - for adjusting the energy zero (Z);
10-19 >>C o- # read empty-container data;
# use them from now on for container subtraction (C)
20-29 of s220 # read sample data;
# apply corrections C,D,N,Z;
# save spectra in s220.y08
30-32,35-39 of s340 # read selected sample data;
# apply corrections C,D,N,Z;
# save spectra in s340.y08
Pure backscattering spectrometer, operated by Juelich Centre for Neutron Scattering, located at FRM II, Garching, Germany; http://apps.jcns.fz-juelich.de/spheres.
Pure time-of-flight spectrometer of Technische Universitaet Muenchen, FRM II, Garching, Germany; http://www.frm2.tum.de/en/science/spectrometer/toftof/.
Pure backscattering spectrometer of the Institut Laue-Langevin, Grenoble. In operation since approx. 1995. Data format changed in 2008 to accomodate new Doppler drived. Shut down in 2010 to prepare for new spectrometer IN16B. http://www.ill.eu/instruments-support/instruments-groups/instruments/in16/.
YAML-based format for Frida2.
Verbous format for Frida1.
Traditional ILL format. For use with LAMP.
A simple rectangular table. One line per energy channel. First column contains the energy. Columns 2n, 2n+1 contain S(q,w) and standard error for detector n.
A sequence of tables. One table per detector. For each table, a header line contains the detector angle (or q). The remainder of the table is rectangular; one line per energy channel; the three columns contain energy, S(q,w), standard error.
For Michael Monkenbusch's data analysis program datreat.
Executables:
Installation destination. Typically /usr/local/.
Ruby script, containing the command compiler (the high-level part of slaw).
Directory containing submodules needed by slaw.
Low-level data processing program for individual instruments.
Needed by slaw.rb to check whether SPHERES data have been saved in incremental mode or not.
Input and output files (all in present working directory):
Default input command script.
Default location for dumping and retrieving the empty-cell spectra.
Default location for dumping and retrieving the list of useable detectors.
Default location for dumping and retrieving the intensity normalization.
Default location for dumping and retrieving the energy-scale zeroes.
On error, slaw prints a message to stderr and terminates. If an internal consistency check failed, the error message starts with the word "BUG". Please send a report to the program's author. In all other cases the error is likely due to invalid input.
Main web site: http://apps.jcns.fz-juelich.de/slaw
Download location: http://apps.jcns.fz-juelich.de/src/slaw
Development snapshot: git://apps.jcns.fz-juelich.de/slaw.git/
Note that slaw requires the script language Ruby (http://www.ruby.org) to be installed.
Program and documentation written by Joachim Wuttke <j.wuttke@fz-juelich.de>, reusing code from SQW, INX, and Frida1.
Slaw is the successor of legacy programs like SQW and INX.
INX by F. Rieutord and G.J. Kearley is the traditional raw-data refinement program for the time-of-flight spectrometers IN4, IN5, IN6 of the Institut Laue-Langevin (ILL, Grenoble, France).
SQW by I. Anderson, R. Nelson, M. Wendel and J. Wuttke has been traditionally used for the ILL's backscattering spectrometers IN10, IN13, IN16.
In the mid-1990s, INX and SQW were integrated in the data analysis program IDA (later renamed Frida1) by J. Wuttke. Substantial improvements were contributed by A. Meyer and F. Kargl.
Development of Slaw started in 2008. The aims were:
allow iterative refinement with minimal editing, using concise script control;
support different spectrometers in a unified way;
support inelastic temperature scans or kinetic measurements;
do not bind users to a specific data-analysis program, but support all desired output formats.
Since mid-2008, a prototype version has been in use at the backscattering spectrometer SPHERES. The current version of Slaw has been implemented in 2010.
Copyright 2008-13 by Joachim Wuttke.
Free use of this software is granted under the terms of the GNU General Public License (GPL).