Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/sdcal.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 sdcal.xml ##################### 

2##################### 29a5e4b9883214251585a252bf79c0b8 ############################## 

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_sdcal import sdcal as _sdcal_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 _sdcal: 

15 """ 

16 sdcal ---- MS SD calibration task 

17 

18  

19 Task sdcal implements a single-dish data calibration scheme similar to that of 

20 interferometry, i.e., generate calibration tables (caltables) and apply them. 

21 Available calibration modes are: 

22 'ps', 'otfraster', 'otf' for sky calibration 

23 'tsys' for Tsys calibration 

24 Each mode generates a caltable. 

25 Caltables can be applied to the data by combining calibration 

26 modes with the keyword 'apply'. 

27  

28 Calibration is applicable for fast moving source even like the moon which moves 

29 quickly outside of the field of view (see the note of 'otf' mode in below). 

30  

31 Calibration mode must be set in accordance with the observing mode 

32 of the data. Use case for each mode is as follows: 

33 'ps': position switch (including OTF) with explicit 

34 reference (OFF) spectra 

35 'otfraster': raster OTF scan without explicit OFFs 

36 'otf': non-raster OTF (e.g. double-circle) scan without explicit OFFs 

37  

38 So, if the data contains explicit reference spectra, 'ps' should 

39 be used. Otherwise, 'otfraster' or 'otf' should be used. 

40 In 'otfraster' and 'otf' modes, an edge marker automatically marks spectra from 

41 specific regions of the observation pattern as reference (OFF) spectra. 

42 These specific regions are: 

43 - in 'otfraster' mode: regions near the beginning and the end of the raster 

44 scan lines. 

45 - in 'otf' mode: regions near the periphery of the observation pattern. 

46 Note: The 'otfraster' mode is designed for OTF observations without explicit OFF 

47 spectra. However, it should work even if explicit reference spectra exist. 

48 In that case, these spectra are ignored and spectra marked by edge marker are 

49 used as reference. 

50 Note: Detection of periphery scans in 'otf' mode is available for fast moving 

51 sources, e.g., Sun, Moon. It is often the case antennas keep track of source motion 

52 during the observations of moving sources so that the source is always at the map center. 

53 In order to handle such observations, pheriphery search is done in the source frame 

54 for known moving sources, in which the source is always at a rest position. 

55  

56 Apart from the way reference spectra are selected, the procedure to derive 

57 calibrated spectra is the same for all modes. Selected (or preset) 

58 OFF integrations are separated based on continuity in time domain, 

59 averaged in each segment, and then interpolated to timestamps for ON 

60 integrations. Effectively, it means that OFF integrations are 

61 averaged by each OFF spectrum for 'ps' mode, averaged by either ends 

62 of each raster row for 'otfraster' mode. The formula for calibrated 

63 spectrum is 

64  

65 Tsys * (ON - OFF) / OFF. 

66  

67  

68 

69 --------- parameter descriptions --------------------------------------------- 

70 

71 infile name of input SD dataset (must be MS) 

72 calmode SD calibration mode 

73 fraction fraction of the OFF data to mark 

74 noff number of the OFF data to mark 

75 width width of the pixel for edge detection 

76 elongated whether observed area is elongated in one direction or not 

77 applytable (List of) sky and/or tsys tables 

78 interp Interpolation type in time[,freq]. Valid options for time are "nearest", "linear", and "cubic", while valid options for frequency include "nearest", "linear", "cspline", or any numeric string that indicates an order of polynomial interpolation. You can specify interpolation type for time and frequency separately by joining two of the above options by comma (e.g., "linear,cspline"). 

79 spwmap A dictionary indicating spw combinations to apply Tsys calibration to target. The key should be spw for Tsys calibration and its associated value must be a list of science spws to be applied. 

80 outfile name of output file (See a WARNING in help) 

81 overwrite overwrite the output file if already exists 

82 field select data by field IDs and names, e.g. "3C2*" ("" = all) 

83 spw select data by spw IDs (spectral windows), e.g., "3,5,7" ("" = all) 

84 scan select data by scan numbers, e.g. "21~23" (""=all) 

85 intent select data by observation intent, e.g. "OBSERVE_TARGET#ON_SOURCE" (""=all) 

86 RETURNS void 

87 

88 --------- examples ----------------------------------------------------------- 

89 

90  

91 Keyword arguments: 

92 infile -- Name of input SD dataset 

93 calmode -- Calibration mode. If you want to generate calibration table 

94 or apply existing calibration tables, set calmode to a simple 

95 string. If you want to calibrate data on-the-fly, set calmode 

96 to a composite (comma-separated) string. So far, sky calibration has 

97 three types, 'ps', 'otfraster' and 'otf'. If observation is 

98 configured to observe reference position, calmode must be 

99 'ps'. Otherwise, 'otfraster' or 'otf' should be used. 

100 options: 'ps','otfraster','otf','tsys','apply' 

101 default: 'ps' 

102 example: Here is an example for composite calmode. 

103 'ps,apply' (do sky cal and apply) 

104 'ps,tsys,apply' (do sky and Tsys cal and apply) 

105 >>> calmode expandable parameter 

106 fraction -- Edge marker parameter of 'otfraster'. 

107 Specify a number of OFF integrations (at each 

108 side of the raster rows in 'otfraster' mode) 

109 as a fraction of total number of integrations. 

110 In 'otfraster' mode, number of integrations 

111 to be marked as OFF, n_off, is determined by 

112 the following formula, 

113  

114 n_off = floor(fraction * n), 

115  

116 where n is number of integrations per raster 

117 row. Note that n_off from both sides will be 

118 marked as OFF so that twice of specified 

119 fraction will be marked at most. For example, 

120 if you specify fraction='10%', resultant 

121 fraction of OFF integrations will be 20% at 

122 most. 

123 default: '10%' 

124 options: '20%' in string style or float value less 

125 than 1.0 (e.g. 0.15). 

126 'auto' is available only for 'otfraster'. 

127 noff -- Edge marking parameter for 'otfraster'. 

128 It is used to specify a number of OFF spectra near 

129 edge directly. Value of noff comes before setting 

130 by fraction. Note that n_off from both sides will 

131 be marked as OFF so that twice of specified noff 

132 will be marked at most. 

133 default: -1 (use fraction) 

134 options: any positive integer 

135  

136 applytable -- List of sky/Tsys calibration tables you want to 

137 apply. 

138 default: '' 

139 interp -- Interpolation method in time and frequency axis. 

140 Set comma separated method strings if you want 

141 to use different interpolation in time and 

142 frequency. 

143 options: 'linear', 'nearest', 'cspline', 'cubic', 

144 any numeric string indicating an order 

145 of polynomial. 

146 Note that 'cubic' is available for time only, 

147 and that 'cspline' and numeric strings are 

148 available for frequency only. 

149 default: '' (linear in time and frequency) 

150 example: 'linear,cspline' (linear in time, cubic 

151 spline in frequency) 

152 'linear,3' (linear in time, third order 

153 polynomial in frequency) 

154 'nearest' (nearest in time and frequency) 

155 spwmap -- Dictionary defining transfer of Tsys calibration. 

156 Key must be spw for Tsys and its value must be 

157 a list of spws for science target. 

158 default: {} 

159 example: {1: [5,6], 3: [7,8]} 

160 Tsys in spw 1 is transferred to spws 5 and 6 

161 while Tsys in spw 3 is to spws 7 and 8. 

162 field -- select data by field IDs and names 

163 default: '' (use all fields) 

164 example: field='3C2*' (all names starting with 3C2) 

165 field='0,4,5~7' (field IDs 0,4,5,6,7) 

166 field='0,3C273' (field ID 0 or field named 3C273) 

167 this selection is in addition to the other selections to data 

168 spw -- select data by spw IDs (spectral windows) 

169 NOTE this task only supports spw ID selction and ignores channel 

170 selection. 

171 default: '' (use all spws and channels) 

172 example: spw='3,5,7' (spw IDs 3,5,7; all channels) 

173 spw='<2' (spw IDs less than 2, i.e., 0,1; all channels) 

174 spw='30~45GHz' (spw IDs with the center frequencies in range 30-45GHz; all channels) 

175 this selection is in addition to the other selections to data 

176 NOTE spw input must be '' (''= all) in calmode='tsys'. 

177 scan -- select data by scan numbers 

178 default: '' (use all scans) 

179 example: scan='21~23' (scan IDs 21,22,23) 

180 this selection is in addition to the other selections to data 

181 NOTE scan input must be '' (''= all) in calmode='tsys'. 

182 outfile -- Name of output file 

183 NOTE if you omit and calmode doesn't include 'apply', the task 

184 will use default outfile name based on infile and predefined 

185 suffix ('_sky' for sky, '_tsys' for Tsys). 

186 default: '' (<infile>_<suffix> for calibration) 

187 overwrite -- overwrite the output file if already exists 

188 options: (bool) True,False 

189 default: False 

190 NOTE this parameter is ignored when outform='ASCII' 

191  

192  

193 DESCRIPTION: 

194  

195 Task sdcal is an implementation of a calibration scheme like as 

196 interferometry, i.e., generate caltables and apply them. Available 

197 calibration modes are 'ps', 'otfraster', 'otf', and 'tsys'. 

198 Those modes generates caltables for sky or Tsys calibration. 

199 The caltables can be applied to the data by using calmode 'apply'. 

200  

201 First three calibration modes, 'ps', 'otfraster', and 'otf', 

202 generate sky calibration tables. The user should choose appropriate 

203 calibration mode depending on the data. Use case for each mode is 

204 as follows: 

205  

206 'ps': position switch (including OTF) with explicit 

207 reference (OFF) spectra 

208 'otfraster': raster OTF scan without explicit OFFs 

209 'otf': fast-scan observation with Lissajous or 

210 double-circle trajectory 

211  

212 So, if the data contains explicit reference spectra, 'ps' should 

213 be used. The 'otfraster' mode is appropriate for raster OTF. 

214 For non-raster OTF data, 'otf' mode is available to support fast- 

215 scanning observation. In 'otfraster' mode, the task first try to 

216 find several integrations near edge as OFF spectra, then the data 

217 are calibrated using those OFFs. If the observing pattern is raster, 

218 you should use the 'otfraster' mode to calibrate data. 

219 The 'otfraster' mode is designed for OTF observations without 

220 explicit OFF spectra. However, these modes should work even if 

221 explicit reference spectra exist. In this case, these spectra will be 

222 ignored and spectra near edges detected by edge marker will be used as 

223 reference. In 'otf' mode, the task detects integrations near edges of 

224 observed area, and detected integrations are regarded as OFFs. 

225 This mode is specifically designed for fast-scan mode, which takes 

226 the data contiguously by moving antenna along trajectory that 

227 imitates random spatial data sampling, which is implemented as 

228 either Lissajous or double-circle pattern. 

229  

230  

231 Except for how to choose OFFs, the procedure to derive calibrated 

232 spectra is common for the above three modes. Selected (or preset) OFF 

233 integrations are separated by its continuity in time domain, averaged in 

234 each segment, then interpolated to timestamps for ON integrations. 

235 Effectively, it means that OFF integrations are averaged by each 

236 OFF spectrum for 'ps' mode, averaged by either ends of each raster 

237 row for 'otfraster' mode. The formula for calibrated spectrum 

238 is 

239  

240 Tsys * (ON - OFF) / OFF. 

241  

242 You can calibrate data on-the-fly like sdcal task by setting 

243 calmode to a composite calmode string separated by comma. 

244 For example, calmode='ps,apply' means doing sky calibration and 

245 apply it on-the-fly. In this case, caltable is generated as a 

246 temporary plain table and will be deleted at the end. 

247 Allowed calibration modes in this task is as follows: 

248  

249 ps 

250 generate sky caltable using 'ps' mode 

251 otfraster 

252 generate sky caltable using 'otfraster' mode 

253 otf 

254 generate sky caltable using 'otf' mode 

255 tsys 

256 generate tsys caltable 

257 apply 

258 apply caltables specified by applytable parameter 

259 ps,apply 

260 generate temporary sky caltable using 'ps' mode and 

261 apply it. also apply caltables specified by applytable 

262 ps,tsys,apply 

263 generate temporary sky caltable using 'ps' mode as well 

264 as temporary tsys caltable, and apply them. 

265 otfraster,apply 

266 generate temporary sky caltable using 'otfraster' mode 

267 and apply it. also apply caltables specified by applytable 

268 otfraster,tsys,apply 

269 generate temporary sky caltable using 'otfraster' mode 

270 as well as temporary tsys caltable, and apply them. 

271 otf,apply 

272 generate temporary sky caltable using 'otf' mode 

273 and apply it. also apply caltables specified by applytable 

274 otf,tsys,apply 

275 generate temporary sky caltable using 'otf' mode 

276 as well as temporary tsys caltable, and apply them. 

277  

278 There are several control parameters for sky/Tsys calibration and 

279 application of caltables. See the above parameter description. 

280  

281 In ALMA, Tsys measurement is usually done using different spectral 

282 setup from spectral windows for science target. In this case, sdcal 

283 transfers Tsys values to science spectral windows in the application 

284 stage. To do that, the user has to give a list of spectral windows for 

285 Tsys measurement as well as mapping between spectral windows for Tsys 

286 measurement and scicence target. These can be specified by parameters 

287 'tsysspw' and 'spwmap', which are defined as subparameters of 'calmode'. 

288 For example, suppose that Tsys measurements for science windows 17, 19, 

289 21, and 23 are done in spw 9, 11, 13, and 15, respectively. 

290 In this case, tsysspw and spwmap should be specified as follows: 

291  

292 tsysspw = '9,11,13,15' 

293 spwmap = {9:[17],11:[19],13:[21],15:[23]} 

294  

295 Below is an example of full specification of task parameters for calmode 

296 of 'ps,tsys,apply': 

297  

298 default(sdcal) 

299 infile = 'foo.ms' 

300 calmode = 'ps,tsys,apply' 

301 spw = '' 

302 tsysspw = '9,11,13,15' 

303 spwmap = {9:[17],11:[19],13:[21],15:[23]} 

304 sdcal() 

305  

306 Note that, in contrast to applycal task, spwmap must be a dictionary 

307 with Tsys spectral window as key and a list of corresponding science 

308 spectral window as value. Note also that the parameter 'spw' should 

309 not be used to specify a list of spectral windows for Tsys measurement. 

310 It is intended to select data to be calibrated so that the list should 

311 contain spectral windows for both science target and Tsys measurement. 

312 The task will fail if you use 'spw' instead of 'tsysspw'. 

313  

314  

315 For Tsys calibration, the user is able to choose whether Tsys is 

316 averaged in spectral axis or not. If tsysavg is False (default), 

317 resulting Tsys is spectral value. On the other hand, when tsysavg 

318 is True, Tsys is averaged in spectral axis before output. The channel 

319 range for averaging is whole channels by default. If channel range is 

320 specified by tsysspw string, it is used for averaging. The user can 

321 specify channel range with ms selection syntax. For example, 

322  

323 tsysspw = '1:0~100' 

324  

325 specifies spw 1 for Tsys calibration and channel range between channel 

326 0 and 100 for averaging. You can specify more than one ranges per spw. 

327  

328 tsysspw = '1:0~100;200~400' 

329  

330 In this case, selected ranges are between 0 and 100 plus 200 and 400. 

331 Note that even if multiple ranges are selected, the task average whole 

332 ranges together and output single averaged value. You can specify multiple 

333 spws by separating comma. 

334  

335 tsysspw = '1:0~100,3:400~500' 

336 Note that specified channel range is ignored if tsysavg is False. 

337  

338 

339 

340 """ 

