.ec _
.ll 76
.ad b
.in 4
.\"====================================================================
.ti -4
1 Language
.ce
MRTCAL_\ Command Language Summary

.nf
CALIBRATE: Calibrate a single file
INDEX    : Build/read the index of the IMB-FITS files
MCOPY    : Copy the index to a file
MDUMP    : DUMP the content of the Mrtcal buffers
MFIND    : Select entries from index file
MLIST    : List the files selected by the FIND command
MSETUP   : Tune some program behaviours
MUPDATE  : Update the index and IMB-FITS files from buffers
MWRITE   : WRITE the class data format 
PIPELINE : Calibrate the Current indeX
READ     : READ IMBFITS file
SOLVE    : SOLVE for the pointing/focus/skydip parameters
VARIABLE : Add Sic variables mapping internal buffers
.fi
.\"====================================================================
.ti -4
1 CALIBRATE
.ti +4
[MRTCAL_\]CALIBRATE Num[.Ver] [/WITH Num[.Ver]]

Calibrate the file indentified by its Number. The calibration scan is
chosen implicitly by the command, except if explicitly specified
through the option /WITH.

Boths file numbers can be added a Version number. If not given, the
latest version is selected.
.\"====================================================================
.ti -4
1 INDEX
.ti +4
[MRTCAL_\]INDEX [BUILD|UPDATE|OPEN|APPEND|WATCH|CONVERT [DirName]]
[/FILE IndexFile] [/RECURSIVE] [/PATTERN String] [/DATE DateString]
[/TIMEOUT Value]

This commands creates, updates, or opens a file index (database) of
IMB-FITS files, for later use by the commands MFIND and/or
CALIBRATE.
.in +4
.ti -2
-_ BUILD creates or rebuilds the index file from scratch, overwriting
the previous one if any,
.ti -2
- UPDATE creates or updates the index file if it already exists,
.ti -2
- OPEN opens the index file,
.ti -2
- APPEND appends in memory another index file,
.ti -2
- OUTPUT select the index file used for writing new entries,
.ti -2
-_ WATCH waits for new files to appear in the IMB-FITS directory,
and index them (INDEX UDPATE) as soon as one new is found.
.ti -2
-_ CONVERT converts the index file to the latest known version (if
relevant).
.in -4
BUILD and UPDATE will implicitly OPEN the index file after creating
it. The default is to open the index of the current working directory.

By default, the index file created/searched as 'index.mrt' in the
directory where the IMB-FITS files are (DirName). However, if user has
no right (e.g. write access) to put the index file in this directory,
he can override this default and give any IndexFile name (with its
path). In this case, it is his responsibility to ensure a correct
DirName/IndexFile match. For clarity reasons, the default should be
prefered when possible.
.\"--------------------------------------------------------------------
.ti -4
2 UPDATE
.ti +4
[MRTCAL_\]INDEX UPDATE [DirName] [/PATTERN String] [DATE DateString]

Build or update the index of the IMB-FITS files. The index is stored
in a binary file named 'index.mrt'. The command implicitly performs an
INDEX OPEN right after the UPDATE to allow direct use of the index.

The index lists all the files named 'iram30m-*-*s*-imb.fits' in the
directory, including unreadable and incomplete (in terms of number of
subscans) ones. Selection is made from this list with the various
options and features of the commands using this list.

The command can be called several times. The index file is updated if
needed, in particular if the file readability has improved (e.g. scan
has been completed).

By default, the command searches for the IMB-FITS files in the current
working directory. This can be overriden thanks to the option
/DIRECTORY. Note that the index file is always created in the same
directory of the files it lists (write access is thus
needed). Directory search is not recursive.
.\"--------------------------------------------------------------------
.ti -4
2 OPEN
.ti +4
[MRTCAL_\]INDEX OPEN [DirName]

Load the index in memory, for subsequent use by the commands FIND
and/or CALIBRATE. Default is to open the index of the current working
directory.
.\"--------------------------------------------------------------------
.ti -4
2 OUTPUT
.ti +4
[MRTCAL_\]INDEX OUTPUT [DirName] [/FILE IndexFile]

Append a new index file in memory (i.e. appended to the Input indeX)
and make it the default for writing new entries (i.e. entries saved
after a calibration). This index file is thus in-out.

By default, the new entries are saved in the same index file they come
from. If you want to keep the original index file unmodified (e.g. if
you have no write access), use this command to select another output
file. This output index destination is reset by commands which fully
reset the Input indeX, namely INDEX OPEN and INDEX BUILD.

Note that if you mix several directories in the Input indeX, it
becomes a non-sense to use a unique index file as output (you will get
lost when reopening it). This command is basically protected against
this situation.
.\"--------------------------------------------------------------------
.ti -4
2 WATCH
.ti +4
[MRTCAL_\]INDEX WATCH [/TIMEOUT Value]

