Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/cvel.py: 56%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 19:53 +0000
1##################### generated by xml-casa (v2) from cvel.xml ######################
2##################### 0547fb425e17ddf38c97521fa4ec472a ##############################
3from __future__ import absolute_import
4import numpy
5from casatools.typecheck import CasaValidator as _val_ctor
6_pc = _val_ctor( )
7from casatools.coercetype import coerce as _coerce
8from casatools.errors import create_error_string
9from .private.task_cvel import cvel as _cvel_t
10from casatasks.private.task_logging import start_log as _start_log
11from casatasks.private.task_logging import end_log as _end_log
12from casatasks.private.task_logging import except_log as _except_log
14class _cvel:
15 """
16 cvel ---- regrid an MS to a new spectral window / channel structure or frame
19 The intent of cvel is to transform channel labels and the
20 visibilities to a spectral reference frame which is appropriate
21 for the science analysis, e.g. from TOPO to LSRK to correct for
22 Doppler shifts throughout the time of the observation. Naturally,
23 this will change the shape of the spectral feature to some extent.
24 According to the Nyquist theorem you should oversample a spectrum
25 with twice the numbers of channels to retain the shape. Based on
26 some tests, however, we recommend to observe with at least
27 3-4 times the number of channels for each significant spectral
28 feature (like 3-4 times the linewidth). This will minimize
29 regridding artifacts in cvel.
31 If cvel has already established the grid that is desired for the
32 imaging, clean should be run with exactly the same frequency/velocity
33 parameters as used in cvel in order to avoid additional regridding in
34 clean.
36 Hanning smoothing is optionally offered in cvel, but tests have
37 shown that already the regridding process itself, if it involved
38 a transformation from TOPO to a non-terrestrial reference frame,
39 implies some smoothing (due to channel interpolation) such that
40 Hanning smoothing may not be necessary.
42 --------- parameter descriptions ---------------------------------------------
44 vis Name of input measurement set
45 outputvis Name of output measurement set
46 passall Pass through (write to output MS) non-selected data with no change
47 field Select field using field id(s) or field name(s)
48 spw Select spectral window/channels
49 selectdata Other data selection parameters
50 antenna Select data based on antenna/baseline
51 timerange Range of time to select from data
52 scan scan number range
53 array (sub)array indices
54 mode Regridding mode
55 nchan Number of channels in output spw (-1=all). Used for regridding, together with \'start\' and \'width\'.
56 start Start of the output visibilities. Used for regridding, together with \'width\' and \'nchan\'. It can be in different units, depending on the regridding mode: first input channel (mode=\'channel\'), first velocity (mode=\'velocity\'), or first frequency (mode=\'frequency\'). Example values: \'5\', \'0.0km/s\', \'1.4GHz\', for channel, velocity, and frequency modes, respectively.
57 width Channel width of the output visibilities. Used for regridding, together with \'start\', and \'nchan\'. It can be in different units, depending on the regridding mode: number of input channels (mode=\'channel\'), velocity (mode=\'velocity\'), or frequency (mode=\'frequency\'. Example values: \'2\', \'1.0km/s\', \'1.0kHz\', for channel, velocity, and frequency modes, respectively.
58 interpolation Spectral interpolation method
59 phasecenter Phase center direction to be used for the spectral coordinate transformation: direction measure or field index
60 restfreq rest frequency (see help)
61 outframe Output frame (not case-sensitive, \'\'=keep input frame)
62 veltype velocity definition
63 hanning If true, Hanning smooth data before regridding to remove Gibbs ringing.
64 [1;42mRETURNS[1;m void
66 --------- examples -----------------------------------------------------------
70 vis -- Name of input visibility file
71 default: none; example: vis='ngc5921.ms'
73 outputvis -- Name of output measurement set (required)
74 default: none; example: vis='ngc5921-regridded.ms'
76 passall -- if False, data not meeting the selection is omitted/deleted
77 or flagged (if in-row); if True, data not meeting the selection
78 on field and spw is passed through without modification
79 default: False; example:
80 field='NGC5921'
81 passall=False : only data from NGC5921 is included in output MS,
82 no data from other fields (e.g. 1331+305) is included
83 passall=True : data from NGC5921 is transformed by cvel, all other
84 fields are passed through unchanged
86 field -- Select fields in mosaic. Use field id(s) or field name(s).
87 ['go listobs' to obtain the list id's or names]
88 default: ''= all fields
89 If field string is a non-negative integer, it is assumed to
90 be a field index otherwise, it is assumed to be a
91 field name
92 field='0~2'; field ids 0,1,2
93 field='0,4,5~7'; field ids 0,4,5,6,7
94 field='3C286,3C295'; field named 3C286 and 3C295
95 field = '3,4C*'; field id 3, all names starting with 4C
97 spw --Select spectral window/channels
98 NOTE: This selects the data passed as the INPUT to mode
99 default: ''=all spectral windows and channels
100 spw='0~2,4'; spectral windows 0,1,2,4 (all channels)
101 spw='0:5~61'; spw 0, channels 5 to 61
102 spw='<2'; spectral windows less than 2 (i.e. 0,1)
103 spw='0,10,3:3~45'; spw 0,10 all channels, spw 3,
104 channels 3 to 45.
105 spw='0~2:2~6'; spw 0,1,2 with channels 2 through 6 in each.
106 spw='0:0~10;15~60'; spectral window 0 with channels
107 0-10,15-60
108 spw='0:0~10,1:20~30,2:1;2;3'; spw 0, channels 0-10,
109 spw 1, channels 20-30, and spw 2, channels, 1,2 and 3
111 selectdata -- Other data selection parameters
112 default: True
114 >>> selectdata=True expandable parameters
116 antenna -- Select data based on antenna/baseline
117 default: '' (all)
118 If antenna string is a non-negative integer, it is
119 assumed to be an antenna index, otherwise, it is
120 considered an antenna name.
121 antenna='5&6'; baseline between antenna index 5 and
122 index 6.
123 antenna='VA05&VA06'; baseline between VLA antenna 5
124 and 6.
125 antenna='5&6;7&8'; baselines 5-6 and 7-8
126 antenna='5'; all baselines with antenna index 5
127 antenna='05'; all baselines with antenna number 05
128 (VLA old name)
129 antenna='5,6,9'; all baselines with antennas 5,6,9
130 index numbers
132 timerange -- Select data based on time range:
133 default = '' (all); examples,
134 timerange = 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss'
135 Note: if YYYY/MM/DD is missing date defaults to first
136 day in data set
137 timerange='09:14:0~09:54:0' picks 40 min on first day
138 timerange= '25:00:00~27:30:00' picks 1 hr to 3 hr
139 30min on NEXT day
140 timerange='09:44:00' pick data within one integration
141 of time
142 timerange='>10:24:00' data after this time
144 scan -- Scan number range.
145 default: '' (all)
146 example: scan='1~5'
147 Check 'go listobs' to insure the scan numbers are in
148 order.
150 array -- Select data by (sub)array indices
151 default: '' (all); example:
152 array='0~2'; arrays 0 to 2
154 mode -- Frequency Specification:
155 NOTE: See examples below:
156 default: 'channel'
157 mode = 'channel'; Use with nchan, start, width to specify
158 output spw. Produces equidistant grid based on first
159 selected channel. See examples below.
160 mode = 'velocity', means channels are specified in
161 velocity.
162 mode = 'frequency', means channels are specified in
163 frequency.
164 mode = 'channel_b', alternative 'channel' mode.
165 Does not force an equidistant grid. Faster.
167 >>> mode expandable parameters
168 Start, width are given in units of channels, frequency
169 or velocity as indicated by mode
170 nchan -- Number of channels in output spw
171 default: -1 = all channels; example: nchan=3
172 start -- Start or end input channel (zero-based) depending on the sign of the width parameter
173 default=0; example: start=5
174 width -- Output channel width in units of the input
175 channel width (sign indicates whether the start parameter is lower(+) or upper(-) end of the range)
176 default=1; example: width=4
177 interpolation -- Interpolation method (linear, nearest, cubic, spline, fftshift)
178 default = 'linear'
179 examples:
180 spw = '0,1'; mode = 'channel'
181 will produce a single spw containing all channels in spw
182 0 and 1
183 spw='0:5~28^2'; mode = 'channel'
184 will produce a single spw made with channels
185 (5,7,9,...,25,27)
186 spw = '0'; mode = 'channel': nchan=3; start=5; width=4
187 will produce an spw with 3 output channels
188 new channel 1 contains data from channels (5+6+7+8)
189 new channel 2 contains data from channels (9+10+11+12)
190 new channel 3 contains data from channels (13+14+15+16)
191 spw = '0:0~63^3'; mode='channel'; nchan=21; start = 0;
192 width = 1
193 will produce an spw with 21 channels
194 new channel 1 contains data from channel 0
195 new channel 2 contains data from channel 2
196 new channel 21 contains data from channel 61
197 spw = '0:0~40^2'; mode = 'channel'; nchan = 3; start =
198 5; width = 4
199 will produce an spw with three output channels
200 new channel 1 contains channels (5,7)
201 new channel 2 contains channels (13,15)
202 new channel 3 contains channels (21,23)
204 phasecenter -- Direction measure or fieldid. To be used in mosaics to indicate
205 the center direction to be used in the spectral coordinate transformation.
206 default: '' => first field selected ; example: phasecenter=6
207 or phasecenter='J2000 19h30m00 -40d00m00'
209 restfreq -- Specify rest frequency to use for output visibilities
210 default='' Occasionally it is necessary to set this (for
211 example some VLA spectral line data). For example for
212 NH_3 (1,1) put restfreq='23.694496GHz'
214 outframe -- output reference frame (not case-sensitive)
215 possible values: LSRK, LSRD, BARY, GALACTO, LGROUP, CMB, GEO, TOPO, or SOURCE
216 (SOURCE is meant for solar system work and corresponds to GEO + radial velocity
217 correction for ephemeris objects).
218 default='' (keep original reference frame) ; example: outframe='BARY'
220 veltype -- definition of velocity (in mode)
221 default = 'radio'
223 hanning -- if true, Hanning smooth frequency channel data to remove Gibbs ringing
225 ==================================================================
227 The intent of cvel is to transform channel labels and the
228 visibilities to a spectral reference frame which is appropriate
229 for the science analysis, e.g. from TOPO to LSRK to correct for
230 Doppler shifts throughout the time of the observation. Naturally,
231 this will change the shape of the spectral feature to some extent.
232 According to the Nyquist theorem you should oversample a spectrum
233 with twice the numbers of channels to retain the shape. Based on
234 some tests, however, we recommend to observe with at least
235 3-4 times the number of channels for each significant spectral
236 feature (like 3-4 times the linewidth). This will minimize
237 regridding artifacts in cvel.
239 If cvel has already established the grid that is desired for the
240 imaging, clean should be run with exactly the same frequency/velocity
241 parameters as used in cvel in order to avoid additional regridding in
242 clean.
244 Hanning smoothing is optionally offered in cvel, but tests have
245 shown that already the regridding process itself, if it involved
246 a transformation from TOPO to a non-terrestrial reference frame,
247 implies some smoothing (due to channel interpolation) such that
248 Hanning smoothing may not be necessary.
251 """
253 _info_group_ = """manipulation"""
254 _info_desc_ = """regrid an MS to a new spectral window / channel structure or frame"""
256 def __call__( self, vis='', outputvis='', passall=False, field='', spw='', selectdata=True, antenna='', timerange='', scan='', array='', mode='channel', nchan=int(-1), start=int(0), width=int(1), interpolation='linear', phasecenter='', restfreq='', outframe='', veltype='radio', hanning=False ):
257 schema = {'vis': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'outputvis': {'type': 'cStr', 'coerce': _coerce.to_str}, 'passall': {'type': 'cBool'}, 'field': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, {'type': 'cInt'}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}]}, 'spw': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, {'type': 'cInt'}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}]}, 'selectdata': {'type': 'cBool'}, 'antenna': {'type': 'cStr', 'coerce': _coerce.to_str}, 'timerange': {'type': 'cStr', 'coerce': _coerce.to_str}, 'scan': {'type': 'cStr', 'coerce': _coerce.to_str}, 'array': {'type': 'cStr', 'coerce': _coerce.to_str}, 'mode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'channel', 'velocity', 'frequency', 'channel_b' ]}, 'nchan': {'type': 'cInt'}, 'start': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'width': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'interpolation': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'nearest', 'linear', 'NEAREST', 'FFTSHIFT', 'spline', 'fftshift', 'LINEAR', 'SPLINE', 'CUBIC', 'cubic' ]}, 'phasecenter': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'restfreq': {'type': 'cStr', 'coerce': _coerce.to_str}, 'outframe': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'SOURCE', 'LSRK', 'CMB', 'geo', 'source', 'bary', 'GALACTO', 'GEO', 'TOPO', 'LSRD', 'lsrk', 'topo', 'LGROUP', 'BARY', 'lsrd', 'cmb', 'galacto', 'lgroup', '' ]}, 'veltype': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'optical', 'radio', 'OPTICAL', 'RADIO' ]}, 'hanning': {'type': 'cBool'}}
258 doc = {'vis': vis, 'outputvis': outputvis, 'passall': passall, 'field': field, 'spw': spw, 'selectdata': selectdata, 'antenna': antenna, 'timerange': timerange, 'scan': scan, 'array': array, 'mode': mode, 'nchan': nchan, 'start': start, 'width': width, 'interpolation': interpolation, 'phasecenter': phasecenter, 'restfreq': restfreq, 'outframe': outframe, 'veltype': veltype, 'hanning': hanning}
259 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
260 _logging_state_ = _start_log( 'cvel', [ 'vis=' + repr(_pc.document['vis']), 'outputvis=' + repr(_pc.document['outputvis']), 'passall=' + repr(_pc.document['passall']), 'field=' + repr(_pc.document['field']), 'spw=' + repr(_pc.document['spw']), 'selectdata=' + repr(_pc.document['selectdata']), 'antenna=' + repr(_pc.document['antenna']), 'timerange=' + repr(_pc.document['timerange']), 'scan=' + repr(_pc.document['scan']), 'array=' + repr(_pc.document['array']), 'mode=' + repr(_pc.document['mode']), 'nchan=' + repr(_pc.document['nchan']), 'start=' + repr(_pc.document['start']), 'width=' + repr(_pc.document['width']), 'interpolation=' + repr(_pc.document['interpolation']), 'phasecenter=' + repr(_pc.document['phasecenter']), 'restfreq=' + repr(_pc.document['restfreq']), 'outframe=' + repr(_pc.document['outframe']), 'veltype=' + repr(_pc.document['veltype']), 'hanning=' + repr(_pc.document['hanning']) ] )
261 task_result = None
262 try:
263 task_result = _cvel_t( _pc.document['vis'], _pc.document['outputvis'], _pc.document['passall'], _pc.document['field'], _pc.document['spw'], _pc.document['selectdata'], _pc.document['antenna'], _pc.document['timerange'], _pc.document['scan'], _pc.document['array'], _pc.document['mode'], _pc.document['nchan'], _pc.document['start'], _pc.document['width'], _pc.document['interpolation'], _pc.document['phasecenter'], _pc.document['restfreq'], _pc.document['outframe'], _pc.document['veltype'], _pc.document['hanning'] )
264 except Exception as exc:
265 _except_log('cvel', exc)
266 raise
267 finally:
268 task_result = _end_log( _logging_state_, 'cvel', task_result )
269 return task_result
271cvel = _cvel( )