ISIS direct reduction script description.

Overview

All ISIS direct inelastic reduction scripts have similar interface and layout, with only parameters different for different instruments. Some parameters change from one cycle and sometimes one experiment to another but most of them are instrument specific and changes only when instrument is modified. Instrument scientists prepare cycle specific master Mantid python reduction scripts, which are then automatically distributed to Isiscompute users according to the rules described here.

From the links below one can retrieve resent versions of these scripts and their default reduction parameters stored in XML files, namely:

Instrument	Simple reduction script	Full reduction script	Default reduction parameters	User Settings Description file
MARI:	template_mari.py	MARIReduction_Sample.py	MARI_Parameters.xml	MARI User settings
MAPS:	template_maps.py	MAPSReduction_Sample.py	MAPS_Parameters.xml	MAPS User settings
MERLIN:	---	MERLINReduction_Sample.py	MERLIN_Parameters.xml	MERLIN User settings
LET:	---	LETReduction_Sample.py	LET_Parameters.xml	LET User settings
HET:	---	HETReduction.py	HET_Parameters.xml	Is not autoconfigured

The template_instrument_name.py and InstrumentReduction_Sample.py files referenced in column two and three above are processed by MantidConfigurationScript, which replaces the strings, specified in correspondent User Settings Description file (Column 5) and produces simple and full reduction scripts for users (Row 8, Output 2 of the Table by the link).

Parameters used by every user are usually the run number or list of run numbers to process, run number for a white beam vanadium run, energies the user is interested in and the energy binning. There are couple of other parameters, directly related to the experiment in progress. These parameters are better described in the script itself.

Simple reduction script is created for users who prefer old functional interface used by qtiGenie and Libisis. It highlights only the parameters user needs to change during an experiment and allows users to separate all parameters, necessary to reduce data and user's parameters in different files.

Simple reduction script imports the full reduction script. Imported full reduction scripts picks up all reduction parameters defaults from the appropriate xml file and sets up parameters, specified in the script overriding default values. Parameters, specified in the Simple reduction script override all parameters, specified in the full reduction script and the instrument specific xml files. On execution, both simple and advanced reduction scripts run the same data reduction process, described below.

User may work directly with the full reduction script as this one has all necessary parameters which can then be fine tuned for particular runs in the __main__ section of the script as described in the script. In fact, setting up selected number of simple parameters in a separate simple script or setting up all parameters together in one full script is the matter of personal choice between using one big file with all parameters or two files with different sets of parameters.

For instruments, where the simple reduction script is present, user can find the definition of the iliad function, used by the simple reduction script inside the full reduction script.

Reduction Scripts in Depth

This chapter intended for advanced users or instrument scientists who wants to modify reduction scripts and add some new features to them. To benefit from reading the following, a user should be familiar with OOP jargon and have some knowledge of Python concepts for Properties descriptors, Decorators, and usage of __setattr__ and __getattr__ methods. We also use word Run as synonym for the results of single inelastic experiment (a file or range of files, recorded during experiment and associated with the instrument and a particular experiment number (run number))

Reduction script files and their purpose

ISIS reduction scripts are part of Mantid and located under Mantid installation folder in /scripts/Inelastic/Direct directory (/opt/Mantid/scripts/Inelastic/Direct on Unix, c:\Mantid\scripts\Inelastic\Direct under Windows or see it on the web here). The following files are located in subfolder Direct:

File	Description
DirectEnergyConversion.py	The python class implementing ISIS direct inelastic reduction workflow. Its most important method is convert_to_energy,invoked for each run or sum of runs, and converting data, obtained in experiment into reduced data. All other methods of this class are directly or indirectly called by this method. The class also imports diagnostics.py file, containing number of functions, responsible for various diagnostics operations over a Mantid workspace.
NonIDF_Properties.py	The file contains the parent class for the PropertyManager class below. It instantiates and controls properties, not related to the properties found in Instrument_Parameters.xml file. (e.g. incident_energy, or sample_run)
PropertyManager.py	When workspace is loaded, Mantid reads appropriate InstrumentName_Parameters.xml file and interprets all records, found in this file as instrument parameters with appropriate names. This python class, together with NonIDF_Properties class get access to these parameters and transforms them into DirectEnergyConversion process properties. This class is also responsible for processing user input and all other DirectEnergyConversion properties, and provides input data and settings for DirectEnergyConversion. To do that PropertyManager, together with NonIDF_Properties class instantiates classes found in three other files, namely: PropertiesDescriptors.py,RunDescriptor.py and ReductionHelpers.py.