Wait for new files added in the directory associated to the input
index. As soon as new data is detected, the index is updated (same as
INDEX UPDATE) and the command returns. There are 3 major waiting
modes:
.in +4
.ti -2
- INDEX WATCH: wait indefinitely,
.ti -2
- INDEX WATCH /TIMEOUT Value>0: wait until this time (in seconds) is
elapsed, and then return normally. Note that you can mimic an infinite
loop by setting a huge value (1 year is ~3e7 seconds),
.ti -2
- INDEX WATCH /TIMEOUT Value<=0: does not wait. This can be useful
when writing generic code including time-outs.
.in -4

The waiting loop can also be stopped with CTRL-C. In this case the
command will return with an error status.
.\"--------------------------------------------------------------------
.ti -4
2 CONVERT
.ti +4
[MRTCAL_\]INDEX CONVERT [/FILE IndexFile]

Check if the index file version is the latest possible. If not, the
associated file on disk is automatically converted. The original file
is backup'ed to another name.

While index file version has very seldom evolutions, when this happens
it is necessary to convert 'old' files opened in UPDATE mode
beforehand, as MRTCAL writes only in latest version files.
.\"--------------------------------------------------------------------
.ti -4
2 /PATTERN
.ti +4
[MRTCAL_\]INDEX [BUILD|UPDATE|WATCH [DirName]] [/FILE IndexFile]
[/RECURSIVE] /PATTERN String

The option /PATTERN allows to indicate which files should be
indexed. Default is 'iram30m-*-*s*-imb.fits', i.e. all the IMB-FITS
files in the directory, but this can be restricted with other
patterns. Note that file names matter in Mrtcal: basically you can not
index a file which do not match the default pattern above.

For best portability, you should use a sh-compatible syntax.
.\"--------------------------------------------------------------------
.ti -4
2 /DATE
.ti +4
[MRTCAL_\]INDEX [BUILD|UPDATE|WATCH [DirName]] [/FILE IndexFile]
[/RECURSIVE] /DATE [List1] [List 2] ... [ListN]

The option /DATE allows to restrict the files to be indexed for a
date or list of dates.

A list has the form "Date1 [TO Date2]". Typical uses are:
.nf
  /DATE Date: select this unique date,
  /DATE Date1 Date2 Date3: select those 3 scalar dates,
  /DATE Date1 TO Date2: select this range of dates,
  /DATE Date1 Date2 Date3 TO Date4: select these dates (Date1,
    Date2) or range of dates (Date3 to Date4).
.fi

Accepted formats are:
.ti +4
- DD-MMM-YYYY (MMM as letters),
.ti +4
- YYYYMMDD (all numbers),
.ti +4
- Keyword "TODAY" or "YESTERDAY".
.\"====================================================================
.ti -4
1 MCOPY
.ti +4
[MRTCAL_\]MCOPY [IN|CURRENT] /FILE IndexFile

Copy the named index (default current) from memory to the given file
to disk. Any pre-existing file is overwritten, except that you can not
overwrite one of the input index files involved during this operation.

This command is useful for a few main purposes:
.in +4
.ti -2
-_ extract a subset from an index file, by combining the commands
INDEX OPEN, MFIND (with criteria), and MCOPY,
.ti -2
-_ merge several index files, by combining INDEX OPEN, INDEX APPEND
(repeated), MFIND, MCOPY,
.ti -2
-_ convert an old format file to latest format, simply by using INDEX
 OPEN, MCOPY IN.
.in -4
.\"====================================================================
.ti -4
1 MDUMP
.ti +4
[MRTCAL_\]MDUMP [/OUTPUT LogFile]
.ti +4
[MRTCAL_\]MDUMP ALL|SUMMARY|SUBSCANS|HduName|DATA [/OUTPUT LogFile]
.ti +4
[MRTCAL_\]MDUMP HduName ColumnName [/OUTPUT LogFile]

Display the content of all or one section from the internal memory
buffers. Default section is ALL sections.

One of the following section can be used:
.ti +2
- ALL is a shortcut for SUMMARY + SUBSCANS + the HDUs list
.in +4
.ti -2
-_ SUMMARY displays a short summary of the file contents, and
equivalence classes of the subscans (i.e. grouped by categories).
.in -4
.ti +2
- SUBSCANS shows a list of the subscans with their observing types,
.ti +2
- HduName can be one of the following names:
.ti +6
PRIMARY, SCAN, FRONTEND, BACKEND, DEROT
.ti +6
BACKDATA, ANTSLOW, ANTFAST (of the current subscan)
.in +4
.ti -2
- DATA shows a summary of the current subset of the DATA column for
the current subscan. It also shows how this data is mapped into
chunksets.
.in -4

If an HDU name is requested, the header keys are displayed (key +
value + comment), and the table columns are summarized (key + a few
values + comment from associated TTYPE). If the HDU name is followed
by a column name, the full column contents is displayed.

Note that the internal IMB-FITS reader may apply patches at read time
(e.g.  old headers are patched to mimic the latest IMB-FITS
format). In other words, what MDUMP shows in not exactly the FITS
contents, but what the calibration engines use. In case of patch, the
comments are replaced by a warning message with a brief explanation.
.\"--------------------------------------------------------------------
.ti -4
2 /OUTPUT
.ti +4
[MRTCAL_\]MDUMP [Topic] [SubTopic] /OUTPUT LogFile

