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

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 polcal.xml #################### 

2##################### fc3d1d4a07231908b23e215ee75e4bbe ############################## 

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_polcal import polcal as _polcal_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 _polcal: 

15 """ 

16 polcal ---- Determine instrumental polarization calibrations 

17 

18  

19 The complex instrumental polarization factors (D-terms) for each antenna/spwid 

20 are determined from the data for the specified calibrator sources. Previous 

21 calibrations can be applied on the fly. 

22 

23 --------- parameter descriptions --------------------------------------------- 

24 

25 vis Name of input visibility file 

26 caltable Name of output gain calibration table 

27 field Select field using field id(s) or field name(s) 

28 spw Select spectral window/channels 

29 intent Select observing intent 

30 selectdata Other data selection parameters 

31 timerange Select data based on time range 

32 uvrange Select data within uvrange (default units meters) 

33 antenna Select data based on antenna/baseline 

34 scan Scan number range 

35 observation Select by observation ID(s) 

36 msselect Optional complex data selection (ignore for now) 

37 solint Solution interval 

38 combine Data axes which to combine for solve (obs, scan, spw, and/or field) 

39 preavg Pre-averaging interval (sec) 

40 refant Reference antenna name(s) 

41 minblperant Minimum baselines _per antenna_ required for solve 

42 minsnr Reject solutions below this SNR 

43 poltype Type of instrumental polarization solution (see help) 

44 smodel Point source Stokes parameters for source model. 

45 append Append solutions to the (existing) table 

46 docallib Use callib or traditional cal apply parameters 

47 callib Cal Library filename 

48 gaintable Gain calibration table(s) to apply 

49 gainfield Select a subset of calibrators from gaintable(s) 

50 interp Interpolation mode (in time) to use for each gaintable 

51 spwmap Spectral window mappings to form for gaintable(s) 

52 Only used if callib=False 

53 default: [] (apply solutions from each calibration spw to 

54 the same MS spw only) 

55 Any available calibration spw can be mechanically mapped to any  

56 MS spw.  

57 Examples: 

58 spwmap=[0,0,1,1] means apply calibration  

59 from cal spw = 0 to MS spw 0,1 and cal spw 1 to MS spws 2,3. 

60 spwmap=[[0,0,1,1],[0,1,0,1]] (use a list of lists for multiple 

61 gaintables) 

62 

63 --------- examples ----------------------------------------------------------- 

64 

65  

66  

67 The instrumental polarization factors (D-terms), the calibrator polarization, 

68 and the R-L polarization angle can be determined using polcal. The solutions 

69 can be obtained for each antenna/spwid and even individual channels, if desired. 

70 Previous calibrations of the total intensity data should be applied on the fly 

71 when running polcal, since polcal uses the 'data' column, not the 'corrected' 

72 column. 

73  

74 After calibrating the gain, bandpass, and (if relevant, for channelized data) 

75 cross-hand delay, the simplest way to calibrate the polarization data is: 

76  

77 a) Run polcal with poltype = 'D+QU' on the main 'calibrator' source. The D terms 

78 and polarization (QU) of the calibrator will be determined. Relatively good 

79 parallactic angle coverage is needed. 

80  

81 b) If there is little parallactic angle coverage, place the known polarization of 

82 the main calibrator (or 0) using setjy with the appropriate fluxdensity. Then 

83 run polcal with poltype = 'D'. Run plotcal with xaxis = 'real'; yaxis ='imag' 

84 to view solutions. It is best to use an unpolarized calibrator in this 

85 instance; large systematic offsets from zero indicate significant source 

86 polarization that will bias the polarization calibration. A mechanism 

87 to constrain this bias will be made available in the near future. 

88  

89 c) To determine R-L polarization angle, use setjy to put the fluxdensity of the 

90 polarization calibrator [I,Q,U,0.0] in the model column. For resolved sources 

91 put in values associated with an appropriate u-v range. Polarized models are 

92 not yet available for the major polarization standard sources, so very 

93 resolved polarized sources should not be used. 

94  

95 d) Run polcal with poltype = 'X' and include polarization standard. Make sure to 

96 include all previous calibrations, especially the D results. Run plotxy with 

97 correlation = 'RL LR' and make sure polarization angles are as expected. 

98  

99 e) Run applycal with all calibration table, include the D and X tables. Make sure 

100 that parang = T 

101  

102 NOTE: For very high dynamic range, use poltype='Df' or 'Df+QU' to determine 

103 D terms for each channel. Similarly, poltype='Xf' can 

104 be used to determine a channel-dependent R-L phase 

105 "bandpass". 

106 NOTE: Rather than use setjy in b and c above, the new smodel 

107 parameter may be used in polcal to specify a simple 

108 point source Stokes model. 

109  

110 Keyword arguments: 

111 vis -- Name of input visibility file 

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

113 caltable -- Name of output gain calibration table 

114 default: none; example: caltable='ngc5921.dcal' 

115  

116 --- Data Selection (see help par.selectdata for more detailed information) 

117  

118 field -- Select field using field id(s) or field name(s). 

119 [run listobs to obtain the list id's or names] 

120 default: ''=all fields. 

121 Most likely, the main calibrator source should be picked. 

122 If field string is a non-negative integer, it is assumed a field index 

123 otherwise, it is assumed a field name 

124 field='0~2'; field ids 0,1,2 

125 field='0,4,5~7'; field ids 0,4,5,6,7 

126 field='3C286,3C295'; field named 3C286 adn 3C295 

127 field = '3,4C*'; field id 3, all names starting with 4C 

128 spw -- Select spectral window/channels 

129 type 'help par.selection' for more examples. 

130 spw='0~2,4'; spectral windows 0,1,2,4 (all channels) 

131 spw='<2'; spectral windows less than 2 (i.e. 0,1) 

132 spw='0:5~61'; spw 0, channels 5 to 61, INCLUSIVE 

133 spw='*:5~61'; all spw with channels 5 to 62 

134 spw='0,10,3:3~45'; spw 0,10 all channels, spw 3, channels 3 to 45. 

135 spw='0~2:2~6'; spw 0,1,2 with channels 2 through 6 in each. 

136 spw='0:0~10;15~60'; spectral window 0 with channels 0-10,15-60 

137 NOTE ';' to separate channel selections 

138 spw='0:0~10^2,1:20~30^5'; spw 0, channels 0,2,4,6,8,10, 

139 spw 1, channels 20,25,30 

140 intent -- Select observing intent 

141 default: '' (no selection by intent) 

142 intent='*BANDPASS*' (selects data labelled with 

143 BANDPASS intent) 

144 selectdata -- Other data selection parameters 

145 default: True 

146 timerange -- Select data based on time range: 

147 default = '' (all); examples, 

148 timerange = 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss' 

149 Note: if YYYY/MM/DD is missing dat defaults to first day in data set 

150 timerange='09:14:0~09:54:0' picks 40 min on first day 

151 timerange= '25:00:00~27:30:00' picks 1 hr to 3 hr 30min on next day 

152 timerange='09:44:00' data within one integration of time 

153 timerange='>10:24:00' data after this time 

154 uvrange -- Select data within uvrange (default units meters) 

155 default: '' (all); example: 

156 uvrange='0~1000klambda'; uvrange from 0-1000 kilo-lambda 

157 uvrange='>4klambda';uvranges greater than 4 kilo-lambda 

158 antenna -- Select data based on antenna/baseline 

159 default: '' (all) 

160 If antenna string is a non-negative integer, it is assumed an antenna index 

161 otherwise, it is assumed as an antenna name 

162 antenna='5&6'; baseline between antenna index 5 and index 6. 

163 antenna='VA05&VA06'; baseline between VLA antenna 5 and 6. 

164 antenna='5&6;7&8'; baseline 5-6 and 7-8 

165 antenna='5'; all baselines with antenna index 5 

166 antenna='05'; all baselines with antenna name 05, i.e. VLA ant 5 

167 antenna='5,6,10'; all baselines with antennas 5, 6 and 10 

168 scan -- Scan number range 

169 observation -- Observation ID(s). 

170 default: '' = all 

171 example: '0~2,4' 

172 msselect -- Optional complex data selection (ignore for now) 

173  

174 --- Solution parameters 

175 poltype -- Type of instrumental polarization solution 

176 'D+QU' (or 'Df+QU') solve also for apparent source polarization (channelized D) 

177 Need relatively good parallactic angle coverage for this 

178 'D' (or 'Df') solve only for instrumental polarization (channelized). The 

179 I, Q, U flux density of the source can be placed in the model column using 

180 setjy. Use for poor parallactic angle coverage. 

181 'X' (or 'Xf') = solve only for position angle correction (channelized). 

182 The source must have its I, Q, U flux density in the model column 

183 or specified in smodel. If the source is resolved, use a limited 

184 uvrange that is appropriate. 

185 'D+X' (or 'Df+X') = solve also for position angle offset (channelized D) as 

186 well as the D-term. Not normally done. 

187 default: 'D+QU' 

188 The solution used the traditional linear approximation. Non-linearized options 

189 will be avaible soon. 

190 smodel -- Point source Stokes parameters for source model (experimental) 

191 default: [] (use MODEL_DATA column) 

192 examples: [1,0,0,0] (I=1, unpolarized) 

193 [5.2,0.2,0.3,0.0] (I=5.2, Q=0.2, U=0.3, V=0.0) 

194 solint -- Solution interval (units optional) 

195 default: 'inf' (~infinite, up to boundaries controlled by combine); 

196 Options: 'inf' (~infinite), 'int' (per integration), any float 

197 or integer value with or without units 

198 examples: solint='1min'; solint='60s', solint=60 --> 1 minute 

199 solint='0s'; solint=0; solint='int' --> per integration 

200 solint-'-1s'; solint='inf' --> ~infinite, up to boundaries 

201 enforced by combine 

202 combine -- Data axes to combine for solving 

203 default: 'obs,scan' --> solutions will break at field and spw 

204 boundaries but may extend over multiple obs and scans 

205 (per field and spw) up to solint. 

206 Options: '','obs','scan','spw',field', or any comma-separated 

207 combination in a single string 

208 example: combine='scan,spw' --> extend solutions over scan boundaries 

209 (up to the solint), and combine spws for solving 

210 preavg -- Pre-averaging interval (sec) 

211 default=300 

212 Interval to apply parallactic angle. 

213 refant -- Reference antenna name 

214 default: '' => refant = '0' 

215 example: refant='13' (antenna with index 13) 

216 refant='VA04' (VLA antenna #4) 

217 refant='EA02,EA23,EA13' (EVLA antenna EA02, use 

218 EA23 and EA13 as alternates if/when EA02 

219 drops out) 

220 Use 'go listobs' for antenna listing. 

221 USE SAME REFERENCE ANTENNA AS USED FOR I CALIBRATION. 

222 minblperant -- Minimum number of baselines required per antenna for each solve 

223 Antennas with fewer baaselines are excluded from solutions. Amplitude 

224 solutions with fewer than 4 baselines, and phase solutions with fewer 

225 than 3 baselines are only trivially constrained, and are no better 

226 than baseline-based solutions. 

227 default: 4 

228 example: minblperant=10 => Antennas participating on 10 or more 

229 baselines are included in the solve 

230 minsnr -- Reject solutions below this SNR 

231 default: 3.0 

232 append -- Append solutions to the (existing) table. Appended solutions 

233 must be derived from the same MS as the existing 

234 caltable, and solution spws must have the same 

235 meta-info (according to spw selection and solint) 

236 or be non-overlapping. 

237 default: False; overwrite existing table or make new table 

238  

239 --- Other calibrations to apply on the fly before determining polcal solution 

240  

241 docallib -- Control means of specifying the caltables: 

242 default: False ==> Use gaintable,gainfield,interp,spwmap,calwt 

243 If True, specify a file containing cal library in callib 

244 callib -- If docallib=True, specify a file containing cal 

245 library directives 

246  

247 gaintable -- Gain calibration table(s) to apply 

248 default: '' (none); BUT I CALIBRATION TABLES SHOULD GENERALLY BE INCLUDED 

249 examples: gaintable='ngc5921.gcal' 

250 gaintable=['ngc5921.ampcal','ngc5921.phcal'] 

251 gainfield -- Select a subset of calibrators from gaintable(s) 

252 default:'' ==> all sources in table; 

253 'nearest' ==> nearest (on sky) available field in table 

254 otherwise, same syntax as field 

255 example: gainfield='0~3' 

256 gainfield=['0~3','4~6'] means use field 0 through 3 

257 from first gain file, field 4 through 6 for second. 

258 interp -- Interpolation type (in time[,freq]) to use for each gaintable. 

259 When frequency interpolation is relevant (B, Df, Xf), 

260 separate time-dependent and freq-dependent interp 

261 types with a comma (freq _after_ the comma). 

262 Specifications for frequency are ignored when the 

263 calibration table has no channel-dependence. 

264 Time-dependent interp options ending in 'PD' enable a 

265 "phase delay" correction per spw for non-channel-dependent 

266 calibration types. 

267 For multi-obsId datasets, 'perobs' can be appended to 

268 the time-dependent interpolation specification to 

269 enforce obsId boundaries when interpolating in time. 

270 For multi-scan datasets, 'perscan' can be appended to 

271 the time-dependent interpolation specification to 

272 enforce scan boundaries when interpolating in time. 

273 default: '' --> 'linear,linear' for all gaintable(s) 

274 example: interp='nearest' (in time, freq-dep will be 

275 linear, if relevant) 

276 interp='linear,cubic' (linear in time, cubic 

277 in freq) 

278 interp='linearperobs,spline' (linear in time 

279 per obsId, 

280 spline in freq) 

281 interp=',spline' (spline in freq; linear in 

282 time by default) 

283 interp=['nearest,spline','linear'] (for multiple gaintables) 

284 Options: Time: 'nearest', 'linear' 

285 Freq: 'nearest', 'linear', 'cubic', 'spline' 

286 spwmap -- Spectral windows combinations to form for gaintable(s) 

287 default: [] (apply solutions from each spw to that spw only) 

288 Example: spwmap=[0,0,1,1] means apply the caltable solutions 

289 from spw = 0 to the spw 0,1 and spw 1 to spw 2,3. 

290 spwmap=[[0,0,1,1],[0,1,0,1]] 

291 

292 

293 """ 