341 

342 _info_group_ = """single dish""" 

343 _info_desc_ = """ MS SD calibration task""" 

344 

345 def __call__( self, infile='', calmode='ps', fraction='10%', noff=int(-1), width=float(0.5), elongated=False, applytable='', interp='', spwmap={ }, outfile='', overwrite=False, field='', spw='', scan='', **kwargs ): 

346 schema = {'infile': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'calmode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'apply', 'ps,apply', 'otf,apply', 'ps,tsys,apply', 'tsys,apply', 'tsys', 'otf,tsys,apply', 'otf', 'otfraster', 'otfraster,tsys,apply', 'ps', 'otfraster,apply' ]}, 'fraction': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'noff': {'type': 'cInt'}, 'width': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'elongated': {'type': 'cBool'}, 'applytable': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'interp': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spwmap': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'outfile': {'type': 'cStr', 'coerce': _coerce.to_str}, 'overwrite': {'type': 'cBool'}, 'field': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spw': {'type': 'cStr', 'coerce': _coerce.to_str}, 'scan': {'type': 'cStr', 'coerce': _coerce.to_str}, 'intent': {'type': 'cStr', 'coerce': _coerce.to_str}} 

347 doc = dict( {'infile': infile, 'calmode': calmode, 'fraction': fraction, 'noff': noff, 'width': width, 'elongated': elongated, 'applytable': applytable, 'interp': interp, 'spwmap': spwmap, 'outfile': outfile, 'overwrite': overwrite, 'field': field, 'spw': spw, 'scan': scan}, **kwargs) 

348 assert _pc.validate(doc,schema), create_error_string(_pc.errors) 

349 _logging_state_ = _start_log( 'sdcal', [ 'infile=' + repr(_pc.document['infile']), 'calmode=' + repr(_pc.document['calmode']), 'fraction=' + repr(_pc.document['fraction']), 'noff=' + repr(_pc.document['noff']), 'width=' + repr(_pc.document['width']), 'elongated=' + repr(_pc.document['elongated']), 'applytable=' + repr(_pc.document['applytable']), 'interp=' + repr(_pc.document['interp']), 'spwmap=' + repr(_pc.document['spwmap']), 'outfile=' + repr(_pc.document['outfile']), 'overwrite=' + repr(_pc.document['overwrite']), 'field=' + repr(_pc.document['field']), 'spw=' + repr(_pc.document['spw']), 'scan=' + repr(_pc.document['scan']), '**kwargs=' + repr(kwargs) ] ) 

350 task_result = None 

351 try: 

352 task_result = _sdcal_t( _pc.document['infile'], _pc.document['calmode'], _pc.document['fraction'], _pc.document['noff'], _pc.document['width'], _pc.document['elongated'], _pc.document['applytable'], _pc.document['interp'], _pc.document['spwmap'], _pc.document['outfile'], _pc.document['overwrite'], _pc.document['field'], _pc.document['spw'], _pc.document['scan'], **kwargs ) 

353 except Exception as exc: 

354 _except_log('sdcal', exc) 

355 raise 

356 finally: 

357 task_result = _end_log( _logging_state_, 'sdcal', task_result ) 

358 return task_result 

359 

360sdcal = _sdcal( ) 

361