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

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

2##################### 9d6c5795d9dfba6821c2263a4b3cb80f ############################## 

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_apparentsens import apparentsens as _apparentsens_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 _apparentsens: 

15 """ 

16 apparentsens ---- Imaging sensitivity estimation 

17 

18 Estimates the expected imaging sensitivity as a function of the 

19 visibility weights and imaging parameters. 

20 

21 --------- parameter descriptions --------------------------------------------- 

22 

23 vis Name(s) of input visibility file(s) 

24 default: none; 

25 example: vis='ngc5921.ms' 

26 vis=['ngc5921a.ms','ngc5921b.ms']; multiple MSes 

27 field Select fields to image or mosaic. Use field id(s) or name(s). 

28 ['go listobs' to obtain the list id's or names] 

29 default: ''= all fields 

30 If field string is a non-negative integer, it is assumed to 

31 be a field index otherwise, it is assumed to be a 

32 field name 

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

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

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

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

37 For multiple MS input, a list of field strings can be used: 

38 field = ['0~2','0~4']; field ids 0-2 for the first MS and 0-4 

39 for the second 

40 field = '0~2'; field ids 0-2 for all input MSes 

41 spw Select spectral window/channels 

42 NOTE: channels de-selected here will contain all zeros if 

43 selected by the parameter mode subparameters. 

44 default: ''=all spectral windows and channels 

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

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

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

48 spw='0,10,3:3~45'; spw 0,10 all channels, spw 3, 

49 channels 3 to 45. 

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

51 For multiple MS input, a list of spw strings can be used: 

52 spw=['0','0~3']; spw ids 0 for the first MS and 0-3 for the second 

53 spw='0~3' spw ids 0-3 for all input MS 

54 spw='3:10~20;50~60' for multiple channel ranges within spw id 3 

55 spw='3:10~20;50~60,4:0~30' for different channel ranges for spw ids 3 and 4 

56 spw='0:0~10,1:20~30,2:1;2;3'; spw 0, channels 0-10, 

57 spw 1, channels 20-30, and spw 2, channels, 1,2 and 3 

58 spw='1~4;6:15~48' for channels 15 through 48 for spw ids 1,2,3,4 and 6 

59 intent Scan Intent(s) 

60  

61 default: '' (all) 

62 example: intent='TARGET_SOURCE' 

63 example: intent='TARGET_SOURCE1,TARGET_SOURCE2' 

64 example: intent='TARGET_POINTING*' 

65 selectdata Enable data selection parameters. 

66 timerange Range of time to select from data 

67  

68 default: '' (all); examples, 

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

70 Note: if YYYY/MM/DD is missing date defaults to first 

71 day in data set 

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

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

74 30min on NEXT day 

75 timerange='09:44:00' pick data within one integration 

76 of time 

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

78 For multiple MS input, a list of timerange strings can be 

79 used: 

80 timerange=['09:14:0~09:54:0','> 10:24:00'] 

81 timerange='09:14:0~09:54:0''; apply the same timerange for 

82 all input MSes 

83 uvrange Select data within uvrange (default unit is meters) 

84 default: '' (all); example: 

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

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

87 For multiple MS input, a list of uvrange strings can be 

88 used: 

89 uvrange=['0~1000klambda','100~1000klamda'] 

90 uvrange='0~1000klambda'; apply 0-1000 kilo-lambda for all 

91 input MSes 

92 antenna Select data based on antenna/baseline 

93  

94 default: '' (all) 

95 If antenna string is a non-negative integer, it is 

96 assumed to be an antenna index, otherwise, it is 

97 considered an antenna name. 

98 antenna='5\&6'; baseline between antenna index 5 and 

99 index 6. 

100 antenna='VA05\&VA06'; baseline between VLA antenna 5 

101 and 6. 

102 antenna='5\&6;7\&8'; baselines 5-6 and 7-8 

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

104 antenna='05'; all baselines with antenna number 05 

105 (VLA old name) 

106 antenna='5,6,9'; all baselines with antennas 5,6,9 

107 index number 

108 For multiple MS input, a list of antenna strings can be 

109 used: 

110 antenna=['5','5\&6']; 

111 antenna='5'; antenna index 5 for all input MSes 

112 antenna='!DV14'; use all antennas except DV14 

113 scan Scan number range 

114  

115 default: '' (all) 

116 example: scan='1~5' 

117 For multiple MS input, a list of scan strings can be used: 

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

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

120 observation Observation ID range 

121 default: '' (all) 

122 example: observation='1~5' 

123 imsize Number of pixels 

124 example : imsize = [350,250] 

125 imsize = 500 is equivalent to [500,500] 

126 To take proper advantage of internal optimized FFT routines, the 

127 number of pixels must be even and factorizable by 2,3,5,7 only. 

128 cell Cell size 

129 example: cell=['0.5arcsec,'0.5arcsec'] or 

130 cell=['1arcmin', '1arcmin'] 

131 cell = '1arcsec' is equivalent to ['1arcsec','1arcsec'] 

132 stokes Stokes Planes to make (I only, for now) 

133 default='I'; example: stokes='IQUV'; 

134 Options: 'I','Q','U','V','IV','QU','IQ','UV','IQUV','RR','LL','XX','YY','RRLL','XXYY','pseudoI' 

135  

136 Note : Due to current internal code constraints, if any correlation pair 

137 is flagged, by default, no data for that row in the MS will be used. 

138 So, in an MS with XX,YY, if only YY is flagged, neither a 

139 Stokes I image nor an XX image can be made from those data points. 

140 In such a situation, please split out only the unflagged correlation into 

141 a separate MS. 

142  

143 Note : The 'pseudoI' option is a partial solution, allowing Stokes I imaging 

144 when either of the parallel-hand correlations are unflagged. 

145  

146 The remaining constraints shall be removed (where logical) in a future release. 

147 specmode Spectral definition mode (mfs only, for now) 

148  

149 mode='mfs' : Continuum imaging with only one output image channel. 

150 (mode='cont' can also be used here) 

151  

152 mode='cube' : Spectral line imaging with one or more channels 

153 Parameters start, width,and nchan define the spectral 

154 coordinate system and can be specified either in terms 

155 of channel numbers, frequency or velocity in whatever 

156 spectral frame is specified in 'outframe'. 

157 All internal and output images are made with outframe as the 

158 base spectral frame. However imaging code internally uses the fixed 

159 spectral frame, LSRK for automatic internal software 

160 Doppler tracking so that a spectral line observed over an 

161 extended time range will line up appropriately. 

162 Therefore the output images have additional spectral frame conversion 

163 layer in LSRK on the top the base frame. 

164  

165  

166 (Note : Even if the input parameters are specified in a frame 

167 other than LSRK, the viewer still displays spectral 

168 axis in LSRK by default because of the conversion frame 

169 layer mentioned above. The viewer can be used to relabel 

170 the spectral axis in any desired frame - via the spectral 

171 reference option under axis label properties in the 

172 data display options window.) 

173  

174  

175  

176  

177 mode='cubedata' : Spectral line imaging with one or more channels 

178 There is no internal software Doppler tracking so 

179 a spectral line observed over an extended time range 

180 may be smeared out in frequency. There is strictly 

181 no valid spectral frame with which to label the output 

182 images, but they will list the frame defined in the MS. 

183 weighting Weighting scheme (natural,uniform,briggs,superuniform,radial) 

184  

185 During gridding of the dirty or residual image, each visibility value is 

186 multiplied by a weight before it is accumulated on the uv-grid. 

187 The PSF's uv-grid is generated by gridding only the weights (weightgrid). 

188  

189 weighting='natural' : Gridding weights are identical to the data weights 

190 from the MS. For visibilities with similar data weights, 

191 the weightgrid will follow the sample density 

192 pattern on the uv-plane. This weighting scheme 

193 provides the maximum imaging sensitivity at the 

194 expense of a possibly fat PSF with high sidelobes. 

195 It is most appropriate for detection experiments 

196 where sensitivity is most important. 

197  

198 weighting='uniform' : Gridding weights per visibility data point are the 

199 original data weights divided by the total weight of 

200 all data points that map to the same uv grid cell : 

201 ' data_weight / total_wt_per_cell '. 

202  

203 The weightgrid is as close to flat as possible resulting 

204 in a PSF with a narrow main lobe and suppressed 

205 sidelobes. However, since heavily sampled areas of 

206 the uv-plane get down-weighted, the imaging 

207 sensitivity is not as high as with natural weighting. 

208 It is most appropriate for imaging experiments where 

209 a well behaved PSF can help the reconstruction. 

210  

211 weighting='briggs' : Gridding weights per visibility data point are given by 

212 'data_weight / ( A / total_wt_per_cell + B ) ' where 

213 A and B vary according to the 'robust' parameter. 

214  

215 robust = -2.0 maps to A=1,B=0 or uniform weighting. 

216 robust = +2.0 maps to natural weighting. 

217 (robust=0.5 is equivalent to robust=0.0 in AIPS IMAGR.) 

218  

219 Robust/Briggs weighting generates a PSF that can 

220 vary smoothly between 'natural' and 'uniform' and 

221 allow customized trade-offs between PSF shape and 

222 imaging sensitivity. 

223  

224 weighting='superuniform' : This is similar to uniform weighting except that 

225 the total_wt_per_cell is replaced by the 

226 total_wt_within_NxN_cells around the uv cell of 

227 interest. ( N = subparameter 'npixels' ) 

228  

229 This method tends to give a PSF with inner 

230 sidelobes that are suppressed as in uniform 

231 weighting but with far-out sidelobes closer to 

232 natural weighting. The peak sensitivity is also 

233 closer to natural weighting. 

234  

235 weighting='radial' : Gridding weights are given by ' data_weight * uvdistance ' 

236  

237 This method approximately minimizes rms sidelobes 

238 for an east-west synthesis array. 

239  

240 For more details on weighting please see Chapter3 

241 of Dan Briggs' thesis (http://www.aoc.nrao.edu/dissertations/dbriggs) 

242 robust Robustness parameter for Briggs weighting. 

243  

244 robust = -2.0 maps to uniform weighting. 

245 robust = +2.0 maps to natural weighting. 

246 (robust=0.5 is equivalent to robust=0.0 in AIPS IMAGR.) 

247 npixels Number of pixels to determine uv-cell size for super-uniform weighting 

248 (0 defaults to -/+ 3 pixels) 

249  

250 npixels -- uv-box used for weight calculation 

251 a box going from -npixel/2 to +npixel/2 on each side 

252 around a point is used to calculate weight density. 

253  

254 npixels=2 goes from -1 to +1 and covers 3 pixels on a side. 

255  

256 npixels=0 implies a single pixel, which does not make sense for 

257 superuniform weighting. Therefore, if npixels=0 it will 

258 be forced to 6 (or a box of -3pixels to +3pixels) to cover 

259 7 pixels on a side. 

260 uvtaper uv-taper on outer baselines in uv-plane 

261  

262 Apply a Gaussian taper in addition to the weighting scheme specified 

263 via the 'weighting' parameter. Higher spatial frequencies are weighted 

264 down relative to lower spatial frequencies to suppress artifacts 

265 arising from poorly sampled areas of the uv-plane. It is equivalent to 

266 smoothing the PSF obtained by other weighting schemes and can be 

267 specified either as a Gaussian in uv-space (eg. units of lambda) 

268 or as a Gaussian in the image domain (eg. angular units like arcsec). 

269  

270 uvtaper = [bmaj, bmin, bpa] 

271  

272 NOTE: the on-sky FWHM in arcsec is roughly the uv taper/200 (klambda). 

273 default: uvtaper=[]; no Gaussian taper applied 

274 example: uvtaper=['5klambda'] circular taper 

275 FWHM=5 kilo-lambda 

276 uvtaper=['5klambda','3klambda','45.0deg'] 

277 uvtaper=['10arcsec'] on-sky FWHM 10 arcseconds 

278 uvtaper=['300.0'] default units are lambda 

279 in aperture plane 

280 RETURNS record 

281 

282 --------- examples ----------------------------------------------------------- 

283 

284  

285  

286 TBD. 

287  

288  

289 

290 

291 """ 

