sdatmcor

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='')[source]

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.

    atmdetail = True

    • 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)

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.

References

Sawada, T. et al., 2021, PASP, 133, 034504 ( arXiv:2101.11450 )

Examples

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)

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)

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)

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)

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)

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

No additional development details

Parameter Details

Detailed descriptions of each function parameter

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='') - 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 (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 (string='') - Scan number range
Default: ‘’ (all)
Example: scan=’1~5’
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 (string='') - Correlation (polarization) types or expression
Default: ‘’ (all correlations)
Example: correlation=’XX,YY’
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 (string='') - Scan Intent(s)
Default: ‘’ (all)
Example:
intent=’TARGET_SOURCE’
intent=’TARGET_SOURCE1,TARGET_SOURCE2’
intent=’TARGET_POINTING*’
observation (string='') - Observation ID range
Default: ‘’ (all observations)
Example: observation=’0~5’
feed (string='') - feed selection
Default: ‘’ (all feeds)
Example: feed=’0,1’
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 (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 ({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 ({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 ({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 (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 (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 ({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 ({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 ({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 (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 ({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 ({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 (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 ({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 ({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’