294 

295 _info_group_ = """calibration""" 

296 _info_desc_ = """Determine instrumental polarization calibrations""" 

297 

298 def __call__( self, vis='', caltable='', field='', spw='', intent='', selectdata=True, timerange='', uvrange='', antenna='', scan='', observation='', msselect='', solint='inf', combine='obs,scan', preavg=float(300.0), refant='', minblperant=int(4), minsnr=float(3.0), poltype='D+QU', smodel=[ ], append=False, docallib=False, callib='', gaintable=[ ], gainfield=[ ], interp=[ ], spwmap=[ ] ): 

299 schema = {'vis': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'caltable': {'type': 'cStr', 'coerce': _coerce.to_str}, 'field': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spw': {'type': 'cStr', 'coerce': _coerce.to_str}, 'intent': {'type': 'cStr', 'coerce': _coerce.to_str}, 'selectdata': {'type': 'cBool'}, 'timerange': {'type': 'cStr', 'coerce': _coerce.to_str}, 'uvrange': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'antenna': {'type': 'cStr', 'coerce': _coerce.to_str}, 'scan': {'type': 'cStr', 'coerce': _coerce.to_str}, 'observation': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cInt'}]}, 'msselect': {'type': 'cStr', 'coerce': _coerce.to_str}, 'solint': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'combine': {'type': 'cStr', 'coerce': _coerce.to_str}, 'preavg': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'refant': {'type': 'cStr', 'coerce': _coerce.to_str}, 'minblperant': {'type': 'cInt'}, 'minsnr': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'poltype': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'Dflls', 'D', 'Dlls', 'D+QU', 'D+X', 'PosAng', 'X', 'Dfgen', 'Dfgen+X', 'Df+X', 'Df', 'Dgen+X', 'Dgen+QU', 'Df+QU', 'Dgen', 'Xfparang+QU', 'Xf', 'Dfgen+QU', 'Xj', 'Xparang+QU' ]}, 'smodel': {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}, 'append': {'type': 'cBool'}, 'docallib': {'type': 'cBool'}, 'callib': {'type': 'cStr', 'coerce': _coerce.to_str}, 'gaintable': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'gainfield': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'interp': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'spwmap': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}} 

