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

2##################### 00ebb1489d4e63a2ce3f6c2e5a10db6e ############################## 

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_setjy import setjy as _setjy_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 _setjy: 

15 """ 

16 setjy ---- Fills the model column with the visibilities of a calibrator 

17 

18  

19 This task places the model visibility amp and phase associated with a 

20 specified clean components image into the model column of the data 

21 set. The flux density (I,Q,U,V) for a point source calibrator can be 

22 entered explicitly. 

23  

24 setjy need only be run on the calibrator sources with a known flux 

25 density and/or model. 

26  

27 Models are available in CASA for 3C48, 3C138, 3C286, and 3C147 between 230 MHz 

28 and 43 GHz. In addition, P-band models for the frequency range between 230 - 

29 470 MHz are available in CASA for 3C123, 3C196, 3C295, and 3C380. 

30 These models are scaled to the precise frequency of the data. Only I models are 

31 presently available. 

32  

33 For Solar System Objects, model determination was updated and it is 

34 available via the 'Butler-JPL-Horizons 2012' standard. Currently they 

35 are modeled as uniformtemperature disks based on their ephemeris at 

36 the time of observation (note that this may oversimplify objects, in 

37 particular asteroids). Specify the name of the object in the 'field' 

38 parameter. 

39  

40 The location of the models is system dependent: At the AOC, the 

41 models are in the directory::/usr/lib/casapy/data/nrao/VLA/CalModels/ 

42 3C286_L.im (egs). 

43 

44 --------- parameter descriptions --------------------------------------------- 

45 

46 vis Name of input visibility file 

47 Default: none 

48  

49 Example: vis='ngc5921.ms' 

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

51 Default: '' (all fields, but run setjy one field 

52 at a time) 

53  

54 Use 'go listobs' to obtain the list id's or 

55 names. If field string is a non-negative integer, 

56 it is assumed a field index, otherwise, it is 

57 assumed a field name. 

58  

59 Examples: 

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

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

62 field='3C286,3C295'; field named 3C286 and 

63 3C295 

64 field = '3,4C*'; field id 3, all names 

65 starting with 4C 

66 Field name(s) 

67 spw Select spectral window/channels 

68 Default: '' (all spectral windows) 

69  

70 NOTE: setjy only selects by spectral window, and 

71 ignores channel selections. Fine-grained control 

72 could be achieved using (and possibly 

73 constructing) a cube for model. 

74 selectdata Other parameters for selecting part(s) of the MS to 

75 operate on. 

76 Default: False 

77 Options: False|True 

78  

79 Currently all time-oriented and most likely only 

80 of interest when using a Solar System object as a 

81 calibrator. 

82 timerange Select data based on time range 

83 Subparameter of selectdata=True 

84 Default = '' (all) 

85  

86 Examples: 

87 timerange = 

88 'YYYY/MM/DD/hh:mm:ss~YYYY/MM/DD/hh:mm:ss' 

89 (Note: if YYYY/MM/DD is missing date defaults 

90 to first day in data set.) 

91 timerange='09:14:0~09:54:0' picks 40 min on 

92 first day  

93 timerange= '25:00:00~27:30:00' picks 1 hr to 3 

94 hr 30min on NEXT day 

95 timerange='09:44:00' pick data within one 

96 integration of time 

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

98 scan Scan number range 

99 Subparameter of selectdata=True 

100 Default: '' = all 

101  

102 Example:scan='1~5' 

103  

104 For multiple MS input, a list of scan strings can 

105 be used: 

106 scan=['0~100','10~200'] 

107 scan='0~100; scan ids 0-100 for all input MSes 

108 Check 'go listobs' to insure the scan numbers are 

109 in order. 

110 intent Select observing intent 

111 Default: '' (all 

112  

113 Example: using wildcard characters, 

114 intent="*CALIBRATE_AMPLI*" will match field(s) 

115 contains CALIBRATE_AMPLI in a list of intents 

116  

117 WARNING: If a source with a specific field id has 

118 scans that can be distinguishable with intent 

119 selection, one should set 

120 usescatch=True. Otherwise, any existing model of 

121 the source may be cleared and overwritten even if 

122 the part of the scans not selected by intent. 

123 observation Select by observation ID(s) 

124 Subparameter of selectdata=True 

125 Default: '' = all 

126  

127 Example: observation='0~2,4' 

128 scalebychan Scale the flux density on a per channel basis? 

129 Default: True 

130 Options: True|False 

131  

132 This determines whether the fluxdensity set in 

133 the model is calculated on a per channel 

134 basis. If False then it only one fluxdensity 

135 value is calculated per spw. (Either way, all 

136 channels in spw are modified.) It is effectively 

137 True if fluxdensity[0] > 0.0. 

138 standard Flux density standard, used if fluxdensity[0] less than 0.0 

139 Default: 'Perley-Butler 2017' 

140 Options: 'Baars', 'Perley 90', 'Perley-Taylor 

141 95', 'Perley-Taylor 99', 'Perley-Butler 2010', 

142 'Perley-Butler 2013', 'Perley-Butler 2017', 

143 'Scaife-Heald 2012', 'Stevens-Reynolds 2016', 

144 'Butler-JPL-Horizons 2010', 'Butler-JPL-Horizons 

145 2012', 'manual' 'fluxscale' 

146  

147 All but the last four options are for 

148 extragalactic calibrators. The two 'Butler-JPL' 

149 standards are for Solar System objects. Note that 

150 Scaife-Heald 2012 is for the low frequencies 

151 (mostly valid for the frequency range, 

152 30-300MHz).  

153  

154 Flux density calculation with Solar System 

155 objects depends on ephemerides. The setjy task 

156 looks for the data in 

157 os.getenv('CASAPATH').split()[0] + 

158 '/data/ephemerides/JPL-Horizons'. If no ephemeris 

159 for the right object at the right time is 

160 present, the calculation will fail. Ask the 

161 helpdesk to make an ephemeris. 

162  

163 For more information on individual calibrators, 

164 see CASA Docs (https://casa.nrao.edu/casadocs/) 

165 model Model image (I only) for setting the model visibilities. 

166 Subparameter of standard="Perley-Butler 2010", 

167 "Perley-Butler 2013", and "Perley-Butler 2017" 

168 Default: '' (do not use a model image) 

169  

170 The model can be a cube, and its channels do not 

171 have to exactly match those of vis. It is 

172 recommended to use model for sources that are 

173 resolved by the observation, but the 

174 Butler-JPL-Horizons standard supplies a basic 

175 model of what several Solar System objects look 

176 like. Each field must be done separately when 

177 using a model image.  

178  

179 Both the amplitude and phase are calculated. At 

180 the AOC or CV, the models are located in 

181 casa['dirs']['data'] + '/nrao/VLA/CalModels/', 

182 e.g. /usr/lib/casapy/data/nrao/VLA/CalModels/3C286_L.im 

183 lib64 

184  

185 If model does not start with '/', setjy will look 

186 for a match in '.', './CalModels', and any 

187 CalModels directories within the 

188 casa['dirs']['data'] tree (excluding certain 

189 branches). 

190  

191 Note that model should be deconvolved, i.e. a set 

192 of clean components instead of an image that has 

193 been convolved with a clean beam. 

194 listmodels List the available models for VLA calibrators or Tb 

195 models for Solar System objects 

196 Subparameter of standard="Perley-Butler 2010", 

197 "Perley-Butler 2013", and "Perley-Butler 2017"  

198 Default: False 

199 Options: False|True 

200  

201 If True, do nothing but list candidates for model 

202 (for extragalactic calibrators) that are present 

203 on the system. It looks for *.im* *.mod* in 

204 . including its sub-directories but skipping any 

205 directory name start with ".", CalModels, and 

206 CalModels directories in the casa['dirs']['data'] 

207 tree. It does not check whether they are 

208 appropriate for the MS! If 

209 standard='Butler-JPL-Horizons 2012', Tb models 

210 (frequency-dependend brightness temperature 

211 models) for Solar System objects used in the 

212 standard. For standard='Butler-JPL-Horizons 

213 2010', the recognized Solar System objects are 

214 listed. 

215 fluxdensity Specified flux density in Jy [I,Q,U,V] 

216 Subparameter of standard="manual" 

217 Default: -1 (uses [1,0,0,0] flux density for 

218 unrecognized sources, and standard flux densities 

219 for ones recognized by the default standard 

220 Perley-Butler 2010).  

221  

222 Only one flux density can be specified at a 

223 time. The phases are set to zero. 

224 setjy will try to use the standard if fluxdensity 

225 is not positive. 

226  

227 Examples:  

228 fluxdensity=-1 will use the default standard 

229 for recognized calibrators (like 3C286, 3C147 

230 and 3C48) and insert 1.0 for selected fields 

231 with unrecognized sources. 

232 field = '1'; fluxdensity=[3.2,0,0,0] will put 

233 in a flux density of I=3.2 for field='1' 

234  

235 At present (June 2000), this is the only method 

236 to insert apolarized flux density model. 

237  

238 Example: fluxdensity=[2.63,0.21,-0.33,0.02] 

239 will put in I,Q,U,V flux densities of 

240 2.63,0.21,-0.33, and 0.02, respectively, in 

241 the model column. 

242 spix Spectral index for I flux density 

243 Subparameter of standard="manual" 

244 Default: [] =>0.0 (no effect) 

245 Options: a float or a list of float values 

246  

247 S = fluxdensity * 

248 (freq/reffreq)**(spix[0]+spix[1]*log(freq/reffreq)+..) 

249  

250 Only used if fluxdensity is being used. 

251 IMPORTANT: If fluxdensity is positive, and spix 

252 is nonzero, then reffreq must be set too! 

253  

254 It is applied in the same way to all 

255 polarizations, and does not account for Faraday 

256 rotation or depolarization. 

257  

258 Example: [-0.7, -0.15] for alpha and a curvature term 

259 reffreq Reference frequency for spix 

260 Subparameter of standard="manual" 

261 Default: '1GHz' (this is only here to prevent 

262 division by 0!) 

263  

264 Given with a unit with an optional frequency 

265 frame (if the frame is not given, LSRK is 

266 assumed). There should be no space between the 

267 value and the unit (e.g. '100.0GHz' or 'TOPO 

268 100.0GHz' are correct but with '100.0 GHz' you 

269 will see a warning message that it will be 

270 defaulted to LSRK).  

271  

272 Example: '86.0GHz', 'TOPO 86.0GHz', '4.65e9Hz' 

273  

274 NOTE: If the flux density is being scaled by 

275 spectral index, then reffreq must be set to 

276 whatever reference frequency is correct for the 

277 given fluxdensity and spix. It cannot be 

278 determined from vis. On the other hand, if spix 

279 is 0, then any positive frequency can be used 

280 (and ignored). 

281 polindex Coefficients of the frequency-dependent linear 

282 polarization index (polarization fraction)  

283 Subparameter of standard="manual" 

284 Default: [] 

285  

286 Expressed as pol. index = sqrt(Q^2+U^2)/I = c0 + 

287 c1*((freq-reffreq)/reffreq) + 

288 c2*((freq-reffreq)/reffreq)^2 + .. When Q and U 

289 flux densities are given fluxdensity, c0 is 

290 determined from these flux densities and the 

291 entry for c0 in polindex is ignored. Or Q and U 

292 flux densities in fluxdensity can be set to 0.0 

293 and then polindex[0] and polangle[0] are used to 

294 determine Q and U at reffreq. 

295  

296 Example: [0.2, -0.01] (= [c0,c1]) 

297 polangle Coefficients of the frequency-dependent linear 

298 polarization angle (in radians) 

299 Subparameter of standard="manual" 

300 Default: [] 

301  

302 Expressed as pol. angle = 0.5*arctan(U/Q) = d0 + 

303 d1*((freq-reffreq)/reffreq) + 

304 d2*((freq-reffreq)/reffreq)^2 + .. When Q and U 

305 flux densities are given in fluxdensity, d0 is 

306 determined from these flux densities and the 

307 entry for d0 in polangle is ignored. Or Q and U 

308 flux densities in fluxdensity can be set to 0.0 

309 and then polindex[0] and polangle[0] are used to 

310 determine Q and U at reffreq. Here polangle 

311 parameters are assumed to represent the intrinsic 

312 polarization angle. 

313  

314 Example: [0.57, 0.2] (=[d0,d1]) 

315 rotmeas Rotation measure (in rad/m^2) 

316 Subparameter of standard="manual" 

317 Default: 0.0 

318  

319 Note on the use of polindex, polangle and rotmeas 

320 When the frequnecy-dependent polindex and 

321 polangle are used, be sure to include all the 

322 coefficients of both polindex and polangle to 

323 describe frequency depencency. Otherwise 

324 frequency-dependent Q and U flux densities are 

325 not calculated correctly. If rotmeas is given, 

326 the calculated Q and U flux densities are then 

327 corrected for the Faraday rotation. 

328 fluxdict Output dictionary from fluxscale 

329 Subparameter of standard="fluxscale" 

330  

331 Using the flexibly results, the flux density, 

332 spectral index, and reference frequency are 

333 extracted and set to fluxdensity, spix, and 

334 reffreq parameters, respectively. The field and 

335 spw selections can be used to specify subset of 

336 the fluxdict to be used to set the model. If they 

337 are left as default (field="", spw="") all fields 

338 and/or spws in the fluxdict (but those spws with 

339 fluxd=-1 will be skipped) are used. 

340 useephemdir Use directions in the ephemeris table for the solar 

341 system object? 

342 Subparameter of standard="Butler-JPL-Horizons 

343 2012", 

344 Default: False 

345 Options: False|True 

346 interpolation Method to be used to interpolate in time for the time 

347 variable sources (3C48,3C138,3C147). 

348 Subparameter of standard="Perley-Butler 2013", 

349 and "Perley-Butler 2017"  

350 Default: 'nearest' 

351 Options: 'nearest|linear|cubic|spline' 

352  

353 This parameter is ignored for other non-variable 

354 sources in the standard. 

355 usescratch Will create if necessary and use the MODEL_DATA 

356 Default: True  

357 Options: True|False 

358  

359 * If True: the model visibility will be evaluated 

360 and saved on disk in the MODEL_DATA column. 

361 This will increase your ms in size by a factor 

362 of 1.5 (w.r.t. the case where you only have 

363 the DATA and the CORRECTED_DATA column). Use 

364 True if you need to interact with the 

365 MODEL_DATA in python, say. Also, use True if 

366 you need finer than field and spw selections 

367 using scans/time (and when use with intent 

368 selection, please see WARNING section in the 

369 intent parameter description). 

370 * If False: 'virtual' model is created. The model 

371 information is saved either in the SOURCE_MODEL 

372 column in the SOURCE table (if one exists) or 

373 in the keyword of the main table in the MS, and 

374 model visibilities are evaluated on the fly 

375 when calculating calibration or plotting in 

376 plotms. 

377  

378 By running usescratch=T, it will remove the 

379 existing virtual model from previous 

380 runs. usescratch=F will not remove the existing 

381 MODEL_DATA but in subsequent process the virtual 

382 model with matching field and spw combination 

383 will be used if it exists regardless of the 

384 presence of the MODEL_DATA column. 

385  

386 NOTE: for usescratch=False, timerange, scan, and 

387 observation are ignored (i.e. time-specific 

388 virtual model is not possible.). 

389  

390 VERY IMPORTANT: The current implementation of 

391 time-dependent models (e.g. ephemerides sources) 

392 within setjy is incompatible with the use of the 

393 virtual model column. Please use ephemerides source 

394 models only with usescratch=True 

395 ismms to be used internally for MMS 

396 

397 --------- examples ----------------------------------------------------------- 

398 

399  

400 FOR MORE INFORMATION, SEE THE TASK PAGES OF SETJY IN CASA DOCS: 

401 https://casa.nrao.edu/casadocs/ 

402 

403 

404 """ 