The option /OUTPUT will redirect the display to the given
file. Default is on screen (STDOUT).
.\"====================================================================
.ti -4
1 MFIND
.ti +4
[MRTCAL_\]MFIND [/DATE Date] [/SCAN List] [/BACKEND List] [/FRONTEND
List] [/OBSTYPE List] [/SWITCHMODE List] [/SOURCE Name] [/PROJID Id]
[/COMPLETENESS Key] [/CALIBRATED List] [/POLARIMETRY YES|NO]

Select IMB-FITS files from the index file and build the Current Index
in memory. With no options, all files are selected. The options allow
to add one or more selection criteria. Using a wildcard '*' as the
option value makes it uneffective. The number of selected entries is
stored in the variable MFOUND, and the index arrays are available in
the structure MDX%.

.in +4
.ti -2
- /DATE: the date list, various formats are supported (see subtopic
  for details),
.ti -2
- /SCAN: the scan list. See subtopic for details
.ti -2
- /BACKEND: the backend name(s) as known in the IMB-FITS file.
.ti -2
- /FRONTEND: the receiver name(s), in single or dual band. See
  subtopic for details.
.ti -2
- /OBSTYPE: the observation type(s) as known in the IMB-FITS file.
.ti -2
- /SWITCHMODE: the switching mode(s) in the list PSW, WSW, FSW, BSW,
  and UNK(nown).
.ti -2
- /POLARIMETRY: select files with polarimetry data (YES|NO),
.ti -2
- /SOURCE: the source name. Wildcards are allowed in the name.
.ti -2
- /PROJID: the project identifier (character string).  Wildcards are
  allowed in the string.
.ti -2
- /COMPLETENESS: one of the following:
    . YES: select only complete files,
    . NO: select unreadable, empty (0 subscan) or partial (missing
          subscans) files,
    . READABLE: select partial or complete files,
    . UNREADABLE: select only unreadable or empty files
.ti -2
- /CALIBRATED: select by one or several calibration statuses, in NONE,
  DONE, EMPTY, FAILED, or SKIPPED.
.in -4
.\"--------------------------------------------------------------------
.ti -4
2 /SCAN
.ti +4
[MRTCAL_\]MFIND /SCAN [List1] [List 2] ... [ListN]

Scan is selected if its number is found in one of the given lists,
where one list has the form "Val1 [TO Val2]". Typical uses are:
.nf
  /SCAN Val: select this unique value,
  /SCAN Val1 Val2 Val3: select those 3 scalar values,
  /SCAN Val1 TO Val2: select this range of values,
  /SCAN Val1 Val2 Val3 TO Val4: select these values (Val1, Val2) or
    range of values (Val3 to Val4).
.fi
.\"--------------------------------------------------------------------
.ti -4
2 /DATE
.ti +4
[MRTCAL_\]MFIND /DATE [List1] [List 2] ... [ListN]

The file is selected if its scan date, as found in the file name,
matches one of the the given lists. The dates in the lists should be
strings in one of the following formats:
.ti +4
- DD-MMM-YYYY (MMM as letters),
.ti +4
- YYYYMMDD (all numbers),
.ti +4
- Keyword "TODAY" or "YESTERDAY".

A list has the form "Date1 [TO Date2]". Typical uses are:
.nf
  /DATE Date: select this unique date,
  /DATE Date1 Date2 Date3: select those 3 scalar dates,
  /DATE Date1 TO Date2: select this range of dates,
  /DATE Date1 Date2 Date3 TO Date4: select these dates (Date1,
    Date2) or range of dates (Date3 to Date4).
.fi

Note that if the scan was started just before midnight, there can be
subscans on the next day, i.e. calibrated data may have a different
date.
.\"--------------------------------------------------------------------
.ti -4
2 /FRONTEND
.ti +4
[MRTCAL_\]MFIND /FRONTEND [Pattern1] ... [PatternN]

The pattern PatternI accepts 3 forms:
.in +4
.ti -2
Value
.br
A single receiver name. Find single-band observations which used this
receiver.
.ti -2
Value1&Value2
.br
Two receiver names with ampersand (&). Find dual-band observations
which used these two receivers (order does not matter).
.ti -2
Value1|Value2
.br
Two receiver names with pipe (|). Find dual-band observations which
used at least one of these two receivers (order does not matter).
.in -4
The Values can be the exact receiver name (e.g. E090) or some
wildcarded pattern (e.g. E0* matches E090). Use * to match any
receiver.

Several patterns can be passed to the option to find entries matching
several criteria. For example:
.nf
  *           : Find all (and only) single-band observations.
  *&*         : Find all (and only) dual-band observations.
  * *&*       : Find all single-band and all dual-band observations (i.e.
                everything). This is the default.
  E090        : Find single-band observations with E090.
  E090&*      : Find dual-band observations with E090.
  E090 E090&* : Find all observations with E090.
  E090 E230   : Find single-band observations with E090 or E230.
  E090|E230   : Find dual-band observations with E090 or E230.
  E090&E230   : Find dual-band observations with E090 and E230.
