#
# stub function definition file for docstring parsing
#
[docs]def sdgaincal(infile, calmode='doublecircle', radius='', smooth=True, antenna='', field='', spw='', scan='', intent='', applytable='', interp='', spwmap='', outfile='', overwrite=False):
r"""
MS SD gain calibration task
[`Description`_] [`Examples`_] [`Development`_] [`Details`_]
Parameters
- infile_ (path) - name of input SD dataset (must be MS)
- calmode_ (string='doublecircle') - gain calibration mode ("doublecircle")
.. raw:: html
<details><summary><i> calmode = doublecircle </i></summary>
- radius_ (variant='') - radius of central region to be used for calibration
- smooth_ (bool=True) - smooth data or not
.. raw:: html
</details>
- antenna_ (string='') - select data by antenna name or ID, e.g. "PM03"
- field_ (string='') - select data by field IDs and names, e.g. "3C2*" ("" = all)
- spw_ (string='') - select data by spw IDs (spectral windows), e.g., "3,5,7" ("" = all)
- scan_ (string='') - select data by scan numbers, e.g. "21~23" (""=all)
- applytable_ (variant='') - (List of) sky and/or tsys tables for pre-application
.. raw:: html
<details><summary><i> applytable != '' </i></summary>
- interp_ (variant='') - Interp type in time[,freq], per gaintable. default==linear,linear
- spwmap_ (intVec='') - Spectral window mappings to form for applytable(s)
.. raw:: html
</details>
- outfile_ (string='') - name of output caltable
- overwrite_ (bool=False) - overwrite the output file if already exists [True, False]
.. _Description:
Description
**sdgaincal** computes and removes a time-dependent gain variation
in single-dish data on a per-spectral-window and per-antenna
basis. Presently the task operates only on data taken with the
ALMA fast-mapped, double-circle observation modes [1]_
. This task exploits the fact that the double-circle mode observes
the same position in the center of the mapped field, approximately
circular every sub-cycle, and normalizes the gains throughout the
entire dataset, relative to the measured brightness at the center
position.
.. note:: Info: This gain calibration task is done independently of, and
following, the atmosphere (i.e. :math:`T_{sys}`) and sky
calibration steps applied through the **sdcal** task.
Alternative way to apply these caltables is to utilize
pre-application capability of **sdgaincal** task. This can be
done by feeding caltables into the task using *applytable*
parameter. You can specify spw mapping and interpolation method
via *spwmap* and *interp*, respectively. Usage for these
parameters are exactly same as **applycal**.
.. rubric:: Configurable inputs control the calibration mode,
selection parameters, and output behavior:
Presently, this task has only one calibration mode:
*calmode=*'*doublecircle*'.
The size of the region that CASA regards as "the center" is
user-configurable via the expandable '*radius*' (in arcsec)
parameter (under '*calmode*'). The default is to use the size of
the primary beam. The data can also be smoothed in the time
domain, prior to computation of the gain variation. Selection is
by specral window/channels, field IDs, and antenna through the
*spw*, *field,* and *antenna* selection parameters. The default is
to use all data for the gain calibration. The caltable can be
output with the '*outfile*' parameter.
.. rubric:: Bibliography
.. [1] Phillips et al, 2015, in ASP Conf. Ser. 499, Revolution in Astronomy with ALMA: The Third Year, 347
`ADS <https://ui.adsabs.harvard.edu/abs/2015ASPC..499..347P/abstract>`__
.. _Examples:
Examples
There are two ways to generate and apply double-circle gaintable.
One is to calibrate and apply atmosphere and sky calibrations
separately, and the other is to apply them on-the-fly during
double-circle gain calibration. The latter should be more
efficient. Examples for these two procedures are shown below.
.. rubric:: Apply atmosphere and sky caltables separately
To compute a gaintable and subsequently apply it using
**applycal**:
#. Generate the :math:`T_{sky}` and :math:`T_{sys}` calibration
tables, and apply them (**sdcal**)
#. Split out the corrected column data (**split**)
#. Generate the double-circle gaincal calibration tables
(**sdgaincal**)
#. Apply the double-circle gaincal calibration tables
(**applycal**)
In CASA, this looks like the following:
::
sdcal(infile=inputvis, calmode='ps,tsys,apply')
split(vis=inputvis, outputvis=calibratedvis, datacolumn='corrected')
sdgaincal(infile=calibratedvis, outfile='DCgaintable', calmode='doublecircle')
applycal(vis=calibratedvis, gaintable='DCgaintable')
.. rubric:: Apply atmosphere and sky caltables on-the-fly
To compute a gaintable and subsequently apply it using
**applycal**:
#. Generate the :math:`T_{sky}` and :math:`T_{sys}` calibration
tables (**sdcal**)
#. Generate the double-circle gaincal calibration tables by
applying :math:`T_{sky}` and :math:`T_{sys}` calibration
tables on-the-fly (**sdgaincal**)
- You can set *spwmap* and *interp* for each
pre-application caltable if necessary
#. Apply the double-circle gaincal calibration tables
(**applycal**)
In CASA, this looks like the following:
::
sdcal(infile=inputvis, calmode='ps', outfile='sky.tbl')
sdcal(infile=inputvis, calmode='tsys', outfile='tsys.tbl')
sdgaincal(infile=inputvis, applytable=['sky.tbl', 'tsys.tbl'],
outfile='DCgaintable', calmode='doublecircle')
applycal(vis=inputvis, gaintable='DCgaintable')
.. _Development:
Development
No additional development details
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _infile:
| ``infile (path)`` - name of input SD dataset (must be MS)
.. _calmode:
| ``calmode (string='doublecircle')`` - gain calibration mode
.. _radius:
| ``radius (variant='')`` - radius of central region to be used for calibration
.. _smooth:
| ``smooth (bool=True)`` - smooth data or not
.. _antenna:
| ``antenna (string='')`` - select data by antenna name or ID, e.g. "PM03"
.. _field:
| ``field (string='')`` - select data by field IDs and names, e.g. "3C2*" ("" = all)
.. _spw:
| ``spw (string='')`` - select data by spw IDs (spectral windows), e.g., "3,5,7" ("" = all)
.. _scan:
| ``scan (string='')`` - select data by scan numbers, e.g. "21~23" (""=all)
.. _intent:
| ``intent (string='')`` - select data by observation intent, e.g. "OBSERVE_TARGET#ON_SOURCE" (""=all)
.. _applytable:
| ``applytable (variant='')`` - (List of) sky and/or tsys tables for pre-application
.. _interp:
| ``interp (variant='')`` - Interp type in time[,freq], per gaintable. default==linear,linear
.. _spwmap:
| ``spwmap (intVec='')`` - Spectral window mappings to form for applytable(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
| applytables)
.. _outfile:
| ``outfile (string='')`` - name of output caltable
.. _overwrite:
| ``overwrite (bool=False)`` - overwrite the output file if already exists
"""
pass