#
# stub function definition file for docstring parsing
#
[docs]def rerefant(vis, tablein, caltable='', refantmode='flex', refant=''):
r"""
Re-apply refant to a caltable
[`Description`_] [`Examples`_] [`Development`_] [`Details`_]
Parameters
- vis_ (path) - Name of input visibility file (MS)
- tablein_ (path) - Input calibration table
- caltable_ (string='') - Output calibration table (overwrite tablein if unspecified)
- refantmode_ (string='flex') - Refant algorithm to use
- refant_ (string='') - Reference antenna name(s)
.. _Description:
Description
The time-dependent phases for a specified caltable are
re-referenced to a new antenna by the specified algorithm.
.. rubric:: Introduction
Fundamentally, the baseline visibility phases measured by a
synthesis instrument are exclusively differences (between
antennas), and so no absolute phase reference exists.
Antenna-based calibration solutions thus have phases which are
constrained only to satisfy the observed visibility phases;
further, each solution in time is formally independent of all
others, though stability (or at least continuity) in time is
expected. Therefore, to assert phase continuity in time, it is
conventional practice to assign a reference antenna whose phase
will be held constant at zero in time. Any actual phase variation
associated with the reference antenna will be transferred to the
phase solutions of all others (consistent with satisfying the
visibility phase differences), and if the time sampling is
adequate, phase continuity for all antennas—and thus also for all
visibility baselines—will be assured. Usually, the phase reference
antenna is applied on the back-end of the calibration solving
task, e.g., **gaincal** or **bandpass**.
However, it is sometimes the case that the referencing must be
reapplied with a different reference antenna choice, or with a
different algorithm, e.g., due to dropouts (from visibility
flagging) or other problems in the nominally preferred reference
antenna. The **rerefant** task provides a convenient mechanism to
achieve this without having to re-run the calibration solving task
with only a new *refant* setting.
.. rubric:: Input/Output parameters
An input MS, input caltable, and output caltable are specified in
*vis*, *tablein*, and *caltable*, respectively.
.. rubric:: Reference antenna choice: *refant*
Reference antennas are specified using the *refant* parameter. A
list of antennas may be specified in decreasing order of
preference. (See below for the conditions under which alternate
reference antennas are used.)
.. rubric:: Phase referencing mode: *refantmode*
The *refantmode* parameter controls how the refant is applied.
Currently available choices are 'flex' and 'strict'.
.. rubric:: *refantmode='flex'*
If the preferred or current *refant* drops out, switch to another.
Alternate reference antennas will be chosen from the *refant*
parameter (if a nontrivial list of antennas is specified), or
according to proximity to the last-used refant. If and when the
preferred refant returns, the referencing will switch back to it.
Note that the preferred reference antenna may no longer be at zero
at phase with respect to the alternate refant, and so it will
return at a new phase value that will be kept constant from that
point. Generally, this mode of referencing should ensure
continuity at the available phase SNR (signal-to-noise ratio).
However, under low SNR conditions, the effective cross-hand phase
may not be assured stable at refant changes, since each hand of
polarization is referenced independently, and the non-zero noise
on the cross-hand phase difference will change. When doing
polarimetry (which depends on stable cross-hand phase), it may be
preferable to use *refantmode='strict'* (see below).
.. rubric:: *refantmode='strict'*
If the preferred or current refant is absent for a solution, flag
all antennas at that solution. This mode ensures that the
effective cross-hand phase will be maintained constant and equal
to that of the chosen refant, and not subject to variation due to
finite SNR when switching among reference antennas. If a list of
antennas is specified in *refant*, only the first is used. Note
that *refantmode='strict'* is not reversible, since the reason for
flagging solutions is not preserved. Also note that a poor refant
choice could lead to excessive data flagging when using this mode.
.. _Examples:
Examples
To apply a prioritized list of reference antennas using
*refantmode='flex'*:
::
rerefant(vis='n5921.ms',
tablein='n5921.gcal',
caltable='n5921_ea03ish.gcal', # Output caltable
refant='ea03,ea05,ea23,ea01', # prioritized list of reference antennas
refantmode='flex') # flexible use of alternates
To strictly apply a preferred reference antenna:
::
rerefant(vis='n5921.ms',
tablein='n5921.gcal',
caltable='n5921_ea03.gcal', # Output caltable
refant='ea03', # the strictly preferred reference antenna
refantmode='strict') # strict!
.. _Development:
Development
No additional development details
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _vis:
| ``vis (path)`` - Name of input visibility file (MS)
.. _tablein:
| ``tablein (path)`` - Input calibration table
.. _caltable:
| ``caltable (string='')`` - Output calibration table (overwrite tablein if unspecified)
.. _refantmode:
| ``refantmode (string='flex')`` - Refant algorithm to use
.. _refant:
| ``refant (string='')`` - Reference antenna name(s)
"""
pass