292 

293 _info_group_ = """imaging""" 

294 _info_desc_ = """Imaging sensitivity estimation""" 

295 

296 def __call__( self, vis='', field='', spw='', intent='', selectdata=True, timerange='', uvrange='', antenna='', scan='', observation='', imsize=[ int(100) ], cell=[ ], stokes='I', specmode='mfs', weighting='natural', robust=float(0.5), npixels=int(0), uvtaper=[ '' ] ): 

297 schema = {'vis': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'field': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'spw': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'intent': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'selectdata': {'type': 'cBool'}, 'timerange': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'uvrange': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'antenna': {'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]}]}, 'observation': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cInt'}]}, 'imsize': {'anyof': [{'type': 'cInt'}, {'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}]}, 'cell': {'anyof': [{'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, {'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cFloat', 'coerce': _coerce.to_float}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, {'type': 'cInt'}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'stokes': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'I', 'IQUV', 'UV', 'RRLL', 'IQ', 'V', 'pseudoI', 'QU', 'YY', 'RR', 'Q', 'U', 'IV', 'XX', 'XXYY', 'LL' ]}, 'specmode': {'type': 'cVariant', 'coerce': [_coerce.to_variant] # <allowed> IS NOT ALLOWED FOR A PARAMETER OF TYPE any 

298}, 'weighting': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'briggs', 'natural', 'radial', 'superuniform', 'uniform' ]}, 'robust': {'type': 'cFloat', 'coerce': _coerce.to_float, 'min': -2.0, 'max': 2.0}, 'npixels': {'type': 'cInt'}, 'uvtaper': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}} 