405 

406 _info_group_ = """imaging, calibration""" 

407 _info_desc_ = """Fills the model column with the visibilities of a calibrator""" 

408 

409 def __call__( self, vis='', field='', spw='', selectdata=False, timerange='', scan='', intent='', observation='', scalebychan=True, standard='Perley-Butler 2017', model='', listmodels=False, fluxdensity=int(-1), spix=float(0.0), reffreq='1GHz', polindex=[ ], polangle=[ ], rotmeas=float(0.0), fluxdict={ }, useephemdir=False, interpolation='nearest', usescratch=True, ismms=False ): 

410 schema = {'vis': {'type': 'cStr', 'coerce': _coerce.to_str}, 'field': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spw': {'type': 'cStr', 'coerce': _coerce.to_str}, 'selectdata': {'type': 'cBool'}, 'timerange': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'scan': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'intent': {'type': 'cStr', 'coerce': _coerce.to_str}, 'observation': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cInt'}]}, 'scalebychan': {'type': 'cBool'}, 'standard': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'Perley-Taylor 95', 'Butler-JPL-Horizons 2010', 'Perley-Butler 2010', 'Stevens-Reynolds 2016', 'Perley-Taylor 99', 'Perley-Butler 2013', 'Perley 90', 'Scaife-Heald 2012', 'manual', 'Butler-JPL-Horizons 2012', 'Perley-Butler 2017', 'fluxscale', 'Baars' ]}, 'model': {'type': 'cStr', 'coerce': _coerce.to_str}, 'listmodels': {'type': 'cBool'}, 'fluxdensity': {'anyof': [{'type': 'cInt'}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'spix': {'anyof': [{'type': 'cFloat', 'coerce': _coerce.to_float}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'reffreq': {'type': 'cStr', 'coerce': _coerce.to_str}, 'polindex': {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}, 'polangle': {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}, 'rotmeas': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'fluxdict': {'type': 'cDict'}, 'useephemdir': {'type': 'cBool'}, 'interpolation': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'nearest', 'linear', 'spline', '', 'cubic' ]}, 'usescratch': {'type': 'cBool'}, 'ismms': {'type': 'cBool'}} 

411 doc = {'vis': vis, 'field': field, 'spw': spw, 'selectdata': selectdata, 'timerange': timerange, 'scan': scan, 'intent': intent, 'observation': observation, 'scalebychan': scalebychan, 'standard': standard, 'model': model, 'listmodels': listmodels, 'fluxdensity': fluxdensity, 'spix': spix, 'reffreq': reffreq, 'polindex': polindex, 'polangle': polangle, 'rotmeas': rotmeas, 'fluxdict': fluxdict, 'useephemdir': useephemdir, 'interpolation': interpolation, 'usescratch': usescratch, 'ismms': ismms} 

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

413 _logging_state_ = _start_log( 'setjy', [ 'vis=' + repr(_pc.document['vis']), 'field=' + repr(_pc.document['field']), 'spw=' + repr(_pc.document['spw']), 'selectdata=' + repr(_pc.document['selectdata']), 'timerange=' + repr(_pc.document['timerange']), 'scan=' + repr(_pc.document['scan']), 'intent=' + repr(_pc.document['intent']), 'observation=' + repr(_pc.document['observation']), 'scalebychan=' + repr(_pc.document['scalebychan']), 'standard=' + repr(_pc.document['standard']), 'model=' + repr(_pc.document['model']), 'listmodels=' + repr(_pc.document['listmodels']), 'fluxdensity=' + repr(_pc.document['fluxdensity']), 'spix=' + repr(_pc.document['spix']), 'reffreq=' + repr(_pc.document['reffreq']), 'polindex=' + repr(_pc.document['polindex']), 'polangle=' + repr(_pc.document['polangle']), 'rotmeas=' + repr(_pc.document['rotmeas']), 'fluxdict=' + repr(_pc.document['fluxdict']), 'useephemdir=' + repr(_pc.document['useephemdir']), 'interpolation=' + repr(_pc.document['interpolation']), 'usescratch=' + repr(_pc.document['usescratch']), 'ismms=' + repr(_pc.document['ismms']) ] ) 

414 task_result = None 

415 try: 

416 task_result = _setjy_t( _pc.document['vis'], _pc.document['field'], _pc.document['spw'], _pc.document['selectdata'], _pc.document['timerange'], _pc.document['scan'], _pc.document['intent'], _pc.document['observation'], _pc.document['scalebychan'], _pc.document['standard'], _pc.document['model'], _pc.document['listmodels'], _pc.document['fluxdensity'], _pc.document['spix'], _pc.document['reffreq'], _pc.document['polindex'], _pc.document['polangle'], _pc.document['rotmeas'], _pc.document['fluxdict'], _pc.document['useephemdir'], _pc.document['interpolation'], _pc.document['usescratch'], _pc.document['ismms'] ) 

417 except Exception as exc: 

418 _except_log('setjy', exc) 

419 raise 

420 finally: 

421 task_result = _end_log( _logging_state_, 'setjy', task_result ) 

422 return task_result 

423 

424setjy = _setjy( ) 

425