#
# stub function definition file for docstring parsing
#
[docs]def sdatmcor(infile='', datacolumn='data', outfile='', overwrite=False, field='', spw='', scan='', antenna='', correlation='', timerange='', intent='', observation='', feed='', msselect='', outputspw='', gainfactor='1.0', dtem_dh='', h0='', atmtype=2, atmdetail=False, altitude='', temperature='', pressure='', humidity=-1, pwv='', dp='', dpm=-1, layerboundaries='', layertemperature=''):
r"""
Offline correction of residual atmospheric features
[`Description`_] [`Examples`_] [`Development`_] [`Details`_]
Parameters
- infile_ (string='') - name of input MS.
- datacolumn_ (string='data') - name of data column to be used ["data", "float_data", or "corrected"]
- outfile_ (string='') - name of output MS.
- overwrite_ (bool=False) - allow to overwrite the output file if already exists.
- field_ (string='') - field(s) to select
- spw_ (string='') - spws to select
- scan_ (string='') - Scan number range
- antenna_ (string='') - Select data based on antenna
- correlation_ (string='') - Correlation (polarization) types or expression
- timerange_ (string='') - Range of time to select from data
- intent_ (string='') - Scan Intent(s)
- observation_ (string='') - Observation ID range
- feed_ (string='') - feed selection
- msselect_ (string='') - Complicated data selection using TaQL
- outputspw_ (string='') - select spws to output, same syntax of spw.("" = all)
- gainfactor_ ({double, record, string}='1.0') - Gain factor to multiply correction term
- dtem_dh_ ({string, double}='') - temperature gradient [K/km], e.g. -5.6. ("" = Tool default)
- h0_ ({string, double}='') - scale height for water [km], e.g. 2.0. ("" = Tool default)
- atmtype_ (int=2) - Specify atmtype as integer. Options are 1: tropical, 2: mid latitude summer, 3: mid latitude winter, 4: subarctic summer, 5: subarctic winter
- atmdetail_ (bool=False) - Expose sub-parameters if True.
.. raw:: html
<details><summary><i> atmdetail = True </i></summary>
- altitude_ ({string, double}='') - Site altitude [m]. ("" = value from MS.)
- temperature_ ({string, double}='') - Ambient temperature [K]. ("" = value from MS.)
- pressure_ ({string, double}='') - Ambient pressure [mbar]. ("" = value from MS.)
- humidity_ (double=-1) - Relative humidity [percent]. -1 or the value (0.0 - 100.0) (-1 = Tool default)
- pwv_ ({string, double}='') - Zenith water vapor [mm]. ("" = Tool default)
- dp_ ({string, double}='') - Initial pressure step [mbar].("" = Tool default)
- dpm_ (double=-1) - Pressure multiplicative factor for steps. (-1 = Tool default)
- layerboundaries_ ({string, stringVec, doubleVec}='') - Altitude of user-defined temperature profile [m]. ("" = Tool default)
- layertemperature_ ({string, stringVec, doubleVec}='') - User-defined temperature profile [K]. ("" = Tool default)
.. raw:: html
</details>
.. _Description:
Description
The task sdatmcor provides the capability of offline correction of
residual atmospheric features in the calibrated single-dish spectra
which result from the difference of elevation angle between ON_SOURCE
and OFF_SOURCE measurements.
The correction factor is derived from the atmosphere model based on
the atmospheric properties (temperature, pressure, etc.) measured
during the observation. The model is constructed by the atmosphere
(at) tool.
For spw selection, two selection parameters, *spw* and *outputspw*,
are available. The former specifies the data to be
corrected while the latter corresponds to the spw for output.
In practice, intersection of *spw* and *outputspw* is corrected.
For example, when `spw='19,23'` and `outputspw='19'`, spw 23 is not
corrected because data for spw 23 is not written to outfile so
that the correction is not meaningful.
For data selection parameters other than spw, only data selected
by data selection parameters are corrected and written to the outfile.
Note that *outfile* will have the data column DATA regardless of
what data column exists in *infile*.
.. rubric:: References
`Sawada, T. et al., 2021, PASP, 133, 034504 <https://doi.org/10.1088/1538-3873/abe0ab>`__ ( `arXiv:2101.11450 <https://arxiv.org/abs/2101.11450>`__ )
.. _Examples:
Examples
.. rubric:: Example 1
The simplest example that processes all the data.
::
sdatmcor(infile='sd_data.ms', datacolumn='float_data', outfile='sd_data.atmcor.ms', overwrite=True)
.. rubric:: Example 2
This example applies correction only to spw 23 but outputs all the data. Other spws are
included in outfile but are not corrected.
::
sdatmcor(infile='sd_data.ms', datacolumn='float_data', outfile='sd_data.atmcor.ms',
spw='23', overwrite=True)
.. rubric:: Example 3
This example applies correction only to spw 23 and output only spw 23. Note that the
only difference from Example 2 is that *outputspw* is set instead of *spw*.
::
sdatmcor(infile='sd_data.ms', datacolumn='float_data', outfile='sd_data.atmcor.ms',
outputspw='23', overwrite=True)
.. rubric:: Example 4 (not practical)
This example applies correction to spw 19 and 23 and output only spw 23. In this case,
correction was applied only to spw 23 because spw 19 is not supposed to be included in
*outfile*.
::
sdatmcor(infile='sd_data.ms', datacolumn='float_data', outfile='sd_data.atmcor.ms',
spw='19,23', outputspw='23', overwrite=True)
.. rubric:: Example 5
This example specifies scaling factor for the correction. The scaling factor can be
single float value, dictionary of the key-value pair of spw id and the float value
(e.g. *gainfactor={'23': 50.0, '25': 45.0}*), or name of the caltable that stores
scaling factor (e.g. *gainfactor='caltablename.tbl'*). Float value is set in this
example.
::
sdatmcor(infile='sd_data.ms', datacolumn='float_data', outfile='sd_data.atmcor.ms',
outputspw='23', gainfactor=50.0, overwrite=True)
.. rubric:: Example 6
This example shows how to customize atmospheric model.
::
sdatmcor(infile='sd_data.ms', datacolumn='float_data', outfile='sd_data.atmcor.ms',
outputspw='23', overwrite=True
atmtype=1, dtem_dh='-5.7K/km', h0='2010m',
atmdetail=True,
altitude='5.1km', temperature='290K', pressure='700hPa', humidity=30, pwv='0.1cm',
dp='10hPa', dpm=1.2, layerboundaries='800m,1.5km', layertemperature='250K,200K')
.. _Development:
Development
No additional development details
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _infile:
| ``infile (string='')`` - name of input MS.
.. _datacolumn:
| ``datacolumn (string='data')`` - name of data column to be used ["data", "float_data", or "corrected"]
.. _outfile:
| ``outfile (string='')`` - name of output MS.
.. _overwrite:
| ``overwrite (bool=False)`` - allow to overwrite the output file if already exists.
.. _field:
| ``field (string='')`` - Select fields. Use field id(s) or name(s).
| If field string is a non-negative integer, it is assumed to
| be a field index otherwise, it is assumed to be a field name.
| Default: ''= all fields
| Example:
| field='0~2'; field ids 0,1,2
| field='0,4,5~7'; field ids 0,4,5,6,7
| field='3C286,3C295'; field named 3C286 and 3C295
| field = '3,4C*'; field id 3, all names starting with 4C
.. _spw:
| ``spw (string='')`` - Select spectral windows
| Note that spw specifies the list of spw ids to apply correction.
| Spw ids to output should be specified by outputspw.
| Note also that channel selection is not available for this task.
| Default: ''=all spectral windows
| Example:
| spw='0~2,4'; spectral windows 0,1,2,4
| spw='<2'; spectral windows less than 2 (i.e. 0,1)
| spw='0,10'; spw 0,10
.. _scan:
| ``scan (string='')`` - Scan number range
| Default: '' (all)
| Example: scan='1~5'
.. _antenna:
| ``antenna (string='')`` - Select data based on antenna/baseline
| If antenna string is a non-negative integer, it is
| assumed to be an antenna index, otherwise, it is
| considered an antenna name.
| If specified selection doesn't contain any autocorrelation,
| the selection will be tweaked to include autocorrelation data.
| For example, 'PM02' will be interpreted as 'PM02&&&'.
| Default: '' (all)
| Example:
| antenna='5&6'; baseline between antenna index 5 and
| index 6.
| antenna='VA05&VA06'; baseline between VLA antenna 5
| and 6.
| antenna='5&6;7&8'; baselines 5-6 and 7-8
| antenna='5'; all baselines with antenna index 5
| antenna='05'; all baselines with antenna number 05
| (VLA old name)
| antenna='5,6,9'; all baselines with antennas 5,6,9
| index number
.. _correlation:
| ``correlation (string='')`` - Correlation (polarization) types or expression
| Default: '' (all correlations)
| Example: correlation='XX,YY'
.. _timerange:
| ``timerange (string='')`` - Range of time to select from data
| timerange = 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss'
| Note: if YYYY/MM/DD is missing date defaults to first
| day in data set
| Default: '' (all)
| Example:
| timerange='09:14:0~09:54:0' picks 40 min on first day
| timerange='25:00:00~27:30:00' picks 1 hr to 3 hr
| 30min on NEXT day
| timerange='09:44:00' pick data within one integration
| of time
| timerange='> 10:24:00' data after this time
.. _intent:
| ``intent (string='')`` - Scan Intent(s)
| Default: '' (all)
| Example:
| intent='TARGET_SOURCE'
| intent='TARGET_SOURCE1,TARGET_SOURCE2'
| intent='TARGET_POINTING*'
.. _observation:
| ``observation (string='')`` - Observation ID range
| Default: '' (all observations)
| Example: observation='0~5'
.. _feed:
| ``feed (string='')`` - feed selection
| Default: '' (all feeds)
| Example: feed='0,1'
.. _msselect:
| ``msselect (string='')`` - Complicated data selection using TaQL
| Complicated data selection that cannot be supported by other
| data selection parameters should be specified here using TaQL.
| See Casacore Note 199 for detailed syntax of TaQL:
| https://casacore.github.io/casacore-notes/199.html
| Default: '' (all data)
| Example:
| msselect='ABS(DATA) < 1 && ANTENNA1 == ANTENNA2 + 1'
| msselect='ROWNUMBER() < 100'
.. _outputspw:
| ``outputspw (string='')`` - select spws to output, same syntax of spw.("" = all)
| Note that outputspw specifies the list of spw ids to output.
| Spw ids to be corrected should be specified by spw.
| Note also that channel selection is not available for this task.
.. _gainfactor:
| ``gainfactor ({double, record, string}='1.0')`` - Gain factor to multiply correction term.
| In ALMA data reduction, intensity of calibrated spectra, antenna
| temperature Ta* in unit of Kelvin, is converted to Jansky (Jy)
| by multiplying conversion factor. This parameter is intended to
| apply exactly the same multiplicative factor to correction term.
| If no conversion is applied to spectral data, gainfactor should
| be 1.0, which means that the correction is in unit of Ta*.
| The value can be float, dict, or string. Default is 1.0.
| Float value is interpreted as fixed factor, which is applied to all spws.
| Dict should be the pair of spw id (key) and the factor to be applied (value).
| Key should be string rather than int.
| If string is given, it should be the name of caltable. For caltable,
| inverse square of stored value is applied.
| Default: 1.0
| Example: 10.0
| {'17': 45.0, '19': 43.5, '21': 42.0, '23': 40.0}
| 'k2jycal.tbl'
.. _dtem_dh:
| ``dtem_dh ({string, double}='')`` - temperature gradient [K/km], e.g. -5.6. ("" = Tool default)
| The value is directly passed to initialization method for ATM model.
| Float and string types are acceptable. Float value is interpreted as
| the value in K/km. String value should be the numeric value with unit
| such as '-5.6K/km'.
| Default: '' (tool default, -5.6K/km, is used)
.. _h0:
| ``h0 ({string, double}='')`` - scale height for water [km], e.g. 2.0. ("" = Tool default)
| The value is directly passed to initialization method for ATM model.
| Float and string types are acceptable. Float value is interpreted as
| the value in kilometer. String value should be the numeric value with
| unit compatible with length, such as '2km' or '2000m'.
.. _atmtype:
| ``atmtype (int=2)`` - Atmospheric type.
| The value is directly passed to initialization method for ATM model.
| The type should be specified as integer. Available options are,
| 1: tropical
| 2: mid latitude summer (default)
| 3: mid latitude winter
| 4: subarctic summer
| 5: subarctic winter
.. _atmdetail:
| ``atmdetail (bool=False)`` - Expose parameters for detailed configuration of ATM model if True.
| The following parameters are exposed to the user if atmdetail is True:
| altitude
| temperature
| pressure
| humidity
| pwv
| dp
| dpm
| layerboundaries
| layertemperature
.. _altitude:
| ``altitude ({string, double}='')`` - Site altitude [m].
| The value is directly passed to initialization method for ATM model.
| Float and string types are acceptable. Float value is interpreted as
| the value in meter. String value should be the numeric value with
| unit compatible with length, such as '5km' or '5000m'.
| Default value is taken from the input MS (ANTENNA table).
.. _temperature:
| ``temperature ({string, double}='')`` - Ambient temperature [K].
| The value is directly passed to initialization method for ATM model.
| Float and string types are acceptable. Float value is interpreted as
| the value in Kelvin. String value should be the numeric value with
| unit, such as '270K'.
| Default value is taken from the input MS (ASDM_CALATMOSPHERE table).
.. _pressure:
| ``pressure ({string, double}='')`` - Ambient pressure [mbar].
| The value is directly passed to initialization method for ATM model.
| Float and string types are acceptable. Float value is interpreted as
| the value in mbar. String value should be the numeric value with
| unit compatible with pressure, such as '1000mbar' or '1000hPa'.
| Default value is taken from the input MS (ASDM_CALATMOSPHERE table).
.. _humidity:
| ``humidity (double=-1)`` - Relative humidity [percent].
| If the value is explicitly specified, it should range from 0 to 100.
| Default value (-1) indicates that the value is taken from the input MS
| (ASDM_CALATMOSPHERE table).
.. _pwv:
| ``pwv ({string, double}='')`` - Zenith water vapor [mm].
| The value is directly passed to configuration method for ATM model.
| Float and string types are acceptable. Float value is interpreted as
| the value in millimeter. String value should be the numeric value with
| the unit compatible with length, such as '0.3mm'
| Default value is taken from the input MS (ASDM_CALWVR table).
.. _dp:
| ``dp ({string, double}='')`` - Initial pressure step.
| The value is directly passed to initialization method for ATM model.
| Float and string types are acceptable. Float value is interpreted as
| the value in mbar. String value should be the numeric value with
| unit compatible with pressure, such as '10mbar' or '10hPa'.
| Default value ('') indicates to use tool default (10mbar).
.. _dpm:
| ``dpm (double=-1)`` - Pressure multiplicative factor for steps.
| The value is directly passed to initialization method for ATM model.
| Default value (-1) indicates to use tool default (1.2).
.. _layerboundaries:
| ``layerboundaries ({string, stringVec, doubleVec}='')`` - Altitude of user-defined temperature profile.
| The value is directly passed to initialization method for ATM model.
| String, list of strings, and list of float values are acceptable.
| For list inputs, float values are interpreted as the value in meter
| while the string values should be the numeric value with the unit
| compatible with length.
| For string input, the value should be comma separated list of
| strings consisting of numeric value and the unit compatible with
| length.
| Number of values should be identical to the number for layertemperature.
| Default value ('') indicates to use tool default.
| Example: [1000, 2000]
| ['1km', '2km']
| '1km,2km'
.. _layertemperature:
| ``layertemperature ({string, stringVec, doubleVec}='')`` - User-defined temperature profile [K].
| The value is directly passed to initialization method for ATM model.
| String, list of strings, and list of float values are acceptable.
| For list inputs, float values are interpreted as the value in Kelvin
| while the string values should be the numeric value with unit.
| For string input, the value should be comma separated list of
| strings consisting of numeric value and unit.
| Number of values should be identical to the number for layerboundaries.
| Example: [250, 240]
| ['250K', '240K']
| '250K,240K'
"""
pass