Calibration

The calibration system is essentially based on the concept of index files. An index file is a data file containing information on all calibration observation reduced by the pipeline. A separate index file is created for each calibration sub-system (e.g. one for dark observations, one for skydip observations etc) with the convention is that each index file is stored in ORAC_DATA_OUT and prefixed with the string index (e.g. index.dark, index.skydip etc.). It is the responsibility of a primitive (usually a complete recipe is dedicated to the calibration observation) to file a calibration to an index file. The index file can be used simply to register a file name (e.g. the name of a dark file or flatfield) or a calibration result (the current sky opacity or flux conversion factor). Methods are provided in the ORAC::Index class for retrieving this information from the index file⁹

The index object is responsible for searching the relevant index file and returning the most suitable calibration. This is achieved by the use of external rules files (stored in ORAC_DATA_CAL called rules.CALIBRATION_NAME) which list which header keywords are relevant and should be checked against the headers of the current frame. This means that the calibration object itself does not need to worry about searching the index file or reading the rules files.

An example rules file could look like:

# Example rules file for SCUBA skydips
MODE eq 'SKYDIP'
FILTER eq $Hdr{FILTER}
WAVE == $Hdr{WAVE}
TAUZ
ORACTIME ; abs(ORACTIME - $Hdr{ORACTIME}) < 0.5

The format is intended to be fairly simple as it should be possible for a non-programmer to edit it. The main points are:

• # is the comment character. Anything after a comment within a line is ignored.
• Blank lines are ignored.
• Each line in the rules file is translated to the Perl code and evaluated. If it returns `true' the value in the index file (keyed by the first word in the rules file) matches the coresponding values in the header of the current frame. For example, the second rule is translated into the following code (assuming the current index entry contains the filter name of "850W").

  if ( '850W' eq $Hdr{FILTER} ) {
     # Rules passes
  }
  

  and the last line in the above rules file could be translated to the following if statement (using ORACTIME of 19990827.55 for the index entry):

  '19990827.55'; abs(19990827.55 - $Hdr{ORACTIME}) < 0.5
  

  which returns true if the ORACTIME stored in the index is within half a day of the value stored in the current frame object (%Hdr is a hash read from the current frame header). The semi-colon is used to separate the Perl code into two statements. The return value of the eval is that of the second statement. This is required for cases that are not simply `A == B' format.
• When using complex rules the substituted index value (ORACTIME in the above example) is only quoted when placed as the first statement. When in the body of the rule it must be quoted if the value is not a number. This is because the value itself is placed into the rule rather than a variable containing the value.
• Lines which only contain a keyword, are place holders indicating that the information should be present in the index file but not used. Care must be taken that the value of the corresponding keyword can never be zero since that would return false to the rules system. If this is the case a rule of

  KEYWORD ; 1
  

  can be used instead since in this case the test will always return true.