299 doc = {'vis': vis, 'field': field, 'spw': spw, 'intent': intent, 'selectdata': selectdata, 'timerange': timerange, 'uvrange': uvrange, 'antenna': antenna, 'scan': scan, 'observation': observation, 'imsize': imsize, 'cell': cell, 'stokes': stokes, 'specmode': specmode, 'weighting': weighting, 'robust': robust, 'npixels': npixels, 'uvtaper': uvtaper} 

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

301 _logging_state_ = _start_log( 'apparentsens', [ 'vis=' + repr(_pc.document['vis']), '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']), 'imsize=' + repr(_pc.document['imsize']), 'cell=' + repr(_pc.document['cell']), 'stokes=' + repr(_pc.document['stokes']), 'specmode=' + repr(_pc.document['specmode']), 'weighting=' + repr(_pc.document['weighting']), 'robust=' + repr(_pc.document['robust']), 'npixels=' + repr(_pc.document['npixels']), 'uvtaper=' + repr(_pc.document['uvtaper']) ] ) 

302 task_result = None 

303 try: 

304 task_result = _apparentsens_t( _pc.document['vis'], _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['imsize'], _pc.document['cell'], _pc.document['stokes'], _pc.document['specmode'], _pc.document['weighting'], _pc.document['robust'], _pc.document['npixels'], _pc.document['uvtaper'] ) 

305 except Exception as exc: 

306 _except_log('apparentsens', exc) 

307 raise 

308 finally: 

309 task_result = _end_log( _logging_state_, 'apparentsens', task_result ) 

310 return task_result 

311 

312apparentsens = _apparentsens( ) 

313