.fi
.\"====================================================================
.ti -4
1 MLIST
.ti +4
[MRTCAL_\]MLIST [IN|CURRENT] [/COLUMNS List] [/PAGE] [/FILE
OutputFile]
.ti +4
[MRTCAL_\]MLIST [IN|CURRENT] /TOC Keys [/PAGE] [/VARIABLE VarName]
[/FILE OutputFile]
.ti +4
[MRTCAL_\]MLIST [IN|CURRENT] /POINTING [/FILE OutputFile]

MLIST the content of the given index. MLIST CURRENT refers to the
selection made with the command MFIND. MLIST IN lists all the files
known in the memory index. Default is MLIST CURRENT.

MLIST offers 3 main kind of lists:
.in +4
.ti -2
- Basic (no dedicated option): list the entries in index (one per
line). The columns can be customized with /COLUMNS.
.ti -2
- Table-Of-Contents (/TOC): summarize the entries per group of
properties. See subtopic for details.
.ti -2
- Pointing results (/POINTING): list all the pointing drift solutions
found in the index. There can be 0 (not a pointing) to many solutions
per entries.
.in -4

The output can be redirected to an ASCII file thanks to the option
/FILE. Default is print to STDOUT, continuously (scroll mode, default)
or page by page (option /PAGE).
.\"--------------------------------------------------------------------
.ti -4
2 /TOC
.ti +4
MRTCAL_\MLIST [IN|CURRENT] /TOC [Key1 Key2 ... KeyN] [/VARIABLE
VarName]

MLIST /TOC displays the Table Of Contents of the current index, or of
the input (MLIST IN) index file. A summary of the different values of
each attribute is made, plus a final summary of all the combinations
(setups). The results are accessible in the structure MTOC%. This name
can be customized thanks to the option /VARIABLE. The attributes can
be:
.in +4
- NUMBER: observation number
.br
- VERSION: observation version
.br
- TELESCOPE
.br
- ID
.br
- SOURCE
.br
- OBSERVED
.br
- SCAN
.br
- FRONTEND
.br
- BACKEND
.br
- OBSTYPE
.br
- SWITCHMODE
.br
- POLARIMETRY: file contains polarimetry data
.br
- CALIBRATED: calibration status
.br
- DIRECTORY
.in -4
By default, OBSERVED and SCAN are used.
.\"--------------------------------------------------------------------
.ti -4
2 /COLUMNS
.ti +4
MRTCAL_\MLIST [IN|OUT] /COLUMNS [Attr1 Attr2 ... AttrN]

MLIST /COLUMNS allows to customize the columns displayed. They can be
repeated as many time as desire. Valid values are:
.in +4
- NUMBER
.br
- VERSION
.br
- DIRECTORY
.br
- FITSFILE
.br
- MRTFILE: the index file name
.br
- RECORD: the position in the MRT index file
.br
- WORD: the position in the record
.br
- TELESCOPE
.br
- PROJID
.br
- SOURCE
.br
- OBSERVED
.br
- UT
.br
- LST
.br
- AZIMUTH
.br
- ELEVATION
.br
- POSITION: Lontigude, Latitude, Coordinate system, Equinox
.br
- FRONTEND
.br
- SCAN
.br
- BACKEND
.br
- OBSTYPE
.br
- SWITCHMODE
.br
- POLARIMETRY: file contains polarimetry data
.br
- COMPLETE
.br
- CALIBRATED
.br
- ITIME (last indexation time)
.br
-_ WITH: for a science scan, the Date, Scan, Backend, and Version of
the associated calibration scan used when calibrating.
.br
- RESULTS: results of pointing, focus, calibration scans
.br
- DEFAULT: alias for the default columns
.in -4
.\"====================================================================
.ti -4
1 MSETUP
.ti +4
[MRTCAL_\]MSETUP [INPUT|BOOKKEEPING|CALIBRATION|SOLVE|OUTPUT|PIPELINE|DEBUG]

Tune global 6 different kinds of behaviour for the READ, CALIBRATE and
PIPELINE commands:
.in +4
INPUT: how the command READ reads the data
.br
BOOKKEEPING: how the input data is handled
.br
CALIBRATION: how the calibration is performed
.br
SOLVE: how the solutions are computed
.br
OUTPUT: how the results are exported
.br
PIPELINE: how the pipeline works
.br
DEBUG: which debugging messages are displayed.
.in -4

The MSETUP command without arguments will display the current status
of all these categories. MSETUP CATEGORY without further argument will
display the current status of the named category.
.\"--------------------------------------------------------------------
.ti -4
2 INPUT
.ti +4
[MRTCAL_\]MSETUP INPUT Keyword Switch

[MRTCAL_\]MSETUP INPUT BAD YES|NO

