Difference between revisions of "Homer and mgenie style functions"

From LIBISIS
Jump to navigation Jump to search
 
(36 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
!!! [Special Population Routines]
+
== Preparing the [[IXTdata_source]] ==
  
−
!!Preparing the [IXTdata_source]
+
All the population routines descirbed here use the [[IXTdata_source]] object.  The [[IXTdata_source]] object is used to define source files for the population of an [[IXTrunfile]] object. Different source files can be added to the [[IXTdata_source]] object with their own special commands:
−
All the population routines descirbed here use the [IXTdata_source] object.  The [IXTdata_source] object is used to define source files for the population of an [IXTrunfile] object. Different source files can be added to the [IXTdata_source] object with their own special commands:
 
  
−
*rawfiles: [addrawfile]
+
*rawfiles: [[add_rawfile]] [[add_multrawfile]]
−
*monitor map files: [addmonmap]
+
*monitor map files: [[add_monmap]]
−
*monitor mask files: [addmonmask]
+
*monitor mask files: [[add_monmask]]
−
*detector map files: [adddetmap]
+
*detector map files: [[add_detmap]]
−
*detector mask files: [adddetmask]
+
*detector mask files: [[add_detmask]]
  
−
It is <b>necessary</b> to define the type of instrument you are using in the [IXTdata_source] object, of course only <b>one</b> instrument can be defined for population to work as you would expect. This affects how the IXTrunfile is populated, and the current options are as follows
+
It is <b>necessary</b> to define the type of instrument you are using in the [[IXTdata_source]] object, of course only <b>one</b> instrument can be defined for population to work as you would expect. This affects how the IXTrunfile is populated, and the current options are as follows
  
−
*chopper instruments: [addchopinst]
+
*chopper instruments: [[add_chopinst]]
−
*diffraction instruments: [adddiffinst]
+
*diffraction instruments: [[add_diffinst]]
  
−
!! Alternative [IXTmap], [IXTmask] population
+
== IXTmap and IXTmask files ==
  
−
The commands above are for specifying files, it is also possible to populate [IXTmap] and [IXTmask] objects in the matlab environment from the command line.
+
Different instruments generally have their own map files associated with them, but it is also possible to create [[IXTmap and IXTmask from the matlab command line]]
  
−
[IXTmask]
+
==  Populating [[IXTrunfile]] ==
  
−
<pre>
+
There are three standard ways to populate an [[IXTrunfile]] object, all require an [[IXTdata_source]] object which has had the type of instrument defined in it ie. chopper or diffraction instrument. As well as simply loading data from a raw file the data can generally be optionally masked/mapped/rebinned using an argument to the population function as a keyword with an associated parameter (eg. a map/mask file, rebin parameters etc.)
−
>> mask_array = ~[1,3,5,6,7,8,9]
 
−
>> mask = IXTmask(mask_array)
 
−
</pre>
 
−
or
 
−
<pre>
 
−
>> mask = IXTmask(~[1,3,5,6,7,8,9])
 
−
</pre>
 
−
* this is a special [IXTmask] constructor
 
−
* mask is an [IXTmask] object
 
−
* mask_array is an array of spectra to be masked
 
−
* a mask object can be created by <b>DIAG</b> which is one of the [Diagnostic tools for homer]
 
  
−
[IXTmap]
+
*'''For any of these functions to run properly the matlab environment must be prepared by calling the [[instrument setup]] scripts.'''
 +
*If a map/mask/raw file is provided as a command line argument, then it will override any specification already defined in the [IXTdata_source] object.
 +
*If no map files are defined, either on the command line or in the [[IXTdata_source]] object then a 1:1 mapping with _all_ spectra will be created by default. If no mask files are defined then all spectra will be included in the workspaces.
 +
 
 +
The standard construction for these population routines is as follows.
  
 
<pre>
 
<pre>
−
>> spectrum_arrays = {~[1,3,5,6],~[7,8,9,10],~[11,12,13,14]}
+
>> RF=pop_fun(DSO, run_no, 'keyword_1', parameter_1,..., 'keyword_N',parameter_N)
−
>> workspace_numbers = ~[1,22,333]
 
−
>> map=IXTmap(spectrum_arrays)
 
−
</pre>
 
−
or
 
−
<pre>
 
−
>> map=IXTmap(~[1,22,333],{~[1,3,5,6],~[7,8,9,10],~[11,12,13,14]})
 
 
</pre>
 
</pre>
−
* this is a special [IXTmap] constructor
 
−
* spectrum_arrays is a <b>cell array</b> containing numerical lists of spectra to be grouped together into workspaces
 
−
* the array workspace_numbers is optional, and if not provided workspace numbers will be given values 1->N where N = size(spectrum_arrays,2)
 
  
−
!! Populating [IXTrunfile]
+
For any of these functions to run properly the matlab environment must be prepared by calling the [[instrument setup]] scripts.
−
There are three standard ways to populate an [IXTrunfile] object, all require an [IXTdata_source] object which has had the type of instrument defined in it ie. chopper or diffraction instrument. As well as simply loading data from a raw file the data can generally be optionally masked/mapped/rebinned using an argument to the population function as a keyword with an associated parameter (eg. a map/mask file, rebin parameters etc.)
 
  
−
If a map/mask/raw file is provided as a command line argument, then it will override any specification already defined in the [IXTdata_source] object.
 
  
−
If no map files are defined, either on the command line or in the [IXTdata_source] object then a 1:1 mapping with _all_ spectra will be created by default. If no mask files are defined then all spectra will be included in the workspaces.
+
* RF is an [[IXTrunfile]] object
 +
* DSO is an [[IXTdata_source]] object which contains an instrument type definition
 +
* pop_fun  can be either _mon,spec,pop_full,homer_
 +
* raw file specification does not use a keyword, it is built up from the standard instrument abbreviation (eg. HRP, MAR, SRF etc.) and the run number automatically according to which setup file has been run. If this has not been run then the script will fail and tell you
 +
* keywords are ''always'' character strings and each keyword '''must''' be followed by a parameter
 +
* values can take any appropriate type
 +
* map files have a designated [[Map File Format]]
 +
* mask files have a designated [[Mask File Format]]
  
−
The standard construction for these population routines is as follows.
 
  
−
<pre>
+
=== mon ===
−
>> RF=pop_fun(DSO, inst_abv, run_no, 'keyword_1', parameter_1,..., 'keyword_N',parameter_N)
 
−
</pre>
 
−
* RF is an [IXTrunfile] object
 
−
* DSO is an [IXTdata_source] object which contains an instrument type definition
 
−
* pop_fun  can be either _mon,spec,pop_full,homer_
 
−
* raw file specification does not use a keyword, it is built up from the standard instrument abbreviation (eg. HRP, MAR, SRF etc.) and the run number
 
−
* keywords are _always_ character strings and each keyword must be followed by a parameter
 
−
* values can take any appropriate type
 
−
* map files have a designated [Map File Format]
 
−
* mask files have a designated [Mask File Format]
 
  
−
!! mon
+
This function populates an [[IXTrunfile]] object with the raw time-of-flight data for the monitors in the runfile.mon_data [IXTdata] object only. It will optionally accept the keywords in the following table:
−
This function populates an [IXTrunfile] object with the raw time-of-flight data for the monitors in the runfile.mon_data [IXTdata] object only. It will optionally accept the keywords in the following table:
 
  
−
{| border="1" cellpadding="2"Keyword arguments for mon
+
{| border ="1" cellpadding="2"
−
|-
+
|+ '''Keyword arguments for mon function'''
−
| *Keyword*  || *Parameter Type* || *Brief Description*
+
!width="10%"|Keyword
 +
!width="20%"|Parameter Type  
 +
!width="70%"|Brief Description
 
|-
 
|-
 
| 'period'  || numeric || specifies period default:1, if = 0 then spectra can be defined from more than one period
 
| 'period'  || numeric || specifies period default:1, if = 0 then spectra can be defined from more than one period
 
|-
 
|-
−
|  'mon_map'|| 'string' || specifies a map file, supplied parameter is defines the location of the monitor map file
+
|  'mon_map'|| 'string' or [[IXTmap]] || specifies a map file, supplied parameter is defines the location of the monitor map file
 
|-
 
|-
 
|  'mon_mask'|| 'string' || specifies a mask file, supplied parameter is defines the location of the monitor mask file
 
|  'mon_mask'|| 'string' || specifies a mask file, supplied parameter is defines the location of the monitor mask file
 
|-
 
|-
−
|  'm_rebin'|| ~[xlo,dx,xhi] or ~[x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] || rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
+
|  'm_rebin'|| [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] || rebin parameters are defined according to the '''numerical''' array inputs of [[rebin_x]],[[rebin]] for single datasets
 
|}
 
|}
  
Line 89: Line 67:
  
 
<pre>
 
<pre>
−
>> inst='HET'
 
 
>> run_no= '12345' % run number
 
>> run_no= '12345' % run number
 
>> monitor_mask_file = 'X:\MASKFILES\MON.MASK'
 
>> monitor_mask_file = 'X:\MASKFILES\MON.MASK'
 
>> monitor_map_file = 'X:\MAPFILES\MON.MAP'
 
>> monitor_map_file = 'X:\MAPFILES\MON.MAP'
−
>> rebin_parameters = ~[1000,100,20000]
+
>> rebin_parameters = [1000,100,20000]
−
>> runfile = mon(dso,inst,run_no,'mon_map',monitor_map_file,'mon_mask',monitor_mask_file,'m_rebin',rebin_parameters)
+
>> runfile = mon(dso,run_no,'mon_map',monitor_map_file,'mon_mask',monitor_mask_file,'m_rebin',rebin_parameters)
 
</pre>
 
</pre>
  
−
!! spec
+
=== spec ===
−
This function populates an [IXTrunfile] object with the raw time-of-flight data for the detectors in the runfile.det_data [IXTdata] object only. It will optionally accept the keywords in the following table:
 
  
−
<?plugin OldStyleTable caption="Keyword arguments for spec" border||=2
+
This function populates an [[IXTrunfile]] object with the raw time-of-flight data for the detectors in the runfile.det_data [IXTdata] object only. It will optionally accept the keywords in the following table:
−
|<  *Keyword*  |^ *Parameter Type* |^ *Brief Description*
+
 
−
|< 'period'  |^ numeric |< specifies period default:1, if = 0 then spectra can be defined from more than one period
+
{| border ="1" cellpadding="2"
−
|< 'det_map'|^ 'string' |< specifies a map file, supplied parameter is defines the location of the detector map file
+
|+ '''Keyword arguments for spec function'''
−
|<  'det_mask'|^ 'string' |< specifies a mask file, supplied parameter is defines the location of the detector mask file
+
!width="10%"|Keyword
−
|< 'd_rebin'|^ ~[xlo,dx,xhi] or ~[x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] |< specifies rebinning of data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
+
!width="20%"|Parameter Type  
−
|< 'd_int'|^ ~[xlo,xhi] |< specifies limits for integration of the dataset between two limits, 'd_int' *cannot* be supplied with 'd_rebin'
+
!width="70%"|Brief Description
−
|< 'background'|^ ~[xlo,xhi] |< specifies a background subtraction, the supplied parameter is a numerical array defining the background integration range in time-of-flight
+
|-
−
?>
+
| 'period'  ||numeric ||specifies period default:1, if = 0 then spectra can be defined from more than one period
 +
|-
 +
| 'det_map' or ||'string' or [[IXTmap]] ||specifies a map file, supplied parameter is defines the location of the detector map file
 +
|-
 +
| 'det_mask'||'string' ||specifies a mask file, supplied parameter is defines the location of the detector mask file
 +
|-
 +
| 'd_rebin'||[xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] ||specifies rebinning of data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
 +
|-
 +
| 'd_int'||[xlo,xhi] ||specifies limits for integration of the dataset between two limits, 'd_int' *cannot* be supplied with 'd_rebin'
 +
|-
 +
| 'background'||[xlo,xhi] ||specifies a background subtraction, the supplied parameter is a numerical array defining the background integration range in time-of-flight
 +
|}
  
 
An example sequence of commands is shown below.
 
An example sequence of commands is shown below.
  
 
<pre>
 
<pre>
−
>> inst='MAP'
 
 
>> run_no= '54321' % run number
 
>> run_no= '54321' % run number
 
>> detector_mask_file = 'X:\MASKFILES\DET.MASK'
 
>> detector_mask_file = 'X:\MASKFILES\DET.MASK'
 
>> detector_map_file = 'X:\MAPFILES\DET.MAP'
 
>> detector_map_file = 'X:\MAPFILES\DET.MAP'
−
>> rebin_parameters = ~[1000,100,20000]
+
>> rebin_parameters = [1000,100,20000]
−
>> bgrd = ~[12000,18000]
+
>> bgrd =[12000,18000]
−
>> runfile = spec(dso,inst,run_no,'det_map',detector_map_file,'det_mask',detector_mask_file,'d_rebin',rebin_parameters)
+
>> runfile = spec(dso,run_no,'det_map',detector_map_file,'det_mask',detector_mask_file,'d_rebin',rebin_parameters)
 
</pre>
 
</pre>
  
−
!! pop_full
+
=== pop_full ===
 +
 
  
−
This function populates an [IXTrunfile] object with the raw time-of-flight data for the detectors in the runfile.det_data [IXTdata] object only. It will optionally accept the keywords in the following table:
+
This function populates an [[IXTrunfile]] object with the raw time-of-flight data for the detectors in the runfile.det_data [IXTdata] object only. It will optionally accept the keywords in the following table:
  
−
<?plugin OldStyleTable caption="Keyword arguments for pop_full" border||=2
+
{| border ="1" cellpadding="2"
−
|<  *Keyword*  |^ *Parameter Type* |^ *Brief Description*
+
|+ '''Keyword arguments for pop_full function'''
−
|< 'period'  |^ numeric |< specifies period default:1, if = 0 then spectra can be defined from more than one period
+
!width="10%"|Keyword
−
|< 'mon_map'|^ 'string' |< specifies a monitor map file, supplied parameter is defines the location of the monitor map file
+
!width="20%"|Parameter Type  
−
|<  'mon_mask'|^ 'string' |< specifies a monitor mask file, supplied parameter is defines the location of the monitor mask file
+
!width="70%"|Brief Description
−
|<  'm_rebin'|^ ~[xlo,dx,xhi] or ~[x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] |<  specifies rebinning of monitor data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
+
|-
−
|< 'det_map'|^ 'string' |< specifies a detector map file, supplied parameter is defines the location of the detector map file
+
|'period'  || numeric || specifies period default:1, if = 0 then spectra can be defined from more than one period
−
|<  'det_mask'|^ 'string' |< specifies a detector mask file, supplied parameter is defines the location of the detector mask file
+
|-
−
|<  'd_rebin'|^ ~[xlo,dx,xhi] or ~[x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] |< specifies rebinning of detector data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
+
| 'mon_map' or ||'string' or [[IXTmap]] ||specifies a monitor map file, supplied parameter is defines the location of the monitor map file
−
|<  'd_int'|^ ~[xlo,xhi] |< specifies limits for integration of the dataset between two limits, 'd_int' *cannot* be supplied with 'd_rebin'
+
|-
−
|<  'background'|^ ~[xlo,xhi] |< specifies a background subtraction, the supplied parameter is a numerical array defining the background integration range in time-of-flight
+
|'mon_mask'|| 'string' ||specifies a monitor mask file, supplied parameter is defines the location of the monitor mask file
−
?>
+
|-
 +
|'m_rebin'|| [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] || specifies rebinning of monitor data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
 +
|-
 +
| 'det_map' or ||'string' or [[IXTmap]] ||specifies a detector map file, supplied parameter is defines the location of the detector map file
 +
|-
 +
|'det_mask'|| 'string' || specifies a detector mask file, supplied parameter is defines the location of the detector mask file
 +
|-
 +
|'d_rebin'|| [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] || specifies rebinning of detector data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
 +
|-
 +
|'d_int'|| [xlo,xhi] || specifies limits for integration of the dataset between two limits, 'd_int' *cannot* be supplied with 'd_rebin'
 +
|-
 +
|'background'|| [xlo,xhi] || specifies a background subtraction, the supplied parameter is a numerical array defining the background integration range in time-of-flight
 +
|}
  
 
An example sequence of commands is shown below.
 
An example sequence of commands is shown below.
  
 
<pre>
 
<pre>
−
>> inst='MAP'
 
 
>> run_no= '54321' % run number
 
>> run_no= '54321' % run number
 
>> monitor_mask_file = 'X:\MASKFILES\MON.MASK'
 
>> monitor_mask_file = 'X:\MASKFILES\MON.MASK'
 
>> monitor_map_file = 'X:\MAPFILES\MON.MAP'
 
>> monitor_map_file = 'X:\MAPFILES\MON.MAP'
−
>> mon_rebin_parameters = ~[1000,100,20000]
+
>> mon_rebin_parameters = [1000,100,20000]
 
>> detector_mask_file = 'X:\MASKFILES\DET.MASK'
 
>> detector_mask_file = 'X:\MASKFILES\DET.MASK'
 
>> detector_map_file = 'X:\MAPFILES\DET.MAP'
 
>> detector_map_file = 'X:\MAPFILES\DET.MAP'
−
>> det_rebin_parameters = ~[1000,100,20000]
+
>> det_rebin_parameters = [1000,100,20000]
−
>> bgrd = ~[12000,18000]
+
>> bgrd = [12000,18000]
−
>> runfile = pop_full(dso,inst,run_no,'mon_map',monitor_map_file,'mon_mask',monitor_mask_file,'m_rebin',mon_rebin_parameters, ...
+
>> runfile = pop_full(dso,run_no,'mon_map',monitor_map_file,'mon_mask',monitor_mask_file,'m_rebin',mon_rebin_parameters, ...
 
                                       'det_map',detector_map_file,'det_mask',detector_mask_file,'d_rebin',det_rebin_parameters)
 
                                       'det_map',detector_map_file,'det_mask',detector_mask_file,'d_rebin',det_rebin_parameters)
 
</pre>
 
</pre>
  
  
−
!! homer
+
=== homer ===
 +
 
 
The homer command is a special version of the populate command in which extra normalisation keywords can be supplied with a fixed set of associated parameters.
 
The homer command is a special version of the populate command in which extra normalisation keywords can be supplied with a fixed set of associated parameters.
  
−
<?plugin OldStyleTable caption="Keyword arguments for homer" border||=2
+
{| border ="1" cellpadding="2"
−
|<  *Keyword*  |^ *Parameter Type* |^ *Brief Description*
+
|+ '''Keyword arguments for homer function'''
−
|< 'period'  |^ numeric |< specifies period default:1, if = 0 then spectra can be defined from more than one period
+
!width="10%"|Keyword
−
|< 'mon_map'|^ 'string' |< specifies a monitor map file, supplied parameter is defines the location of the monitor map file
+
!width="20%"|Parameter Type  
−
|<  'mon_mask'|^ 'string' |< specifies a monitor mask file, supplied parameter is defines the location of the monitor mask file
+
!width="70%"|Brief Description
−
|< 'm_rebin'|^ ~[xlo,dx,xhi] or ~[x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] |<  specifies rebinning of monitor data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
+
|-
−
|< 'det_map'|^ 'string' |< specifies a detector map file, supplied parameter is defines the location of the detector map file
+
| 'period'  || numeric || specifies period default:1, if = 0 then spectra can be defined from more than one period
−
|<  'det_mask'|^ 'string' |< specifies a detector mask file, supplied parameter is defines the location of the detector mask file
+
|-
−
|< 'd_rebin'|^ ~[xlo,dx,xhi] or ~[x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] |< specifies rebinning of detector data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets. 'd_rebin' *cannot* be supplied with 'd_int'
+
|'ei'  || real || defines estimate of incident energy (meV)
−
|<  'background'|^ ~[xlo,xhi] |< specifies a background subtraction, the supplied parameter is a numerical array defining the background integration range in time-of-flight
+
|-
−
|<  'ei'  |^ real |< defines estimate of incident energy (meV)
+
| ||'white'  || specifies treatment as a white beam
−
|<  |^ 'white'  |< specifies treatment as a white beam
+
|-
−
|<  'fixei' |^ real |< specifies a known incident energy, so that ei determination is not necessary
+
|'fixei' || real  || specifies a known incident energy, so that ei determination is not necessary
−
|<  'normalisation'  |^ integer |<  value specifies workspace number of monitor used in normalisation ~[default 1]
+
|-
−
|<    |^  'uahr'    |< specifies normalisation by microamp hours, *'range' keyword cannot be specified if this parameter is defined*
+
| 'mon_map' or ||'string' or [[IXTmap]] || specifies a monitor map file, supplied parameter is defines the location of the monitor map file
−
|<  'range'  |^ ~[xlo,xhi] |< specifies range of integration for normalisation, using monitor workspace defined by 'normalisation' and declared in the units defined in 'mon_units'
+
|-
−
|<              |^ 'peak'    |< specifies to use the area determined by peak search in the monitor defined by 'normalisation' close to the value of either 'ei' or 'fixei', only valid if 'ei' numeric, not if 'white'
+
|'mon_mask'|| 'string' || specifies a monitor mask file, supplied parameter is defines the location of the monitor mask file
−
 
+
|-
−
|<  'mon_units'  |^ [units code]    |< specifies output units of monitor data, *only* if you want to change from time-of-flight
+
| 'mon_units'  || [units code]    || specifies output units of monitor data
−
|<  'det_units'  |^ [units code]    |< specifies output units of detector data, *only* if you want to change from time-of-flight
+
|-
−
|<  'd_int'|^ ~[xlo,xhi] |< specifies limits for integration of the dataset between two limits, if 'det_units' has been supplied then integration will take place after units conversion, 'd_int' *cannot* be supplied with 'd_rebin'
+
|'m_rebin'|| [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] || specifies rebinning of monitor data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
−
|<  'scale'  |^    |< specifies units of normalisation ie per 1e6 counts or per 1000uAhrs ~[default 1]
+
|-
−
|<  'solid'  |^ [IXTrunfile]    |< Specifies a solid angle correction, the supplied parameter *must* be a white beam [IXTrunfile] object which has been integrated for every spectrum (i suppose one could also just provide a run number....)
+
| 'det_map' or ||'string' or [[IXTmap]] ||specifies a detector map file, supplied parameter is defines the location of the detector map file
−
|<  'corr'  |^  logical  |< Specifies detector efficiency correction and kf/ki correction will be applied ~[default false]
+
|-
−
?>
+
|'det_mask'|| 'string' || specifies a detector mask file, supplied parameter is defines the location of the detector mask file
−
 
+
|-
−
 
+
|'det_units' || [units code]    || specifies output units of detector data
−
see also: [Creating Datasets], [Arrays of Datasets], [Mathematical Functions and Operators], [Other Matlab Utilities],    [Input and Output Functions], [Dataset Manipulation and Conversion Functions]
+
|-
−
 
+
|'d_rebin'|| [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] || specifies rebinning of detector data, rebin parameters are defined according to the '''numerical''' array inputs of [rebin_x],[rebin] for single datasets. 'd_rebin' '''cannot''' be supplied with 'd_int'
−
------
+
|-
 +
|'d_int'|| [xlo,xhi] || specifies limits for integration of the dataset between two limits, if 'det_units' has been supplied then integration will take place after units conversion, 'd_int' '''cannot''' be supplied with 'd_rebin'. limits are specified in the units of the data, therefore if your output units are 'w' then your integration limits are specified in meV. if no units are specified then the limits are in time (microseconds)
 +
|-
 +
|'background'|| [xlo,xhi] || specifies a background subtraction, the supplied parameter is a numerical array defining the background integration range in time-of-flight
 +
|-
 +
|'normalisation'  || integer || value specifies workspace number of monitor used in normalisation [default 1]
 +
|-
 +
|  ||'uahr'    || specifies normalisation by microamp hours, ''''range' keyword cannot be specified if this parameter is defined'''
 +
|-
 +
|'range'  || [xlo,xhi] || specifies range of integration for normalisation, using monitor workspace defined by 'normalisation' and declared in the units defined in 'mon_units'
 +
|-
 +
|  || 'peak'    || specifies to use the area determined by peak search in the monitor defined by 'normalisation' close to the value of either 'ei' or 'fixei', only valid if 'ei' numeric, not if 'white'
 +
|-
 +
|'scale'  || real || specifies units of normalisation ie per 1e6 counts or per 1000uAhrs [default 1]
 +
|-
 +
|'solid'  || [IXTrunfile]    || Specifies a solid angle correction, the supplied parameter '''must''' be a white beam [IXTrunfile] object which has been integrated for every spectrum (i suppose one could also just provide a run number....)
 +
|-
 +
|'corr'  || logical  || Specifies detector efficiency correction and kf/ki correction will be applied [default false]
 +
|-
 +
|'abs'  || real  || absolute units scaling factor
 +
|-
 +
|'mass' || real  || mass of sample
 +
|-
 +
|'RMM' || real || relative molecular mass of sample
 +
|}

Latest revision as of 14:12, 12 August 2008

Preparing the IXTdata_source

All the population routines descirbed here use the IXTdata_source object. The IXTdata_source object is used to define source files for the population of an IXTrunfile object. Different source files can be added to the IXTdata_source object with their own special commands:

It is necessary to define the type of instrument you are using in the IXTdata_source object, of course only one instrument can be defined for population to work as you would expect. This affects how the IXTrunfile is populated, and the current options are as follows

IXTmap and IXTmask files

Different instruments generally have their own map files associated with them, but it is also possible to create IXTmap and IXTmask from the matlab command line

Populating IXTrunfile

There are three standard ways to populate an IXTrunfile object, all require an IXTdata_source object which has had the type of instrument defined in it ie. chopper or diffraction instrument. As well as simply loading data from a raw file the data can generally be optionally masked/mapped/rebinned using an argument to the population function as a keyword with an associated parameter (eg. a map/mask file, rebin parameters etc.)

  • For any of these functions to run properly the matlab environment must be prepared by calling the instrument setup scripts.
  • If a map/mask/raw file is provided as a command line argument, then it will override any specification already defined in the [IXTdata_source] object.
  • If no map files are defined, either on the command line or in the IXTdata_source object then a 1:1 mapping with _all_ spectra will be created by default. If no mask files are defined then all spectra will be included in the workspaces.

The standard construction for these population routines is as follows. 

>> RF=pop_fun(DSO,  run_no, 'keyword_1', parameter_1,..., 'keyword_N',parameter_N)

For any of these functions to run properly the matlab environment must be prepared by calling the instrument setup scripts.


  • RF is an IXTrunfile object
  • DSO is an IXTdata_source object which contains an instrument type definition
  • pop_fun can be either _mon,spec,pop_full,homer_
  • raw file specification does not use a keyword, it is built up from the standard instrument abbreviation (eg. HRP, MAR, SRF etc.) and the run number automatically according to which setup file has been run. If this has not been run then the script will fail and tell you
  • keywords are always character strings and each keyword must be followed by a parameter
  • values can take any appropriate type
  • map files have a designated Map File Format
  • mask files have a designated Mask File Format


mon

This function populates an IXTrunfile object with the raw time-of-flight data for the monitors in the runfile.mon_data [IXTdata] object only. It will optionally accept the keywords in the following table:

Keyword arguments for mon function
Keyword Parameter Type Brief Description
'period' numeric specifies period default:1, if = 0 then spectra can be defined from more than one period
'mon_map' 'string' or IXTmap specifies a map file, supplied parameter is defines the location of the monitor map file
'mon_mask' 'string' specifies a mask file, supplied parameter is defines the location of the monitor mask file
'm_rebin' [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] rebin parameters are defined according to the numerical array inputs of rebin_x,rebin for single datasets

An example sequence of commands is shown below. 

>> run_no= '12345' % run number
>> monitor_mask_file = 'X:\MASKFILES\MON.MASK'
>> monitor_map_file = 'X:\MAPFILES\MON.MAP'
>> rebin_parameters = [1000,100,20000]
>> runfile = mon(dso,run_no,'mon_map',monitor_map_file,'mon_mask',monitor_mask_file,'m_rebin',rebin_parameters)

spec

This function populates an IXTrunfile object with the raw time-of-flight data for the detectors in the runfile.det_data [IXTdata] object only. It will optionally accept the keywords in the following table:

Keyword arguments for spec function
Keyword Parameter Type Brief Description
'period' numeric specifies period default:1, if = 0 then spectra can be defined from more than one period
'det_map' or 'string' or IXTmap specifies a map file, supplied parameter is defines the location of the detector map file
'det_mask' 'string' specifies a mask file, supplied parameter is defines the location of the detector mask file
'd_rebin' [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] specifies rebinning of data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
'd_int' [xlo,xhi] specifies limits for integration of the dataset between two limits, 'd_int' *cannot* be supplied with 'd_rebin'
'background' [xlo,xhi] specifies a background subtraction, the supplied parameter is a numerical array defining the background integration range in time-of-flight

An example sequence of commands is shown below. 

>> run_no= '54321' % run number
>> detector_mask_file = 'X:\MASKFILES\DET.MASK'
>> detector_map_file = 'X:\MAPFILES\DET.MAP'
>> rebin_parameters = [1000,100,20000]
>> bgrd =[12000,18000]
>> runfile = spec(dso,run_no,'det_map',detector_map_file,'det_mask',detector_mask_file,'d_rebin',rebin_parameters)

pop_full

This function populates an IXTrunfile object with the raw time-of-flight data for the detectors in the runfile.det_data [IXTdata] object only. It will optionally accept the keywords in the following table:

Keyword arguments for pop_full function
Keyword Parameter Type Brief Description
'period' numeric specifies period default:1, if = 0 then spectra can be defined from more than one period
'mon_map' or 'string' or IXTmap specifies a monitor map file, supplied parameter is defines the location of the monitor map file
'mon_mask' 'string' specifies a monitor mask file, supplied parameter is defines the location of the monitor mask file
'm_rebin' [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] specifies rebinning of monitor data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
'det_map' or 'string' or IXTmap specifies a detector map file, supplied parameter is defines the location of the detector map file
'det_mask' 'string' specifies a detector mask file, supplied parameter is defines the location of the detector mask file
'd_rebin' [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] specifies rebinning of detector data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
'd_int' [xlo,xhi] specifies limits for integration of the dataset between two limits, 'd_int' *cannot* be supplied with 'd_rebin'
'background' [xlo,xhi] specifies a background subtraction, the supplied parameter is a numerical array defining the background integration range in time-of-flight

An example sequence of commands is shown below. 

>> run_no= '54321' % run number
>> monitor_mask_file = 'X:\MASKFILES\MON.MASK'
>> monitor_map_file = 'X:\MAPFILES\MON.MAP'
>> mon_rebin_parameters = [1000,100,20000]
>> detector_mask_file = 'X:\MASKFILES\DET.MASK'
>> detector_map_file = 'X:\MAPFILES\DET.MAP'
>> det_rebin_parameters = [1000,100,20000]
>> bgrd = [12000,18000]
>> runfile = pop_full(dso,run_no,'mon_map',monitor_map_file,'mon_mask',monitor_mask_file,'m_rebin',mon_rebin_parameters, ...
                                      'det_map',detector_map_file,'det_mask',detector_mask_file,'d_rebin',det_rebin_parameters)


homer

The homer command is a special version of the populate command in which extra normalisation keywords can be supplied with a fixed set of associated parameters.

Keyword arguments for homer function
Keyword Parameter Type Brief Description
'period' numeric specifies period default:1, if = 0 then spectra can be defined from more than one period
'ei' real defines estimate of incident energy (meV)
'white' specifies treatment as a white beam
'fixei' real specifies a known incident energy, so that ei determination is not necessary
'mon_map' or 'string' or IXTmap specifies a monitor map file, supplied parameter is defines the location of the monitor map file
'mon_mask' 'string' specifies a monitor mask file, supplied parameter is defines the location of the monitor mask file
'mon_units' [units code] specifies output units of monitor data
'm_rebin' [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] specifies rebinning of monitor data, rebin parameters are defined according to the *numerical* array inputs of [rebin_x],[rebin] for single datasets
'det_map' or 'string' or IXTmap specifies a detector map file, supplied parameter is defines the location of the detector map file
'det_mask' 'string' specifies a detector mask file, supplied parameter is defines the location of the detector mask file
'det_units' [units code] specifies output units of detector data
'd_rebin' [xlo,dx,xhi] or [x_1,dx_1,x_2,dx_2,...,x_n,dx_n,x_n+1] specifies rebinning of detector data, rebin parameters are defined according to the numerical array inputs of [rebin_x],[rebin] for single datasets. 'd_rebin' cannot be supplied with 'd_int'
'd_int' [xlo,xhi] specifies limits for integration of the dataset between two limits, if 'det_units' has been supplied then integration will take place after units conversion, 'd_int' cannot be supplied with 'd_rebin'. limits are specified in the units of the data, therefore if your output units are 'w' then your integration limits are specified in meV. if no units are specified then the limits are in time (microseconds)
'background' [xlo,xhi] specifies a background subtraction, the supplied parameter is a numerical array defining the background integration range in time-of-flight
'normalisation' integer value specifies workspace number of monitor used in normalisation [default 1]
'uahr' specifies normalisation by microamp hours, 'range' keyword cannot be specified if this parameter is defined
'range' [xlo,xhi] specifies range of integration for normalisation, using monitor workspace defined by 'normalisation' and declared in the units defined in 'mon_units'
'peak' specifies to use the area determined by peak search in the monitor defined by 'normalisation' close to the value of either 'ei' or 'fixei', only valid if 'ei' numeric, not if 'white'
'scale' real specifies units of normalisation ie per 1e6 counts or per 1000uAhrs [default 1]
'solid' [IXTrunfile] Specifies a solid angle correction, the supplied parameter must be a white beam [IXTrunfile] object which has been integrated for every spectrum (i suppose one could also just provide a run number....)
'corr' logical Specifies detector efficiency correction and kf/ki correction will be applied [default false]
'abs' real absolute units scaling factor
'mass' real mass of sample
'RMM' real relative molecular mass of sample
Retrieved from "http://libisis.org/index.php?title=Homer_and_mgenie_style_functions&oldid=2644"