300 doc = {'vis': vis, 'caltable': caltable, 'field': field, 'spw': spw, 'intent': intent, 'selectdata': selectdata, 'timerange': timerange, 'uvrange': uvrange, 'antenna': antenna, 'scan': scan, 'observation': observation, 'msselect': msselect, 'solint': solint, 'combine': combine, 'preavg': preavg, 'refant': refant, 'minblperant': minblperant, 'minsnr': minsnr, 'poltype': poltype, 'smodel': smodel, 'append': append, 'docallib': docallib, 'callib': callib, 'gaintable': gaintable, 'gainfield': gainfield, 'interp': interp, 'spwmap': spwmap} 

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

302 _logging_state_ = _start_log( 'polcal', [ 'vis=' + repr(_pc.document['vis']), 'caltable=' + repr(_pc.document['caltable']), 'field=' + repr(_pc.document['field']), 'spw=' + repr(_pc.document['spw']), 'intent=' + repr(_pc.document['intent']), 'selectdata=' + repr(_pc.document['selectdata']), 'timerange=' + repr(_pc.document['timerange']), 'uvrange=' + repr(_pc.document['uvrange']), 'antenna=' + repr(_pc.document['antenna']), 'scan=' + repr(_pc.document['scan']), 'observation=' + repr(_pc.document['observation']), 'msselect=' + repr(_pc.document['msselect']), 'solint=' + repr(_pc.document['solint']), 'combine=' + repr(_pc.document['combine']), 'preavg=' + repr(_pc.document['preavg']), 'refant=' + repr(_pc.document['refant']), 'minblperant=' + repr(_pc.document['minblperant']), 'minsnr=' + repr(_pc.document['minsnr']), 'poltype=' + repr(_pc.document['poltype']), 'smodel=' + repr(_pc.document['smodel']), 'append=' + repr(_pc.document['append']), 'docallib=' + repr(_pc.document['docallib']), 'callib=' + repr(_pc.document['callib']), 'gaintable=' + repr(_pc.document['gaintable']), 'gainfield=' + repr(_pc.document['gainfield']), 'interp=' + repr(_pc.document['interp']), 'spwmap=' + repr(_pc.document['spwmap']) ] ) 

303 task_result = None 

304 try: 

305 task_result = _polcal_t( _pc.document['vis'], _pc.document['caltable'], _pc.document['field'], _pc.document['spw'], _pc.document['intent'], _pc.document['selectdata'], _pc.document['timerange'], _pc.document['uvrange'], _pc.document['antenna'], _pc.document['scan'], _pc.document['observation'], _pc.document['msselect'], _pc.document['solint'], _pc.document['combine'], _pc.document['preavg'], _pc.document['refant'], _pc.document['minblperant'], _pc.document['minsnr'], _pc.document['poltype'], _pc.document['smodel'], _pc.document['append'], _pc.document['docallib'], _pc.document['callib'], _pc.document['gaintable'], _pc.document['gainfield'], _pc.document['interp'], _pc.document['spwmap'] ) 

306 except Exception as exc: 

307 _except_log('polcal', exc) 

308 raise 

309 finally: 

310 task_result = _end_log( _logging_state_, 'polcal', task_result ) 

311 return task_result 

312 

313polcal = _polcal( ) 

314