Choose if the command READ should read the bad time dumps (in addition
to the good ones) from the backendXXX tables (including the DATA
column). A bad time dump has a null ISWITCH value, and its associated
data (e.g. MJD, INTEGTIM) are not expected to be correct. Default is
YES.

[MRTCAL_\]MSETUP INPUT BANDWIDTH Value

Setup the desired reading bandwidth in MHz. The nearest value that
allows the division of the good spectra channels of each chunkset in
equal virtual chunk sizes will be used. Exceptions are:
.in +4
.ti -2
-_ if value is 0, use the native hardware chunk size (no subdivision),
.ti -2
-_ if value is larger than the native hardware chunk size, the latter
is used instead (same as 0),
.ti -2
-_ if value is lower than the channel spacing, the latter is used
instead (all channels calibrated individually, use with caution).
.in -4
Default is native chunk size.

[MRTCAL_\]MSETUP INPUT DATA NONE|ONTRACK|ALL

Select how Mrtcal should read the DATA column:
.in +4
.ti -2
-_ NONE: no data is read. Useful to read the other IMB-FITS tables and
avoiding the DATA column which may be large (save time and/or memory).
.ti -2
-_ ONTRACK: read only the on-track part of the DATA column, according
to the subscan start and stop MJDs.
.ti -2
-_ ALL: real the whole DATA column, including the off-track parts.
.in -4
Default is ONTRACK.

[MRTCAL_\]MSETUP INPUT MJDINTER YES|NO

Choose if the command READ should intersect the DATE-OBS and DATE-END
(on-track range) of the subscan with the MJD columns in the tables
Antenna Slow, Antenna Fast, and Backend Data. It may happen that one
of these columns are too short and the data dumps can not be
processed. Setting YES means that the associated dumps in this missing
range won't be considered on-track anymore. Default is NO.

[MRTCAL_\]MSETUP INPUT TOCHUNK YES|NO

Choose if Mrtcal should map the DATA column into chunksets at read
time. NO means that you won't be able to do anything but READing the
raw DATA into the internal buffers, and accessing from the
VARIABLEs. YES is needed for calibration. This is the default.

.\"--------------------------------------------------------------------
.ti -4
2 BOOKKEEPING
.ti +4
[MRTCAL_\]MSETUP BOOKKEPPING SPACE value 

Set the amount (in MB) of RAM memory used to buffer the input backend
data. This allows the user to handle huge data amount on a small computer,
even though it will be slower.
.\"--------------------------------------------------------------------
.ti -4
2 CALIBRATION
.ti +4
[MRTCAL_\]MSETUP CALIBRATION Keyword Switch

[MRTCAL_\]MSETUP CALIBRATION ANTSLOW__MJD__SHIFT Value

Apply (add) a shift in the antenna slow MJD traces of the given value
(in seconds, can be positive or negative). As a result the antenna
will appear earlier or later at the associated position (namely
LONGOFF, LATOFF, CAZIMUTH, CELEVATI). The subscan start and stop
timestamps are NOT shifted. The antenna fast traces are NOT shifted
neither. Default is 0, i.e. no shift is applied.

[MRTCAL_\]MSETUP CALIBRATION BAD YES|NO

Choose if the bad time dumps in the BackendXXX tables should be
calibrated (in addition to the good ones). A bad time dump has a null
ISWITCH value, and its associated data (e.g. MJD, INTEGTIM) are not
expected to be correct. If YES is requested, you will likely be
exposed to problems (e.g. if MJD column has incorrect values, searches
in this column may fail without advise). Default is NO.

[MRTCAL_\]MSETUP CALIBRATION BANDWIDTH Value

Setup the desired calibration bandwidth in MHz. The nearest value that
allows the division of the good spectra channels of each chunkset in
equal virtual chunk sizes will be used. Exceptions are:
.in +4
.ti -2
-_ if value is 0, use the native hardware chunk size (no subdivision),
.ti -2
-_ if value is larger than the native hardware chunk size, the latter
is used instead (same as 0),
.ti -2
-_ if value is lower than the channel spacing, the latter is used
instead (all channels calibrated individually, use with caution).
.in -4
Default is 20 MHz.

[MRTCAL_\]MSETUP CALIBRATION CHOPPER STRICT|TOLERANT

Setup the chopper calibration engine. By default (strict mode), any
error occuring during this process (e.g. cold load greater than hot
load) blanks the resulting data at the chunk level (i.e. the
surrounding chunks are calibrated if they have no problem). In
tolerant mode, the engine goes to the end of process, even if this
implies non physical results (e.g. negative Trec). This second mode
is dangerous and should be used for testing purposes only.
.br
In both modes, a FLAG array is added to the calibration products (see
HELP MSET OUTPUT CALIBRATION). It is 0 where no problem occured, and 1
otherwise.

[MRTCAL_\]MSETUP CALIBRATION FEEDBACK PIXEL|SET|ELEMENT

