#
# stub function definition file for docstring parsing
#
[docs]def fringefit(vis, caltable='', field='', spw='', intent='', selectdata=True, timerange='', uvrange='', antenna='', scan='', observation='', msselect='', solint='inf', combine='', refant='', minsnr=3.0, zerorates=False, globalsolve=True, niter=100, delaywindow='', ratewindow='', append=False, corrdepflags=False, corrcomb='none', docallib=False, callib='', gaintable='', gainfield='', interp='', spwmap='', paramactive='', concatspws=True, parang=False):
r"""
Fringe fit delay and rates
[`Description`_] [`Examples`_] [`Development`_] [`Details`_]
Parameters
 vis_ (path)  Name of input visibility file
 caltable_ (string='')  Name of output gain calibration table
 field_ (string='')  Select field using field id(s) or field name(s)
 spw_ (string='')  Select spectral window/channels
 intent_ (string='')  Select observing intent
 selectdata_ (bool=True)  Other data selection parameters
.. raw:: html
<details><summary><i> selectdata = True </i></summary>
 timerange_ (string='')  Select data based on time range
 antenna_ (string='')  Select data based on antenna/baseline
 scan_ (string='')  Scan number range
 observation_ ({string, int}='')  Select by observation ID(s)
 msselect_ (string='')  Optional complex data selection (ignore for now)
.. raw:: html
</details>
 solint_ (variant='inf')  Solution interval: egs. \'inf\', \'60s\' (see help)
 combine_ (string='')  Data axes which to combine for solve (obs, scan, spw, and/or field)
 refant_ (string='')  Reference antenna name(s)
 minsnr_ (double=3.0)  Reject solutions below this signaltonoise ratio (at the FFT stage)
 zerorates_ (bool=False)  Zero delayrates in solution table
 globalsolve_ (bool=True)  Refine estimates of delay and rate with global leastsquares solver
 niter_ (int=100)  Maximum number of iterations for leastsquares solver
 delaywindow_ (doubleVec='')  Constrain FFT delay search to a window
 ratewindow_ (doubleVec='')  Constrain FFT rate search to a window
 append_ (bool=False)  Append solutions to the (existing) table
 corrdepflags_ (bool=False)  Respect correlationdependent flags
 corrcomb_ (string='none')  Combine correlations
 docallib_ (bool=False)  Use callib or traditional cal apply parameters
.. raw:: html
<details><summary><i> docallib = False </i></summary>
 gaintable_ (stringVec='')  Gain calibration table(s) to apply on the fly
 gainfield_ (stringVec='')  Select a subset of calibrators from gaintable(s)
 interp_ (stringVec='')  Temporal interpolation for each gaintable (''=linear)
 spwmap_ (any='')  Spectral window mappings to form for gaintable(s)
.. raw:: html
</details>
.. raw:: html
<details><summary><i> docallib = True </i></summary>
 callib_ (string='')  Cal Library filename
.. raw:: html
</details>
 paramactive_ (boolVec='')  Control which parameters are solved for
 concatspws_ (bool=True)  Choose between multiband FFT strategies
 parang_ (bool=False)  Apply parallactic angle correction on the fly
.. _Description:
Description
calculates a fringefitting (phase/delay/rate) solution
.. warning:: **WARNING: fringefit** is currently an experimental task. Use
with care and report issues back to the CASA team via the `NRAO
helpdesk <http://help.nrao.edu/>`__. There is also a `Known Issues <../../notebooks/introduction.html#KnownIssues>`__ for fringefit: calibration
tables made with fringefit in CASA 5.5 will not work in CASA
5.6 and later.
The **fringefit** task determines phase, delay, delayrate and
(optionally) dispersive delay solutions as a function of time
and spectral window, thus enabling correction of visibility
phases for errors introduced by the atmosphere, the signal paths
of the instrument, or other precalibration steps. It can
correct a single scan on a bright source for delay offsets
between spectral windows, which can result from instrumental
signal paths (singleband delays), and it can correct multiple
scans on a source to correct for errors that are variable in
time (multiband delay and delay rate). The task uses the model
data column when present in the MeasurementSet. Fringe fitting
is primarily useful for VLBI.
.. rubric:: Introduction
In Very Long Baseline Interferometry (VLBI), fringefitting is
an essential step which is not typically used for connected
element arrays such as JVLA and ALMA. The very long baselines
make observations particularly sensitive to small errors in the
correlator model (station positions), signal chain, and the
temporally and spatiallyvariable atmosphere. The errors
manifest themselves as residual delays (which introduce a slope
when plotting phase against frequency) and delayrates (which
cause the phase offset at, say, the center of the band to drift
as a function of time). Additionally at low frequencies and
large fractional bandwidths a dispersive delay can be observed
proportional (in time) to the inverse of the square of frequency
and therefore proportional to the reciprocal of the frequency in
phase. These errors can be corrected by observations of a bright
calibrator source and a phase reference source which is close to
the target source in projection on the sky.
Prior to running **fringefit** it is recommended to calibrate
the amplitudes, as the weights are used by **fringefit** to
determine the reliability of the fringe detection. A tunable
SNRcutoff is implemented to allow weak fringes and
nondetections to be discarded. Bandpass correction can be done
either before or after fringe fitting using
**bandpass**. ** ** Since the CASA **bandpass** is a simple
complex gain correction, it will be more efficient after fringe
fitting when VLBIstyle geometrical errors are important.
The algorithm used in **fringefit**, based on the SchwabCotton
algorithm (originally implemented in the AIPS task FRING), has
two stages. The first step is to look for fringes on each
baseline to a reference station separately and estimate the SNR
value for each of these baselines using a Fast Fourier
Transform. The fringes that pass the SNR requirement are passed
through to the second step, a global leastsquares solver that
attempts to optimize the solutions and transform them into
antennabased solutions for phase, delay, rate and dispersive
delay. All of the parameters except phase can be included or
excluded in the solution at this phase using the *paramactive*
keyword described below; the default is that phase, delay and
rate are solved but dispersive delay is not, since this matches
the historical default and the usage we expect to be most common
in VLBI.
.. note:: **NOTE**: For the multiband delay, the solutions for the full
combined spectral window are written for a notional spectral
window 0. To account for this spectral window in the
**applycal** step, use the *spwmap* parameter to ensure that
the solutions are correctly applied to all spectral windows
(see the Examples tab for details).
.. rubric:: Common calibration solve parameters
See `Solving for
Calibration <../../notebooks/synthesis_calibration.ipynb#SolveforCalibration>`__ for
more information on the task parameters **fringefit** shares with
all solving tasks, including data selection, general solving
properties and arranging prior calibration (i.e., specifying other
caltables to preapply before solving). Also see
the **rerefant** task documentation for the behavior of reference
antenna application. Below we describe parameters unique to
**fringefit** and those common parameters with unique properties.
.. note:: **NOTE**: Like **gaincal**, fringefit supports passing a list
of antennas through the *refant* parameter. However
**fringefit** does not implement the *refantmode* parameter and
effectively always operates in 'flex' mode, using the next
antenna from the list as the reference antenna if an antenna is
not available.
.. rubric:: Parameter descriptions
.. rubric:: Solution interval: *solint*
The solution interval specified in *solint* (in seconds) is used
to group data. It is important to make sure that for intervals
shorter than the scan length, the scan is divided into roughly
equal sized solution intervals. Avoid selecting a solution
interval that will lead to intervals containing a single
integration time, as this will cause an error.
.. rubric:: Combining data for solutions: *combine*
As in other calibration solve tasks, data can be combined over
different axes. To derive multiband delay corrections, set
*combine='spw'.*
.. rubric:: SNR control: *minsnr*
The *minsnr* parameter sets the threshold of the SNR value
required for the baseline based fringe (FFT stage) to be included
in the global leastsquares minimization.
.. rubric:: Ratezeroing: *zerorates*
When correcting instrumental delays by solving for each spectral
window separately, it is usual to apply the corrections derived to
the entire dataset. Extrapolating the rates in time is
undesirable, so use of *zerorates=True* will cause no
timedependent rate correction to be applied. Note that with this
option the rates are still solved, and zeroed only when written to
the table; *paramactive* can be used to turn off solution of rates
altogether but this is currently not recommended; *zerorates* (and
its equivalent in other software) has been the standard practice
in VLBI for a long time, and is likely to remain so.
.. rubric:: Prior correction for parallactic angle: *parang*
Although optional, it is is generally recomended that
*parang=True* be used for VLBI observations, since parallactic
angle causes differential phase rates among widelyseparated
antennas that usually should not be included within the
**fringefit** solution.
.. rubric:: Disabling the global leastsquares solver: *globalsolve*
By default, fringefit solutions are refined by a global
leastsquares optimization algorithm after the FFT stage. For some
purposes, it is desirable to use the estimates from the FFT stage
directly; this can be done by setting *globalsolve* =False. (The
default is True)
.. rubric:: Setting a maximum number of iterations: *niter*
A maximum number of iterations for the global least squares solver
can be set with the *niter* parameter. The default is 100; in
cases with high signaltonoise this limit is not reached.
.. rubric:: Constrain the search window for delay: *delaywindow*
Sometimes a priori information is available to constrain the
delays relative to the reference station at the FFT search step.
The upper and lower bounds (in nanoseconds) can be provided as a
two element list through the keyword *delaywindow*. The value None
can be used to leave either the upper or lower limit unconstrained
(setting both to None constrains neither; this is the default).
Note that the same constraint is applied to all baselines in the
FFT search step.
.. rubric:: Constrain the search window for rate: *ratewindow*
Similarly to *delaywindow*, sometimes a priori information is
available to constrain the delay rates relative to the reference
station at the FFT search step. The upper and lower bounds (in
units of seconds/second) can be provided as a two element list
through the keyword *ratewindow*. The value None can be used to
leave either the upper or lower limit unconstrained (setting both
to None constrains neither; this is the default). Note that the
same constraint is applied to all baselines in the FFT search
step.
.. rubric:: Select a weighting strategy for the least squares solver: *weightfactor*
It is common in VLBI practice for the user to choose how weights
of visiblities should be used in the global stage of
fringefitting. In any array such as the EVN with a very sensitive
antenna (in the EVN's case Effelsberg), the use of measurement set
weights can mean that baselines to the sensitive antenna dominate
and other baselines have neglibible impact. Choosing the square
root of those weights gives, many users feel, a more balanced
interpretation of the data.
The *weightfactor* parameter allows the user to chose between
strategies:
 0 => use a weight of 1 (i.e., ignore measurement set weights);
 1 => use the squareroot of measurement set weights;
 2 => use the measurement set weights as they are (the default)
.. rubric:: Select active parameters for least square solver: *paramactive*
As part of the inclusion of a dispersive component of delay we
have added a parameter to control which model parameters are used
in the leastsquares part of the solver (the FFT stage is
unaffected). The *paramactive* parameter takes a Python list of
boolean arguments for the delay, rate and dispersive components,
with a default value of [True, True, False] to match the historic
default, which is also expected to be the most common future
usecase. Note that we do not offer users an opportunity not to
solve for phase offset (also known as "secular phase").
.. _Examples:
Examples
Singleband delay: calibration of delay only for a single scan on
a bright calibrator:
::
fringefit(vis='data.ms',
caltable='data.sbd', # write solutions to this table on disk
scan='30', # use only scan 30
solint='inf', # use all timestamps in the scan
refant='EF', # a big antenna does well as reference antenna
minsnr=50, # empirically proven to be a good value is anything over 25
zerorates=True, # for instrumental delay rates should not be used
gaintable=['data.tsys','data.gc'], # apply the amplitude calibration on the fly
parang=True) # always True for VLBI
Multiband delay: calibration of timedependent delay and
delayrate for a phase reference source, relative to singleband
delay solution from above:
::
fringefit(vis='data.ms',
caltable='data.mbd', # write solutions to this table disk
solint='60', # anything shorter than the scan length will give more than 1 solution
combine='spw', # combine spectral windows for this step, gives only a solution for spw0
field='1', # select the field that is your phase reference calibrator
refant='EF', # pick a big antenna or one close to the geometric center of the array
minsnr=50, # this seems to be a sensible value
gaintable=['data.tys', 'data.gc', 'data.sbd'], # apply amplitude calibration and single band delay on the fly
parang=True) # always set to True for VLBI
The calibration table data.mbd will contain phase, delay, and rate
solutions per antenna, per polarization and per solution interval.
For data with multiple spectral windows the solutions will be
assigned to spectral window 0 in the output cal table. In the
**applycal** step, the parameter *spwmap* needs to be set to apply
the solutions to all spectral windows. For example, in a dataset
with 8 spectral windows: *spwmap=[8*[0]]*. Since the **applycal**
step will include multiple calibration tables, this setting needs
to correspond to the data.mbd table in the *gaintable* parameter:
::
applycal(vis='data.ms',
field='0,1', # now select the phase calibrator AND the target source
gaintable=['data.tsys', 'data.gc','data.sbd', 'data.mbd'], # include all the calibration tables
interp=[],spwmap=[[], [], [], 8*[0]], # map the spectral windows accordingly
parang=True) # for VLBI this should always be True
In cases where it is necessary to constrain the search for group
delay and fringe rates at the FFT stage, the parameters
*delaywindow* and *ratewindow* can be used:
::
fringefit(vis='data.ms',
caltable='data.mbd', # write solutions to this table disk
solint='60', # anything shorter than the scan length will give more than 1 solution
combine='spw', # combine spectral windows for this step, gives only a solution for spw0
field='1', # select the field that is your phase reference calibrator
refant='EF', # pick a big antenna or one close to the geometric center of the array
minsnr=5, # we're looking for weak detections, but we have a good a priori idea of
# where they are to steer the FFT search
delaywindow = [0,10], # FFT delay search range of 0 to 10 nanoseconds
ratewindow = [5e9,5e9], # FFT rate search range of 5 to 5 nanoseconds per second
gaintable=['data.tys', 'data.gc', 'data.sbd'], # apply amplitude calibration and single band delay on
# the fly
parang=True) # always set to True for VLBI
.. _Development:
Development
No additional development details
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _vis:
 ``vis (path)``  Name of input visibility file
.. _caltable:
 ``caltable (string='')``  Name of output gain calibration table
.. _field:
 ``field (string='')``  Select field using field id(s) or field name(s)
.. _spw:
 ``spw (string='')``  Select spectral window/channels
.. _intent:
 ``intent (string='')``  Select observing intent
.. _selectdata:
 ``selectdata (bool=True)``  Other data selection parameters
.. _timerange:
 ``timerange (string='')``  Select data based on time range
.. _uvrange:
 ``uvrange (variant='')``  Select data by baseline length.
 Default = '' (all)
 Examples:
 uvrange='0~1000klambda'; uvrange from 01000 kilolambda
 uvrange='>4klambda';uvranges greater than 4 kilolambda
 uvrange='0~1000km'; uvrange in kilometers
.. _antenna:
 ``antenna (string='')``  Select data based on antenna/baseline
.. _scan:
 ``scan (string='')``  Scan number range
.. _observation:
 ``observation ({string, int}='')``  Select by observation ID(s)
.. _msselect:
 ``msselect (string='')``  Optional complex data selection (ignore for now)
.. _solint:
 ``solint (variant='inf')``  Solution interval: egs. \'inf\', \'60s\' (see help)
.. _combine:
 ``combine (string='')``  Data axes which to combine for solve (obs, scan, spw, and/or field)
.. _refant:
 ``refant (string='')``  Reference antenna name(s)
.. _minsnr:
 ``minsnr (double=3.0)``  Reject solutions below this signaltonoise ratio (at the FFT stage)
.. _zerorates:
 ``zerorates (bool=False)``  Zero delayrates in solution table
 Write a solution table with delayrates zeroed, for the case of
 "manual phase calibration", so that the calibration table can be
 applied to the full dataset without the extrapolation of a nonzero delayrate term
 affecting the data
.. _globalsolve:
 ``globalsolve (bool=True)``  Refine estimates of delay and rate with global leastsquares solver
.. _niter:
 ``niter (int=100)``  Maximum number of iterations for leastsquares solver
.. _delaywindow:
 ``delaywindow (doubleVec='')``  Constrain FFT delay search to a window specified as a twoelement list with units of nanoseconds
 Default: [None, None]
 Examples: [10, 10]
.. _ratewindow:
 ``ratewindow (doubleVec='')``  Constrain FFT rate search to a window specified as a twoelement list with units of seconds per second
 Default: [None, None]
 Examples: [1e13, 1e13]
.. _append:
 ``append (bool=False)``  Append solutions to the (existing) table
 Default: False (overwrite existing table or make
 new table)
 Appended solutions must be derived from the same
 MS as the existing caltable, and solution spws
 must have the same metainfo (according to spw
 selection and solint) or be nonoverlapping.
.. _corrdepflags:
 ``corrdepflags (bool=False)``  If False (default), if any correlation is flagged, treat all correlations in
 the visibility vector as flagged when solving (per channel, per baseline).
 If True, use unflagged correlations in a visibility vector, even if one or more
 other correlations are flagged.

 Default: False (treat correlation vectors with one or more correlations flagged as entirely flagged)

 Traditionally, CASA has observed a strict interpretation of
 correlationdependent flags: if one or more correlations
 (for any baseline and channel) is flagged, then all available
 correlations for the same baseline and channel are
 treated as flagged. However, it is desirable in some
 circumstances to relax this stricture, e.g., to preserve use
 of data from antennas with only one good polarization (e.g., one polarization
 is bad or entirely absent). Solutions for the bad or missing polarization
 will be rendered as flagged.
.. _corrcomb:
 ``corrcomb (string='none')``  Combine correlations: "all" and "none" are currently
 supported values
.. _docallib:
 ``docallib (bool=False)``  Control means of specifying the caltables
 Default: False (Use gaintable, gainfield, interp,
 spwmap, calwt)
 Options: FalseTrue
 If True, specify a file containing cal library in
 callib
.. _callib:
 ``callib (string='')``  Specify a file containing cal library directives
 Subparameter of docallib=True
.. _gaintable:
 ``gaintable (stringVec='')``  Gain calibration table(s) to apply on the fly
 Default: '' (none)
 Subparameter of docallib=False
 Examples:
 gaintable='ngc5921.gcal'
 gaintable=['ngc5921.ampcal','ngc5921.phcal']
.. _gainfield:
 ``gainfield (stringVec='')``  Select a subset of calibrators from gaintable(s)
 Default: '' (all sources on the sky)
 'nearest' ==> nearest (on sky) available field in
 table otherwise, same syntax as field
 Examples:
 gainfield='0~2,5' means use fields 0,1,2,5
 from gaintable
 gainfield=['0~3','4~6'] means use field 0
 through 3
.. _interp:
 ``interp (stringVec='')``  Interpolation parameters (in time[,freq]) for each gaintable, as a list of strings.
 Default: '' > 'linear,linear' for all gaintable(s)
 Options: Time: 'nearest', 'linear'
 Freq: 'nearest', 'linear', 'cubic',
 'spline'
 Specify a list of strings, aligned with the list of caltable specified
 in gaintable, that contain the required interpolation parameters
 for each caltable.
 * When frequency interpolation is relevant (B, Df,
 Xf), separate timedependent and freqdependent
 interp types with a comma (freq after the
 comma).
 * Specifications for frequency are ignored when the
 calibration table has no channeldependence.
 * Timedependent interp options ending in 'PD'
 enable a "phase delay" correction per spw for
 nonchanneldependent calibration types.
 * For multiobsId datasets, 'perobs' can be
 appended to the timedependent interpolation
 specification to enforce obsId boundaries when
 interpolating in time.
 * For multiscan datasets, 'perscan' can be
 appended to the timedependent interpolation
 specification to enforce scan boundaries when
 interpolating in time.
 * Freqdependent interp options can have 'flag' appended
 to enforce channeldependent flagging, and/or 'rel'
 appended to invoke relative frequency interpolation
 Examples:
 interp='nearest' (in time, freqdep will be
 linear, if relevant)
 interp='linear,cubic' (linear in time, cubic
 in freq)
 interp='linearperobs,splineflag' (linear in
 time per obsId, spline in freq with
 channelized flagging)
 interp='nearest,linearflagrel' (nearest in
 time, linear in freq with with channelized
 flagging and relativefrequency interpolation)
 interp=',spline' (spline in freq; linear in
 time by default)
 interp=['nearest,spline','linear'] (for
 multiple gaintables)
.. _spwmap:
 ``spwmap (any='')``  Spectral window mappings to form for gaintable(s)
 Only used if callib=False
 default: [] (apply solutions from each calibration spw to
 the same MS spw only)
 Any available calibration spw can be mechanically mapped to any
 MS spw.
 Examples:
 spwmap=[0,0,1,1] means apply calibration
 from cal spw = 0 to MS spw 0,1 and cal spw 1 to MS spws 2,3.
 spwmap=[[0,0,1,1],[0,1,0,1]] (use a list of lists for multiple
 gaintables)
.. _paramactive:
 ``paramactive (boolVec='')``  Control which parameters are solved for; a vector of (exactly) three booleans for delay, delayrate and dispersive delay (in that order)
.. _concatspws:
 ``concatspws (bool=True)``  For combine='spw', the multiband FFT solution can be
 done in two different ways. For concatspws=True (the default), spws are
 combined onto a wider frequency grid. For concatspws=False, each
 spw is separated FFT'd, and the results are combined using the
 shift theorem; this mode is experimental.
.. _parang:
 ``parang (bool=False)``  Apply parallactic angle correction on the fly.
"""
pass