Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/cvel.py: 100%

27 statements  

« prev     ^ index     » next       coverage.py v7.6.4, created at 2024-11-01 07:19 +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 

13 

14class _cvel: 

15 """ 

16 cvel ---- regrid an MS to a new spectral window / channel structure or frame 

17 

18  

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. 

30  

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. 

35  

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. 

41 

42 --------- parameter descriptions --------------------------------------------- 

43 

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 RETURNS void 

65 

66 --------- examples ----------------------------------------------------------- 

67 

68  

69  

70 vis -- Name of input visibility file 

71 default: none; example: vis='ngc5921.ms' 

72  

73 outputvis -- Name of output measurement set (required) 

74 default: none; example: vis='ngc5921-regridded.ms' 

75  

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 

85  

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 

96  

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 

110  

111 selectdata -- Other data selection parameters 

112 default: True 

113  

114 >>> selectdata=True expandable parameters 

115  

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 

131  

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 

143  

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. 

149  

150 array -- Select data by (sub)array indices 

151 default: '' (all); example: 

152 array='0~2'; arrays 0 to 2 

153  

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. 

166  

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) 

203  

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' 

208  

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' 

213  

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' 

219  

220 veltype -- definition of velocity (in mode) 

221 default = 'radio' 

222  

223 hanning -- if true, Hanning smooth frequency channel data to remove Gibbs ringing 

224  

225 ================================================================== 

226  

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. 

238  

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. 

243  

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. 

249 

250 

251 """ 

252 

253 _info_group_ = """manipulation""" 

254 _info_desc_ = """regrid an MS to a new spectral window / channel structure or frame""" 

255 

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 

270 

271cvel = _cvel( ) 

272