Tune the granurality of the calibration results (Tsys, Tcal, Trec, ...).
The median value per pixel, per chunkset, or per chunk element will be
printed in the PIXEL, SET, or ELEMENT mode, respectively. One value per
chunk element may result in very long lists when using virtual chunk sizes
(see MSETUP CALIBRATION BANDWIDTH). Default is SET.

[MRTCAL_\]MSETUP CALIBRATION INTERVAL ErrLimit [WarnLimit]

Setup the time limits (in minutes) used when searching automatically
for a calibration scan to be associated to a science scan. Beyond
ErrLimit, an error is raised if no calibration scan is found. Beyond
WarnLimit, only a warning is displayed. Automatic search is used by
the commands PIPELINE and CALIBRATE without the option /WITH. The
calibration scan always can be forced with CALIBRATE /WITH. Default
ErrLimit is 30 minutes, and WarnLimit defaults to 2/3 of ErrLimit.

[MRTCAL_\]MSETUP CALIBRATION MATCH Value

Define the position matching tolerance when checking the subscan
position(s) on sky. This tolerance is used 1) when checking that a
_'track_' subscan effectively provides dumps at the same position, and
2) when grouping the subscans per ON or OFF positions, and checking
that each group effectively provides the same position. Default is 4
centi-arcseconds.

[MRTCAL_\]MSETUP CALIBRATION MJDINTER YES|NO

Choose if Mrtcal should intersect the DATE-OBS and DATE-END (on-track
range) of the subscans with the MJD columns in the tables Antenna
Slow, Antenna Fast, and Backend Data. It may happen that one of these
columns are too short and the data dumps can not be
calibrated. Setting YES means that the associated dumps in this
missing range won't be considered on-track anymore, and won't be
calibrated. Default is NO.

[MRTCAL_\]MSETUP CALIBRATION OFF NEAREST|LINEAR

Define how to select the OFF subscan matching the current ON subscan
data (OTF PSW only). In NEAREST mode, the OFF subscan nearest in time
will be used. In LINEAR mode, the algorithm will linearly interpolate
between the two nearest OFF spectra. Default is LINEAR.

[MRTCAL_\]MSETUP CALIBRATION PRODUCTS LINEAR|NEAREST|SPLINE

One set of calibration products Trec, Tcal, Tsys, precipitable water
vapor, and zenithal opacity is computed per chunk, at the middle of
the chunk (chunk bandwidth is ruled by MSET CALIB BANDWIDTH). In
NEAREST mode, the intermediate values on the frequency axis use the
nearest computed values (flat value per chunk/bandwidth, possible
discontinuities). In LINEAR mode, the intermediate values are
interpolated between two middle of chunks (possible discontinuity of
the derivatives). In SPLINE mode, the intermediate values are cubic
spline interpolated between two middle of chunks (ensuring continuity
of the first and second derivatives). Default is LINEAR.

[MRTCAL_\]MSETUP CALIBRATION SCAN NEAREST|LINEAR

Define how to select the calibration scan used calibrate science data. In
NEAREST mode, the scan nearest in time will be used. In LINEAR mode, the
algorithm will linearly interpolate calibration parameters between the two
nearest calibration scans. Default is NEAREST.

[MRTCAL_\]MSETUP CALIBRATION WATER SET
.br
[MRTCAL_\]MSETUP CALIBRATION WATER ELEMENT
.br
[MRTCAL_\]MSETUP CALIBRATION WATER FIXED Value

Define if the precipitable water vapour amount should be minimized or
not:
.in +4
.ti -2
-_ SET means one single value for the whole bandwidth,
.ti -2
-_ ELEMENT means one independent value per calibration bandwidth,
.ti -2
-_ FIXED Value will force the pwv amount to the given value without
minimization.
.in -4
Default is ELEMENT.
.\"--------------------------------------------------------------------
.ti -4
2 SOLVE
.ti +4
[MRTCAL_\]MSETUP SOLVE Keyword Switch

[MRTCAL_\]MSETUP SOLVE POINTING Mode

Control how the individual pointing drift entries are combined before
minimizing for the best solution. Possible modes are:
.in +9
.ti -7
ENTRY: unique entry i.e. no mixing,
.ti -7
DRIFT: unique telescope and unique drift i.e. mixed directions
(e.g. 0+180 degrees),
.ti -7
FESBDIREC: unique frontend, unique sideband and unique direction
i.e. mixed polarizations,
.ti -7
FESBDRIFT: unique frontend, unique sideband and unique drift
i.e. mixed polarizations and mixed directions,
.ti -7
FEDIREC: unique frontend and unique direction i.e. mixed polarizations
and sidebands.
.ti -7
FEDRIFT: unique frontend and unique drift i.e. mixed polarizations,
sidebands, and directions,
.in -9

.nf
             FE               POLAR  SB     DIREC  DRIFT
  ENTRY      090|250|230|345  H|V    L|U    +|-    Az|El
  DRIFT      090|250|230|345  H|V    L|U    Mixed  Az|El
  FESBDIREC  090|250|230|345  Mixed  L|U    +|-    Az|El  (default)
  FESBDRIFT  090|250|230|345  Mixed  L|U    Mixed  Az|El
  FEDIREC    090|250|230|345  Mixed  Mixed  +|-    Az|El
  FEDRIFT    090|250|230|345  Mixed  Mixed  Mixed  Az|El