PropertiesDescriptors.py,RunDescriptor.py and ReductionHelpers.py contain small classes and functions helping to process and provide various input parameters to DirectEnergyConversion, namely :

File	Description
ReductionHelpers.py	contains range of helper functions and the class, which is automatically instantiated for the Instrument_Parameters.xml fields, which do not need complex behaviour (e.g. load_monitors_with_workspace True or False)
PropertiesDescriptors.py	contains classes related to properties, described in Instrument_Parameters.xml but providing more complex behaviour for such properties. E.g. DetCalFile class describes detector calibration file det_cal_file present in Instrument_Parameters.xml but contains valiadators, used to check correct file extension and if the calibration file is indeed present.
RunDescriptor.py	contains one but most important property descriptor, related to the reduced and auxiliary experimental data(file). It's responsible for conversion between run numbers and file names, loading appropriate files to Mantid to use in reduction, renaming workspaces according to different stages of reduction process, etc. Each run related property such as sample_run,wb_run, monovan_run, etc is described by a variable-instance of this class located in NonIDF_Properties class.

Note: PropertyManager and many properties descriptors form files above are implemented as singletons so any property instance can be accessed in reduction as:

  prop = PropertyManager.property_name

When PropertyManager has been instantiated somewhere in the python workspace (as part of the reduction script, see below) the call like:

is_multirep  = PropertyManager.incident_energy.multirep_mode()   Returns true if energy is defined as list of energies and false otherwise (multirep mode)

or:

 run_nuber = PropertyManager.sample_run.run_number()    Get run number for defined sample run.
 ws        = PropertyManager.sample_run.get_workspace()  Get Mantid workspace correspondent to sample run (if one is defined) at current state of reduction
                                                         The data will be loaded in memory and properly calibrated if this have not happened yet.

Note the difference between getting the whole property above, allowing access to the properties methods, and getting access to property value within PropertyManager instance (PropertyManager instantiated in DirectEnergyConversion as prop_man):

 dc = DirectEnergyConversion('MER')
 dc.prop_man.sample_run = 2034  # Accessing the PropertyManager instance prop_men defined within DirectEnergyConversion class
 print "Sample run number is: ",dc.prop_man.sample_run

prints:

Sample run number is:2034

while calling

 ws        = PropertyManager.sample_run.get_workspace()

after assigning number to the sample run will try to load Merlin workspace and will return it if Merlin run file for experiment with run number 2034 can be found on the Mantid search path.

Simplest reduction script can be build on the basis of DirectEnergyConversion class as follows:

Usage:
   red = DirectEnergyConversion('InstrumentName')
   red.prop_man.sample_run = run number
   red.prop_man.wb_run     = Whitebeam
   red.prop_man.incident_energy = energy guess
   red.prop_man.energy_bins = [min_val,step,max_val]
   red.convert_to_energy()

Or in functional form:

   red = DirectEnergyConversion('InstrumentName')
     and then:
   red.convert_to_energy(wb_run,sample_run,ei_guess,rebin)
     or
   red.convert_to_energy(wb_run,sample_run,ei_guess,rebin,**arguments)
     or
   red.convert_to_energy(wb_run,sample_run,ei_guess,rebin,mapfile,**arguments)

In more details various ways of calling the convert_to_energy method are described within DirectEnergyConversion class itself.

Reduction wrapper

User usually reduces range of data files. In additional to that, if autoreduction is deployed, the parameters of the reduction script should be loaded to and be modifiable from the web interface.

ReductionWrapper.py 

class provides procedures to run reduction over list of run numbers, to wait until the files intended for reduction are actually recorded and the decorators, switching between the web interface if the reduction is run by the autoreduction and provided by a user if the reduction is run in the user's Mantid session.

User's reduction files described in the section above contain the ReductionWrapper class overloaded and modified according to the features of the particular instrument, and the __main__ section, which instantiates appropriate class and executes run_reduction() method of this ReductionWrapper instance if the reduction script is run from the user's session. The web service runs its own instance of the instrument specific ReductionWrapper class, providing this instance with the information to pick up the parameters from the autoreduction web interface.