.fi
.\"--------------------------------------------------------------------
.ti -4
2 OUTPUT
.ti +4
[MRTCAL_\]MSETUP OUTPUT Keyword Switch

[MRTCAL_\]MSETUP OUTPUT CALIBRATION NONE|SPECTRA|ASSOCIATED

If NONE, the calibration products (CalSKy, Tsys, ...) are not saved
into the current output Class file. If SPECTRA, they are exported as
separated Class observations. If ASSOCIATED, they are exported in a
single observation with CalSky as the main spectrum and the other ones
as Associated Arrays. Default is SPECTRA.

[MRTCAL_\]MSETUP OUTPUT CHUNK ELEMENT|SET

Write one CLASS spectrum per CHUNK ELEMENT or per CHUNKSET. Default is
CHUNKSET.

[MRTCAL_\]MSETUP OUTPUT INTEGRATION CYCLE|SUBSCAN|SCAN|*

Write one CLASS spectrum per cycle, or per subscan, or per
scan. Wildcard * will automatically select the best default choice
from one of these, depending on observing mode. All modes are not
available in all cases:
.br
- TRACKED PSW: subscan CYCLE or SCAN (default)
.br
- TRACKED FSW or WSW: phase CYCLE, SUBSCAN, or SCAN (default)
.br
- OTF: phase CYCLE (default)
.br
- POINTING: phase CYCLE, or SUBSCAN (default)
.br
Default is *.

[MRTCAL_\]MSETUP OUTPUT SPECTRA YES|NO

Indicate whether the calibration spectra should be written in the output
CLASS file. Default is YES, i.e., write the results.

[MRTCAL_\]MSETUP OUTPUT USERSECTION YES|NO

Indicate whether the MRTCAL user section should be written for each CLASS
observation. Default is NO, as this is very experimental to test future
use CLASS, i.e., we do not warrants its stability.

[MRTCAL_\]MSETUP OUTPUT VODIR DirName

Define the target directory for VO XML files. The files will be
written in:
.in +4
.ti -2
- DirName/YYYYMMDD/scans/NN/ if this directory exists (with YYYYMMDD
the scan date and NN the scan number), else
.ti -2
- DirName if this directory exists, else
.ti -2
- ./ (current working directory) as fallback.
.in -4
Default for DirName is .

[MRTCAL_\]MSETUP OUTPUT VOXML YES|NO

Should the VO XML file describing the calibration results be produced
at end end of the processing of the calibration scan (one xml file per
backend). Default is NO.

[MRTCAL_\]MSETUP OUTPUT WEIGHT YES|NO

Write or not the weight array (time*abs(fres)/Tsys**2, Tsys varying as
a function of frequency) in the Class output file. If yes, the array
is saved as the Associated Array named W, shipped together with the
usual RY spectrum. Beware that twice more data will be written, which
typically doubles the Class file size on disk. Default is NO.
.\"--------------------------------------------------------------------
.ti -4
2 PIPELINE
.ti +4
[MRTCAL_\]MSETUP PIPELINE ONERROR CONTINUE|STOP

Set the error recovery mode of the PIPELINE command. In STOP mode, any
raised error will immediately stop the pipeline. In CONTINUE mode, the
pipeline will ontinue to iterate with the next index item when an error is
raised on the current item. Default is CONTINUE.
.\"--------------------------------------------------------------------
.ti -4
2 DEBUG
.ti +4
[MRTCAL_\]MSETUP DEBUG [Topic [Subtopic]] ON|OFF

Turn ON or OFF debugging messages for the given topics:
.ti +4
- IMBFITS [ALLOCATION|OTHERS]: for the IMB-FITS reader,
.ti +4
- INDEX [ALLOCATION|OTHERS]: for the index.mrt reading/writing,
.ti +4
- SYNCHRONIZATION: time synchronization of the tables,
.ti +4
- CALIBRATION [ALLOCATION|BOOKKEEPING|OTHERS]: for the calibration
  process.

Use MSET DEBUG ON|OFF to turn ON or OFF all the debug messages.
.\"====================================================================
.ti -4
1 MUPDATE
.ti +4
[MRTCAL_\]MUPDATE

Update in-place the relevant files from the internal buffers. This
command makes sense after modifying the structures created by the
command VARIABLE in WRITE mode:
.br
- the index file is updated after MHEAD% has been modified,
.br
- the IMB-FITS file is updated after IMBF%, SUBS%, or IMBDATA% have
been modified (NOT YET IMPLEMENTED).

After this action, the files are updated on disk but not in
memory. They should be re-read if needed.
.\"====================================================================
.ti -4
1 MWRITE
.ti +4
[MRTCAL_\]MWRITE

Convert the chunks as Class observations and WRITE them in the current
Class output file. The chunks are written one by one or are stitched
by chunk set before writing according to the MRTCAL_\SET BYCHUNK rule.
.\"====================================================================
.ti -4
1 PIPELINE
.ti +4
[MRTCAL_\]PIPELINE [/SHOW [NONE|DONE|EMPTY|FAILED]]

Calibrate iteratively all the elements in the Current indeX.

The selection of the calibration scan paired to a science scan is
automatic. It is selected according to the following rules:
.in +4
.ti -2
- search in the past the nearest matching calibration scan, up to the
limit defined by MSETUP CALIBRATION INTERVAL,
.ti -2
- if no matching calibration scan is found in the past, search for the
nearest one in the future, up to the same limit. This is useful in
case of offline reprocessing.
.ti -4
A calibration scan matches if:
.ti -2
- its calibration status is NONE or DONE. If NONE, it will be
calibrated before use.
.ti -2
- its project name and backend are identical to the science scan.
.in -4
If those rules do not meet his needs, one can use CALIBRATE /WITH to
force pairing a calibration and a science scans.

The option /SHOW will update the Current indeX at the end of the
process, and MLIST it. The optional argument indicates to populate CX
only with the elements with the corresponding calibration status.
.\"====================================================================
.ti -4
1 READ
.ti +4
[MRTCAL_\]READ [FileName|FileNum|FIRST|LAST|NEXT|PREV] [/FILENAME] [/SUBSCAN Isub]
.ti +4
[MRTCAL_\]READ ZERO

Load a file in the Mrtcal buffers:
.in +4
.ti -2
- the 4 first HDU in the IMBFITS file (namely Primary, IMBF-scan,
IMBF-frontend and IMBF-backend), and then read
.ti -2
- the 3 HDU IMBFITS-backendXXX, IMBFITS-antenna and
IMBFITS-subreflector (this latter not implemented) for the subscan
number Isub (default 1)
.ti -2
- the on-track part of the DATA column of the HDU IMBFITS-backendXXX
  is read (take care that it may be large).
.in -4

Without argument, the command will try to read again the current filename. 
Else the command argument can be either
.in +4
.ti -2
- the file name when the /FILENAME option is present,
.ti -2
- the file number (and optionally its version) in the Input index, of
  the form Num (or Num.Ver),
.ti -2
- the FIRST|LAST file in Current indeX,
.ti -2
- the NEXT|PREVIOUS file in Current indeX, considered from previous
  call to the command.
.in -4

The reference file (for NEXT or PREVIOUS) in Current indeX is reset by
the command MFIND. READ ZERO also reset the reference file and does
not read any file.
.\"====================================================================
.ti -4
1 SOLVE
.ti +4
[MRTCAL_\]SOLVE Num[.Ver] [/WITH Num[.Ver]]

Solve the pointing/focus/skydip parameters for the file indentified by its
Number. To do this, it first calibrate the pointing/focus/skydip data.  The
calibration scan is chosen implicitly by the command, except if explicitly
specified through the option /WITH.

Boths file numbers can be added a Version number. If not given, the
latest version is selected.
.\"====================================================================
.ti -4
1 VARIABLE
.ti +4
[MRTCAL_\]VARIABLE [*|What [READ|WRITE]] [/INDEX]

Create one or all the Sic structures mapping the Mrtcal internal
buffers, namely:
.in +4
.ti -2
-_ IMBF%PRIM, IMBF%SCAN, IMBF%FRONT, IMBF%BACK, IMBF%DEROT map the
FITS HDUs for the scan,
.ti -2
-_ SUBS%BACKDATA, SUBS%ANTSLOW, SUBS%ANTFAST map the FITS HDUs for one
subscan,
.ti -2
-_ IMBDATA%TIME and IMBDATA%IMBF% describe a portion of data of the
DATA table,
.ti -2
-_ MHEAD%KEY, MHEAD%PRI, MHEAD%CAL, MHEAD%SCI, MHEAD%POI map the
sections of the index entry which was read.
.in -4
Default is *, i.e. the 4 structures will be created, but only one
structure can be created with one of the keywords IMBF, SUBS, IMBDATA,
MHEAD.

The structures can be created read-only (keyword READ) or read-write
(keyword WRITE) for further update with the commands
MUPDATE/MWRITE. Default is read-only.

Note that these variables are not updated when the buffers are
changed. For safety they should be updated by recalling the command.
.\"--------------------------------------------------------------------
.ti -4
2 /INDEX
.ti +4
[MRTCAL_\]VARIABLE /INDEX

Populate the MDX%HEAD% Sic structure with all the current index
sections. Components are:
.in +4
.ti -2
- MDX%HEAD%KEY
.ti -2
- MDX%HEAD%PRI
.ti -2
- MDX%HEAD%SCI
.ti -2
- MDX%HEAD%POI
.in -4
Each individual component is appended a "number of entries" (i.e. size
MFOUND) trailing dimension compared to the MHEAD% equivalent structure
for one entry.
.\"====================================================================
.ti -4
1 ENDOFHELP
