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

2##################### 92e5faa737b23ea6b51a6815d68ef04f ############################## 

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_sdintimaging import sdintimaging as _sdintimaging_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 _sdintimaging: 

15 """ 

16 sdintimaging ----  

17 

18 Form images from interferometric visibilities and single dish image 

19 to reconstruct a sky model by joint deconvolution. 

20  

21 

22 --------- parameter descriptions --------------------------------------------- 

23 

24 usedata Output image type: 'int' - use interferometric data only;  

25 'sd' - use single dish data only; 

26 'sdint' - use both single dish and interferic data 

27 sdimage Input single dish image 

28 This single dish Image cube must contain images per frequency channel (blanked for empty 

29 or flagged channels). 

30  

31 If the associated sdpsf parameter is set to an empty string to signal an automatic 

32 calculation of the SD PSF cube, this SD image cube must contain per-plane  

33 restoringbeams that represent the effect SDbeam per frequency. 

34 sdpsf Input single dish PSF image.  

35  

36 This single dish PSF cube must contain the effective SD beam in the center of the image, 

37 for each frequency channel, normalized to peak 1. The coordinate system should ideally  

38 be the same as the SD image cube and contain per-plane restoringbeams that represent the 

39 effect SD beam per frequency.  

40  

41 If the sdpsf is set to a blank string (sdpsf="") an approximate PSF cube will be automatically  

42 calculated internally by using per-plane restoring-beam information from the regridded sdimage 

43 to evaluate 2D Gaussians.  

44  

45 In the future, we will provide an option to auto-generate Airy disk beams derived from  

46 the specified dish diameter. 

47 sdgain A factor or gain to adjust single dish flux scale (to use in feather stage) 

48 dishdia Effective dish diameter of the SD telescope (meters) 

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

50 default: none; 

51 example: vis='ngc5921.ms' 

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

53 selectdata Enable data selection parameters. 

54 field to image or mosaic. Use field id(s) or name(s). 

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

56 default: ''= all fields 

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

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

59 field name 

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 3C295 

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

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

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

66 for the second 

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

68 spw l window/channels 

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

70 selected by the parameter mode subparameters. 

71 default: ''=all spectral windows and channels 

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

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

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

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

76 channels 3 to 45. 

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

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

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

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

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

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

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

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

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

86 timerange Range of time to select from data 

87  

88 default: '' (all); examples, 

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

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

91 day in data set 

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

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

94 30min on NEXT day 

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

96 of time 

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

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

99 used: 

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

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

102 all input MSes 

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

104 default: '' (all); example: 

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

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

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

108 used: 

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

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

111 input MSes 

112 antenna Select data based on antenna/baseline 

113  

114 default: '' (all) 

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

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

117 considered an antenna name. 

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

119 index 6. 

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

121 and 6. 

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

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

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

125 (VLA old name) 

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

127 index number 

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

129 used: 

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

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

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

133 scan Scan number range 

134  

135 default: '' (all) 

136 example: scan='1~5' 

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

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

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

140 observation Observation ID range 

141 default: '' (all) 

142 example: observation='1~5' 

143 intent Scan Intent(s) 

144  

145 default: '' (all) 

146 example: intent='TARGET_SOURCE' 

147 example: intent='TARGET_SOURCE1,TARGET_SOURCE2' 

148 example: intent='TARGET_POINTING\*' 

149 datacolumn Data column to image (data or observed, corrected) 

150 default:'corrected' 

151 ( If 'corrected' does not exist, it will use 'data' instead ) 

152 imagename Pre-name of output images 

153  

154 example : imagename='try' 

155  

156 Output images will be (a subset of) : 

157  

158 try.psf - Point spread function 

159 try.residual - Residual image 

160 try.image - Restored image 

161 try.model - Model image (contains only flux components) 

162 try.sumwt - Single pixel image containing sum-of-weights. 

163 (for natural weighting, sensitivity=1/sqrt(sumwt)) 

164 try.pb - Primary beam model (values depend on the gridder used) 

165  

166 Widefield projection algorithms (gridder=mosaic,awproject) will 

167 compute the following images too. 

168 try.weight - FT of gridded weights or the 

169 un-normalized sum of PB-square (for all pointings) 

170 Here, PB = sqrt(weight) normalized to a maximum of 1.0 

171  

172 For multi-term wideband imaging, all relevant images above will 

173 have additional .tt0,.tt1, etc suffixes to indicate Taylor terms, 

174 plus the following extra output images. 

175 try.alpha - spectral index 

176 try.alpha.error - estimate of error on spectral index 

177 try.beta - spectral curvature (if nterms \> 2) 

178  

179 Tip : Include a directory name in 'imagename' for all 

180 output images to be sent there instead of the 

181 current working directory : imagename='mydir/try' 

182  

183 Tip : Restarting an imaging run without changing 'imagename' 

184 implies continuation from the existing model image on disk. 

185 - If 'startmodel' was initially specified it needs to be set to "" 

186 for the restart run (or sdintimaging will exit with an error message). 

187 - By default, the residual image and psf will be recomputed 

188 but if no changes were made to relevant parameters between 

189 the runs, set calcres=False, calcpsf=False to resume directly from 

190 the minor cycle without the (unnecessary) first major cycle. 

191 To automatically change 'imagename' with a numerical 

192 increment, set restart=False (see sdintimaging docs for 'restart'). 

193  

194 Note : All imaging runs will by default produce restored images. 

195 For a niter=0 run, this will be redundant and can optionally 

196 be turned off via the 'restoration=T/F' parameter. 

197 imsize Number of pixels 

198 example: 

199  

200 imsize = [350,250] 

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

202  

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

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

205 To find the nearest optimal imsize to that desired by the user, please use the following tool method: 

206  

207 from casatools import synthesisutils 

208 su = synthesisutils() 

209 su.getOptimumSize(345)  

210 Output : 360 

211 cell Cell size 

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

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

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

215 phasecenter Phase center of the image (string or field id); if the phasecenter is the name known major solar system object ('MERCURY', 'VENUS', 'MARS', 'JUPITER', 'SATURN', 'URANUS', 'NEPTUNE', 'PLUTO', 'SUN', 'MOON') or is an ephemerides table then that source is tracked and the background sources get smeared. There is a special case, when phasecenter='TRACKFIELD', which will use the ephemerides or polynomial phasecenter in the FIELD table of the MS's as the source center to track. 

216 example: phasecenter=6 

217 phasecenter='J2000 19h30m00 -40d00m00' 

218 phasecenter='J2000 292.5deg -40.0deg' 

219 phasecenter='J2000 5.105rad -0.698rad' 

220 phasecenter='ICRS 13:05:27.2780 -049.28.04.458' 

221 phasecenter='myComet_ephem.tab' 

222 phasecenter='MOON' 

223 phasecenter='TRACKFIELD' 

224 stokes Stokes Planes to make 

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

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

227  

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

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

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

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

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

233 a separate MS. 

234  

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

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

237  

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

239 projection Coordinate projection 

240 Examples : SIN, NCP 

241 A list of supported (but untested) projections can be found here : 

242 http://casa.nrao.edu/active/docs/doxygen/html/classcasa_1_1Projection.html#a3d5f9ec787e4eabdce57ab5edaf7c0cd 

243 startmodel Name of starting model image 

244  

245 The contents of the supplied starting model image will be 

246 copied to the imagename.model before the run begins. 

247  

248 example : startmodel = 'singledish.im' 

249  

250 For deconvolver='mtmfs', one image per Taylor term must be provided. 

251 example : startmodel = ['try.model.tt0', 'try.model.tt1'] 

252 startmodel = ['try.model.tt0'] will use a starting model only 

253 for the zeroth order term. 

254 startmodel = ['','try.model.tt1'] will use a starting model only 

255 for the first order term. 

256  

257 This starting model can be of a different image shape and size from 

258 what is currently being imaged. If so, an image regrid is first triggered 

259 to resample the input image onto the target coordinate system. 

260  

261 A common usage is to set this parameter equal to a single dish image 

262  

263 Negative components in the model image will be included as is. 

264  

265 [ Note : If an error occurs during image resampling/regridding, 

266 please try using task imregrid to resample the starting model 

267 image onto a CASA image with the target shape and 

268 coordinate system before supplying it via startmodel ] 

269 specmode Spectral definition mode (mfs,cube,cubedata, cubesource) 

270  

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

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

273  

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

275 Parameters start, width,and nchan define the spectral 

276 coordinate system and can be specified either in terms 

277 of channel numbers, frequency or velocity in whatever 

278 spectral frame is specified in 'outframe'. 

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

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

281 spectral frame, LSRK for automatic internal software 

282 Doppler tracking so that a spectral line observed over an 

283 extended time range will line up appropriately. 

284 Therefore the output images have additional spectral frame conversion 

285 layer in LSRK on the top the base frame. 

286  

287  

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

289 other than LSRK, the viewer still displays spectral 

290 axis in LSRK by default because of the conversion frame 

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

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

293 reference option under axis label properties in the 

294 data display options window.) 

295  

296  

297  

298  

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

300 There is no internal software Doppler tracking so 

301 a spectral line observed over an extended time range 

302 may be smeared out in frequency. There is strictly 

303 no valid spectral frame with which to label the output 

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

305  

306 mode='cubesource': Spectral line imaging while 

307 tracking moving source (near field or solar system 

308 objects). The velocity of the source is accounted 

309 and the frequency reported is in the source frame. 

310 As there is not SOURCE frame defined, 

311 the frame reported will be REST (as it may not be 

312 in the rest frame emission region may be 

313 moving w.r.t the systemic velocity frame) 

314 reffreq Reference frequency of the output image coordinate system 

315  

316 Example : reffreq='1.5GHz' as a string with units. 

317  

318 By default, it is calculated as the middle of the selected frequency range. 

319  

320 For deconvolver='mtmfs' the Taylor expansion is also done about 

321 this specified reference frequency. 

322 nchan Number of channels in the output image 

323 For default (=-1), the number of channels will be automatically determined 

324 based on data selected by 'spw' with 'start' and 'width'. 

325 It is often easiest to leave nchan at the default value. 

326 example: nchan=100 

327 start First channel (e.g. start=3,start=\'1.1GHz\',start=\'15343km/s\') 

328 of output cube images specified by data channel number (integer), 

329 velocity (string with a unit), or frequency (string with a unit). 

330 Default:''; The first channel is automatically determined based on 

331 the 'spw' channel selection and 'width'. 

332 When the channel number is used along with the channel selection 

333 in 'spw' (e.g. spw='0:6~100'), 

334 'start' channel number is RELATIVE (zero-based) to the selected 

335 channels in 'spw'. So for the above example, 

336 start=1 means that the first image channel is the second selected 

337 data channel, which is channel 7. 

338 For specmode='cube', when velocity or frequency is used it is 

339 interpreted with the frame defined in outframe. [The parameters of 

340 the desired output cube can be estimated by using the 'transform' 

341 functionality of 'plotms'] 

342 examples: start='5.0km/s'; 1st channel, 5.0km/s in outframe 

343 start='22.3GHz'; 1st channel, 22.3GHz in outframe 

344 width Channel width (e.g. width=2,width=\'0.1MHz\',width=\'10km/s\') of output cube images 

345 specified by data channel number (integer), velocity (string with a unit), or 

346 or frequency (string with a unit). 

347 Default:''; data channel width 

348 The sign of width defines the direction of the channels to be incremented. 

349 For width specified in velocity or frequency with '-' in front gives image channels in 

350 decreasing velocity or frequency, respectively. 

351 For specmode='cube', when velocity or frequency is used it is interpreted with 

352 the reference frame defined in outframe. 

353 examples: width='2.0km/s'; results in channels with increasing velocity 

354 width='-2.0km/s'; results in channels with decreasing velocity 

355 width='40kHz'; results in channels with increasing frequency 

356 width=-2; results in channels averaged of 2 data channels incremented from 

357 high to low channel numbers 

358 outframe Spectral reference frame in which to interpret \'start\' and \'width\' 

359 Options: '','LSRK','LSRD','BARY','GEO','TOPO','GALACTO','LGROUP','CMB' 

360 example: outframe='bary' for Barycentric frame 

361  

362 REST -- Rest frequency 

363 LSRD -- Local Standard of Rest (J2000) 

364 -- as the dynamical definition (IAU, [9,12,7] km/s in galactic coordinates) 

365 LSRK -- LSR as a kinematical (radio) definition 

366 -- 20.0 km/s in direction ra,dec = [270,+30] deg (B1900.0) 

367 BARY -- Barycentric (J2000) 

368 GEO --- Geocentric 

369 TOPO -- Topocentric 

370 GALACTO -- Galacto centric (with rotation of 220 km/s in direction l,b = [90,0] deg. 

371 LGROUP -- Local group velocity -- 308km/s towards l,b = [105,-7] deg (F. Ghigo) 

372 CMB -- CMB velocity -- 369.5km/s towards l,b = [264.4, 48.4] deg (F. Ghigo) 

373 DEFAULT = LSRK 

374 veltype Velocity type (radio, z, ratio, beta, gamma, optical) 

375 For start and/or width specified in velocity, specifies the velocity definition 

376 Options: 'radio','optical','z','beta','gamma','optical' 

377 NOTE: the viewer always defaults to displaying the 'radio' frame, 

378 but that can be changed in the position tracking pull down. 

379  

380 The different types (with F = f/f0, the frequency ratio), are: 

381  

382 Z = (-1 + 1/F) 

383 RATIO = (F) \* 

384 RADIO = (1 - F) 

385 OPTICAL == Z 

386 BETA = ((1 - F2)/(1 + F2)) 

387 GAMMA = ((1 + F2)/2F) \* 

388 RELATIVISTIC == BETA (== v/c) 

389 DEFAULT == RADIO 

390 Note that the ones with an '\*' have no real interpretation 

391 (although the calculation will proceed) if given as a velocity. 

392 restfreq List of rest frequencies or a rest frequency in a string. 

393 Specify rest frequency to use for output image. 

394 Currently it uses the first rest frequency in the list for translation of 

395 velocities. The list will be stored in the output images. 

396 Default: []; look for the rest frequency stored in the MS, if not available, 

397 use center frequency of the selected channels 

398 examples: restfreq=['1.42GHz'] 

399 restfreq='1.42GHz' 

400 interpolation Spectral interpolation (nearest,linear,cubic) 

401  

402 Interpolation rules to use when binning data channels onto image channels 

403 and evaluating visibility values at the centers of image channels. 

404  

405 Note : 'linear' and 'cubic' interpolation requires data points on both sides of 

406 each image frequency. Errors are therefore possible at edge channels, or near 

407 flagged data channels. When image channel width is much larger than the data 

408 channel width there is nothing much to be gained using linear or cubic thus 

409 not worth the extra computation involved. 

410 perchanweightdensity When calculating weight density for Briggs 

411 style weighting in a cube, this parameter 

412 determines whether to calculate the weight 

413 density for each channel independently  

414 (the default, True) 

415 or a common weight density for all of the selected 

416 data. This parameter has no 

417 meaning for continuum (specmode='mfs') 

418 imaging but for cube imaging 

419 perchanweightdensity=True is a recommended 

420 option that provides more uniform 

421 sensitivity per channel for cubes, but with 

422 generally larger psfs than the 

423 perchanweightdensity=False (prior behavior) 

424 option. When using Briggs style weight with 

425 perchanweightdensity=True, the imaging weight 

426 density calculations use only the weights of 

427 data that contribute specifically to that 

428 channel. On the other hand, when 

429 perchanweightdensity=False, the imaging 

430 weight density calculations sum all of the 

431 weights from all of the data channels 

432 selected whose (u,v) falls in a given uv cell 

433 on the weight density grid. Since the 

434 aggregated weights, in any given uv cell, 

435 will change depending on the number of 

436 channels included when imaging, the psf 

437 calculated for a given frequency channel will 

438 also necessarily change, resulting in 

439 variability in the psf for a given frequency 

440 channel when perchanweightdensity=False. In 

441 general, perchanweightdensity=False results 

442 in smaller psfs for the same value of 

443 robustness compared to 

444 perchanweightdensity=True, but the rms noise 

445 as a function of channel varies and increases 

446 toward the edge channels; 

447 perchanweightdensity=True provides more 

448 uniform sensitivity per channel for 

449 cubes. This may make it harder to find 

450 estimates of continuum when 

451 perchanweightdensity=False. If you intend to 

452 image a large cube in many smaller subcubes 

453 and subsequently concatenate, it is advisable 

454 to use perchanweightdensity=True to avoid 

455 surprisingly varying sensitivity and psfs 

456 across the concatenated cube. 

457 gridder Gridding options (standard, wproject, widefield, mosaic, awproject) 

458  

459 The following options choose different gridding convolution 

460 functions for the process of convolutional resampling of the measured 

461 visibilities onto a regular uv-grid prior to an inverse FFT. 

462 Model prediction (degridding) also uses these same functions. 

463 Several wide-field effects can be accounted for via careful choices of 

464 convolution functions. Gridding (degridding) runtime will rise in 

465 proportion to the support size of these convolution functions (in uv-pixels). 

466  

467 standard : Prolate Spheroid with 3x3 uv pixel support size 

468  

469 [ This mode can also be invoked using 'ft' or 'gridft' ] 

470  

471 wproject : W-Projection algorithm to correct for the widefield 

472 non-coplanar baseline effect. [Cornwell et.al 2008] 

473  

474 wprojplanes is the number of distinct w-values at 

475 which to compute and use different gridding convolution 

476 functions (see help for wprojplanes). 

477 Convolution function support size can range 

478 from 5x5 to few 100 x few 100. 

479  

480 [ This mode can also be invoked using 'wprojectft' ] 

481  

482 widefield : Facetted imaging with or without W-Projection per facet. 

483  

484 A set of facets x facets subregions of the specified image 

485 are gridded separately using their respective phase centers 

486 (to minimize max W). Deconvolution is done on the joint 

487 full size image, using a PSF from the first subregion. 

488  

489 wprojplanes=1 : standard prolate spheroid gridder per facet. 

490 wprojplanes > 1 : W-Projection gridder per facet. 

491 nfacets=1, wprojplanes > 1 : Pure W-Projection and no facetting 

492 nfacets=1, wprojplanes=1 : Same as standard,ft,gridft 

493  

494 A combination of facetting and W-Projection is relevant only for 

495 very large fields of view. 

496  

497 mosaic : A-Projection with azimuthally symmetric beams without 

498 sidelobes, beam rotation or squint correction. 

499 Gridding convolution functions per visibility are computed 

500 from FTs of PB models per antenna. 

501 This gridder can be run on single fields as well as mosaics. 

502  

503 VLA : PB polynomial fit model (Napier and Rots, 1982) 

504 EVLA : PB polynomial fit model (Perley, 2015) 

505 ALMA : Airy disks for a 10.7m dish (for 12m dishes) and 

506 6.25m dish (for 7m dishes) each with 0.75m 

507 blockages (Hunter/Brogan 2011). Joint mosaic 

508 imaging supports heterogeneous arrays for ALMA. 

509  

510 Typical gridding convolution function support sizes are 

511 between 7 and 50 depending on the desired 

512 accuracy (given by the uv cell size or image field of view). 

513  

514 [ This mode can also be invoked using 'mosaicft' or 'ftmosaic' ] 

515  

516 awproject : A-Projection with azimuthally asymmetric beams and 

517 including beam rotation, squint correction, 

518 conjugate frequency beams and W-projection. 

519 [Bhatnagar et.al, 2008] 

520  

521 Gridding convolution functions are computed from 

522 aperture illumination models per antenna and optionally 

523 combined with W-Projection kernels and a prolate spheroid. 

524 This gridder can be run on single fields as well as mosaics. 

525  

526 The awproject gridder is current not supported in the sdintimaging task. 

527 This feature will be added in the near future.  

528  

529 VLA : Uses ray traced model (VLA and EVLA) including feed 

530 leg and subreflector shadows, off-axis feed location 

531 (for beam squint and other polarization effects), and 

532 a Gaussian fit for the feed beams (Ref: Brisken 2009) 

533 ALMA : Similar ray-traced model as above (but the correctness 

534 of its polarization properties remains un-verified). 

535  

536 Typical gridding convolution function support sizes are 

537 between 7 and 50 depending on the desired 

538 accuracy (given by the uv cell size or image field of view). 

539 When combined with W-Projection they can be significantly larger. 

540  

541 [ This mode can also be invoked using 'awprojectft' ] 

542  

543 imagemosaic : (untested implementation) 

544 Grid and iFT each pointing separately and combine the 

545 images as a linear mosaic (weighted by a PB model) in 

546 the image domain before a joint minor cycle. 

547  

548 VLA/ALMA PB models are same as for gridder='mosaicft' 

549  

550 ------ Notes on PB models : 

551  

552 (1) Several different sources of PB models are used in the modes 

553 listed above. This is partly for reasons of algorithmic flexibility 

554 and partly due to the current lack of a common beam model 

555 repository or consensus on what beam models are most appropriate. 

556  

557 (2) For ALMA and gridder='mosaic', ray-traced (TICRA) beams 

558 are also available via the vpmanager tool. 

559 For example, call the following before the sdintimaging run. 

560 vp.setpbimage(telescope="ALMA", 

561 compleximage='/home/casa/data/trunk/alma/responses/ALMA_0_DV__0_0_360_0_45_90_348.5_373_373_GHz_ticra2007_VP.im', 

562 antnames=['DV'+'%02d'%k for k in range(25)]) 

563 vp.saveastable('mypb.tab') 

564 Then, supply vptable='mypb.tab' to sdintimaging. 

565  

566  

567 ------ Note on PB masks : 

568  

569 In sdintimaging, A-Projection gridders (mosaic and awproject) produce a 

570 .pb image and use the 'pblimit' subparameter to decide normalization 

571 cutoffs and construct an internal T/F mask in the .pb and .image images. 

572 However, this T/F mask cannot directly be used during deconvolution 

573 (which needs a 1/0 mask). There are two options for making a pb based 

574 deconvolution mask. 

575 -- Run sdintimaging with niter=0 to produce the .pb, construct a 1/0 image 

576 with the desired threshold (using ia.open('newmask.im'); 

577 ia.calc('iif("xxx.pb">0.3,1.0,0.0)');ia.close() for example), 

578 and supply it via the 'mask' parameter in a subsequent run 

579 (with calcres=F and calcpsf=F to restart directly from the minor cycle). 

580 -- Run sdintimaging with usemask='pb' for it to automatically construct 

581 a 1/0 mask from the internal T/F mask from .pb at a fixed 0.2 threshold. 

582  

583 ----- Making PBs for gridders other than mosaic,awproject 

584  

585 After the PSF generation, a PB is constructed using the same 

586 models used in gridder='mosaic' but just evaluated in the image 

587 domain without consideration to weights. 

588 facets Number of facets on a side 

589  

590 A set of (facets x facets) subregions of the specified image 

591 are gridded separately using their respective phase centers 

592 (to minimize max W). Deconvolution is done on the joint 

593 full size image, using a PSF from the first subregion/facet. 

594 psfphasecenter For mosaic use psf centered on this 

595 optional direction. You may need to use 

596 this if for example the mosaic does not 

597 have any pointing in the center of the 

598 image. Another reason; as the psf is 

599 approximate for a mosaic, this may help 

600 to deconvolve a non central bright source 

601 well and quickly. 

602  

603 example: 

604  

605 psfphasecenter=6 #center psf on field 6 

606 psfphasecenter='J2000 19h30m00 -40d00m00' 

607 psfphasecenter='J2000 292.5deg -40.0deg' 

608 psfphasecenter='J2000 5.105rad -0.698rad' 

609 psfphasecenter='ICRS 13:05:27.2780 -049.28.04.458' 

610 wprojplanes Number of distinct w-values at which to compute and use different 

611 gridding convolution functions for W-Projection 

612  

613 An appropriate value of wprojplanes depends on the presence/absence 

614 of a bright source far from the phase center, the desired dynamic 

615 range of an image in the presence of a bright far out source, 

616 the maximum w-value in the measurements, and the desired trade off 

617 between accuracy and computing cost. 

618  

619 As a (rough) guide, VLA L-Band D-config may require a 

620 value of 128 for a source 30arcmin away from the phase 

621 center. A-config may require 1024 or more. To converge to an 

622 appropriate value, try starting with 128 and then increasing 

623 it if artifacts persist. W-term artifacts (for the VLA) typically look 

624 like arc-shaped smears in a synthesis image or a shift in source 

625 position between images made at different times. These artifacts 

626 are more pronounced the further the source is from the phase center. 

627  

628 There is no harm in simply always choosing a large value (say, 1024) 

629 but there will be a significant performance cost to doing so, especially 

630 for gridder='awproject' where it is combined with A-Projection. 

631  

632 wprojplanes=-1 is an option for gridder='widefield' or 'wproject' 

633 in which the number of planes is automatically computed. 

634 vptable vpmanager 

635  

636 vptable="" : Choose default beams for different telescopes 

637 ALMA : Airy disks 

638 EVLA : old VLA models. 

639  

640 Other primary beam models can be chosen via the vpmanager tool. 

641  

642 Step 1 : Set up the vpmanager tool and save its state in a table 

643  

644 vp.setpbpoly(telescope='EVLA', coeff=[1.0, -1.529e-3, 8.69e-7, -1.88e-10]) 

645 vp.saveastable('myvp.tab') 

646  

647 Step 2 : Supply the name of that table in sdintimaging. 

648  

649 sdintimaging(....., vptable='myvp.tab',....) 

650  

651 Please see the documentation for the vpmanager for more details on how to 

652 choose different beam models. Work is in progress to update the defaults 

653 for EVLA and ALMA. 

654  

655 Note : AWProjection currently does not use this mechanism to choose 

656 beam models. It instead uses ray-traced beams computed from 

657 parameterized aperture illumination functions, which are not 

658 available via the vpmanager. So, gridder='awproject' does not allow 

659 the user to set this parameter. 

660 mosweight When doing Brigg's style weighting (including uniform) to perform the weight density calculation for each field indepedently if True. If False the weight density is calculated from the average uv distribution of all the fields. 

661 aterm Use aperture illumination functions during gridding 

662  

663 This parameter turns on the A-term of the AW-Projection gridder. 

664 Gridding convolution functions are constructed from aperture illumination 

665 function models of each antenna. 

666 psterm Include the Prolate Spheroidal (PS) funtion as the anti-aliasing  

667 operator in the gridding convolution functions used for gridding. 

668  

669 Setting this parameter to true is necessary when aterm is set to  

670 false. It can be set to false when aterm is set to true, though  

671 with this setting effects of aliasing may be there in the image,  

672 particularly near the edges. 

673  

674 When set to true, the .pb images will contain the fourier transform 

675 of the of the PS funtion. The table below enumarates the functional 

676 effects of the psterm, aterm and wprojplanes settings. PB referes to  

677 the Primary Beam and FT() refers to the Fourier transform operation. 

678  

679 Operation aterm psterm wprojplanes Contents of the .pb image 

680 ---------------------------------------------------------------------- 

681 AW-Projection True True >1 FT(PS) x PB 

682 False PB 

683  

684 A-Projection True True 1 FT(PS) x PB 

685 False PB 

686  

687 W-Projection False True >1 FT(PS) 

688  

689 Standard False True 1 FT(PS) 

690 wbawp Use frequency dependent A-terms 

691 Scale aperture illumination functions appropriately with frequency 

692 when gridding and combining data from multiple channels. 

693 cfcache Convolution function cache directory name 

694  

695 Name of a directory in which to store gridding convolution functions. 

696 This cache is filled at the beginning of an imaging run. This step can be time 

697 consuming but the cache can be reused across multiple imaging runs that 

698 use the same image parameters (cell size, image size , spectral data 

699 selections, wprojplanes, wbawp, psterm, aterm). The effect of the wbawp,  

700 psterm and aterm settings is frozen-in in the cfcache. Using an existing cfcache 

701 made with a different setting of these parameters will not reflect the current 

702 settings. 

703  

704 In a parallel execution, the construction of the cfcache is also parallelized  

705 and the time to compute scales close to linearly with the number of compute  

706 cores used. With the re-computation of Convolution Functions (CF) due to PA  

707 rotation turned-off (the computepastep parameter), the total number of in the 

708 cfcache can be computed as [No. of wprojplanes x No. of selected spectral windows x 4] 

709  

710 By default, cfcache = imagename + '.cf' 

711 usepointing The usepointing flag informs the gridder that it should utilize the pointing table 

712 to use the correct direction in which the antenna is pointing with respect to the pointing phasecenter. 

713 computepastep Parallactic angle interval after the AIFs are recomputed (deg) 

714  

715 This parameter controls the accuracy of the aperture illumination function 

716 used with AProjection for alt-az mount dishes where the AIF rotates on the 

717 sky as the synthesis image is built up. Once the PA in the data changes by  

718 the given interval, AIFs are re-computed at the new PA. 

719  

720 A value of 360.0 deg (the default) implies no re-computation due to PA rotation. 

721 AIFs are computed for the PA value of the first valid data received and used for  

722 all of the data. 

723 rotatepastep Parallactic angle interval after which the nearest AIF is rotated (deg)  

724  

725 Instead of recomputing the AIF for every timestep's parallactic angle, 

726 the nearest existing AIF is used and rotated 

727 after the PA changed by rotatepastep value. 

728  

729 A value of 360.0 deg (the default) disables rotation of the AIF. 

730  

731 For example, computepastep=360.0 and rotatepastep=5.0 will compute 

732 the AIFs at only the starting parallactic angle and all other timesteps will 

733 use a rotated version of that AIF at the nearest 5.0 degree point. 

734 pointingoffsetsigdev Corrections for heterogenous and time-dependent pointing  

735 offsets via AWProjection are controlled by this parameter.  

736 It is a vector of 2 ints or doubles each of which is interpreted  

737 in units of arcsec. Based on the first threshold, a clustering  

738 algorithm is applied to entries from the POINTING subtable  

739 of the MS to determine how distinct antenna groups for which 

740 the pointing offset must be computed separately. The second  

741 number controls how much a pointing change across time can  

742 be ignored and after which an antenna rebinning is required.  

743  

744  

745 Note : The default value of this parameter is [], due a programmatic constraint. 

746 If run with this value, it will internally pick [600,600] and exercise the 

747 option of using large tolerances (10arcmin) on both axes. Please choose 

748 a setting explicitly for runs that need to use this parameter.  

749  

750 Note : This option is available only for gridder='awproject' and usepointing=True and 

751 and has been validated primarily with VLASS on-the-fly mosaic data 

752 where POINTING subtables have been modified after the data are recorded. 

753  

754  

755 Examples of parameter usage :  

756  

757 [100.0,100.0] : Pointing offsets of 100 arcsec or less are considered  

758 small enough to be ignored. Using large values for both 

759 indicates a homogeneous array. 

760  

761  

762 [10.0, 100.0] : Based on entries in the POINTING subtable, antennas  

763 are grouped into clusters based on a 10arcsec bin size.  

764 All antennas in a bin are given a pointing offset calculated 

765 as the average of the offsets of all antennas in the bin. 

766 On the time axis, offset changes upto 100 arcsec will be ignored. 

767  

768 [10.0,10.0] : Calculate separate pointing offsets for each antenna group 

769 (with a 10 arcsec bin size). As a function of time, recalculate  

770 the antenna binning if the POINTING table entries change by 

771 more than 10 arcsec w.r.to the previously computed binning. 

772  

773 [1.0, 1.0] : Tight tolerances will imply a fully heterogenous situation where  

774 each antenna gets its own pointing offset. Also, time-dependent  

775 offset changes greater than 1 arcsec will trigger recomputes of  

776 the phase gradients. This is the most general situation and is also  

777 the most expensive option as it constructs and uses separate  

778 phase gradients for all baselines and timesteps.  

779  

780 For VLASS 1.1 data with two kinds of pointing offsets, the recommended 

781 setting is [ 30.0, 30.0 ]. 

782  

783 For VLASS 1.2 data with only the time-dependent pointing offsets, the 

784 recommended setting is [ 300.0, 30.0 ] to turn off the antenna grouping 

785 but to retain the time dependent corrections required from one timestep 

786 to the next. 

787 pblimit PB gain level at which to cut off normalizations 

788  

789 Divisions by .pb during normalizations have a cut off at a .pb gain 

790 level given by pblimit. Outside this limit, image values are set to zero. 

791 Additionally, by default, an internal T/F mask is applied to the .pb, .image and 

792 .residual images to mask out (T) all invalid pixels outside the pblimit area. 

793  

794 Note : This internal T/F mask cannot be used as a deconvolution mask. 

795 To do so, please follow the steps listed above in the Notes for the 

796 'gridder' parameter. 

797  

798 Note : To prevent the internal T/F mask from appearing in anything other 

799 than the .pb and .image.pbcor images, 'pblimit' can be set to a 

800 negative number. The absolute value will still be used as a valid 'pblimit'. 

801 A sdintimaging restart using existing output images on disk that already 

802 have this T/F mask in the .residual and .image but only pblimit set 

803 to a negative value, will remove this mask after the next major cycle. 

804 deconvolver Name of minor cycle algorithm (hogbom,clark,multiscale,mtmfs,mem,clarkstokes,asp) 

805  

806 Each of the following algorithms operate on residual images and psfs 

807 from the gridder and produce output model and restored images. 

808 Minor cycles stop and a major cycle is triggered when cyclethreshold 

809 or cycleniter are reached. For all methods, components are picked from 

810 the entire extent of the image or (if specified) within a mask. 

811  

812 hogbom : An adapted version of Hogbom Clean [Hogbom, 1974] 

813 - Find the location of the peak residual 

814 - Add this delta function component to the model image 

815 - Subtract a scaled and shifted PSF of the same size as the image 

816 from regions of the residual image where the two overlap. 

817 - Repeat 

818  

819 clark : An adapted version of Clark Clean [Clark, 1980] 

820 - Find the location of max(I^2+Q^2+U^2+V^2) 

821 - Add delta functions to each stokes plane of the model image 

822 - Subtract a scaled and shifted PSF within a small patch size 

823 from regions of the residual image where the two overlap. 

824 - After several iterations trigger a Clark major cycle to subtract 

825 components from the visibility domain, but without de-gridding. 

826 - Repeat 

827  

828 ( Note : 'clark' maps to imagermode='' in the old clean task. 

829 'clark_exp' is another implementation that maps to 

830 imagermode='mosaic' or 'csclean' in the old clean task 

831 but the behavior is not identical. For now, please 

832 use deconvolver='hogbom' if you encounter problems. ) 

833  

834 clarkstokes : Clark Clean operating separately per Stokes plane 

835  

836 (Note : 'clarkstokes_exp' is an alternate version. See above.) 

837  

838 multiscale : MultiScale Clean [Cornwell, 2008] 

839 - Smooth the residual image to multiple scale sizes 

840 - Find the location and scale at which the peak occurs 

841 - Add this multiscale component to the model image 

842 - Subtract a scaled,smoothed,shifted PSF (within a small 

843 patch size per scale) from all residual images 

844 - Repeat from step 2 

845  

846 mtmfs : Multi-term (Multi Scale) Multi-Frequency Synthesis [Rau and Cornwell, 2011] 

847 - Smooth each Taylor residual image to multiple scale sizes 

848 - Solve a NTxNT system of equations per scale size to compute 

849 Taylor coefficients for components at all locations 

850 - Compute gradient chi-square and pick the Taylor coefficients 

851 and scale size at the location with maximum reduction in 

852 chi-square 

853 - Add multi-scale components to each Taylor-coefficient 

854 model image 

855 - Subtract scaled,smoothed,shifted PSF (within a small patch size 

856 per scale) from all smoothed Taylor residual images 

857 - Repeat from step 2 

858  

859  

860 mem : Maximum Entropy Method [Cornwell and Evans, 1985] 

861 - Iteratively solve for values at all individual pixels via the 

862 MEM method. It minimizes an objective function of 

863 chi-square plus entropy (here, a measure of difference 

864 between the current model and a flat prior model). 

865  

866 (Note : This MEM implementation is not very robust. 

867 Improvements will be made in the future.) 

868  

869 asp : ASP Clean [Bhatnagar and Cornwell, 2004] 

870 scales List of scale sizes (in pixels) for multi-scale and mtmfs algorithms. 

871 --> scales=[0,6,20] 

872 This set of scale sizes should represent the sizes 

873 (diameters in units of number of pixels) 

874 of dominant features in the image being reconstructed. 

875  

876 The smallest scale size is recommended to be 0 (point source), 

877 the second the size of the synthesized beam and the third 3-5 

878 times the synthesized beam, etc. For example, if the synthesized 

879 beam is 10" FWHM and cell=2",try scales = [0,5,15]. 

880  

881 For numerical stability, the largest scale must be 

882 smaller than the image (or mask) size and smaller than or 

883 comparable to the scale corresponding to the lowest measured 

884 spatial frequency (as a scale size much larger than what the 

885 instrument is sensitive to is unconstrained by the data making 

886 it harder to recovery from errors during the minor cycle). 

887 nterms Number of Taylor coefficients in the spectral model 

888  

889 - nterms=1 : Assume flat spectrum source 

890 - nterms=2 : Spectrum is a straight line with a slope 

891 - nterms=N : A polynomial of order N-1 

892  

893 From a Taylor expansion of the expression of a power law, the 

894 spectral index is derived as alpha = taylorcoeff_1 / taylorcoeff_0 

895  

896 Spectral curvature is similarly derived when possible. 

897  

898 The optimal number of Taylor terms depends on the available 

899 signal to noise ratio, bandwidth ratio, and spectral shape of the 

900 source as seen by the telescope (sky spectrum x PB spectrum). 

901  

902 nterms=2 is a good starting point for wideband EVLA imaging 

903 and the lower frequency bands of ALMA (when fractional bandwidth 

904 is greater than 10%) and if there is at least one bright source for 

905 which a dynamic range of greater than few 100 is desired. 

906  

907 Spectral artifacts for the VLA often look like spokes radiating out from 

908 a bright source (i.e. in the image made with standard mfs imaging). 

909 If increasing the number of terms does not eliminate these artifacts, 

910 check the data for inadequate bandpass calibration. If the source is away 

911 from the pointing center, consider including wide-field corrections too. 

912  

913 (Note : In addition to output Taylor coefficient images .tt0,.tt1,etc 

914 images of spectral index (.alpha), an estimate of error on 

915 spectral index (.alpha.error) and spectral curvature (.beta, 

916 if nterms is greater than 2) are produced. 

917 - These alpha, alpha.error and beta images contain 

918 internal T/F masks based on a threshold computed 

919 as peakresidual/10. Additional masking based on 

920 .alpha/.alpha.error may be desirable. 

921 - .alpha.error is a purely empirical estimate derived 

922 from the propagation of error during the division of 

923 two noisy numbers (alpha = xx.tt1/xx.tt0) where the 

924 'error' on tt1 and tt0 are simply the values picked from 

925 the corresponding residual images. The absolute value 

926 of the error is not always accurate and it is best to interpret 

927 the errors across the image only in a relative sense.) 

928 smallscalebias A numerical control to bias the scales when using multi-scale or mtmfs algorithms. 

929 The peak from each scale's smoothed residual is 

930 multiplied by ( 1 - smallscalebias \* scale/maxscale ) 

931 to increase or decrease the amplitude relative to other scales, 

932 before the scale with the largest peak is chosen.  

933 Smallscalebias can be varied between -1.0 and 1.0.  

934 A score of 0.0 gives all scales equal weight (default).  

935 A score larger than 0.0 will bias the solution towards smaller scales.  

936 A score smaller than 0.0 will bias the solution towards larger scales. 

937 The effect of smallscalebias is more pronounced when using multi-scale relative to mtmfs. 

938 restoration e. 

939  

940 Construct a restored image : imagename.image by convolving the model 

941 image with a clean beam and adding the residual image to the result. 

942 If a restoringbeam is specified, the residual image is also 

943 smoothed to that target resolution before adding it in. 

944  

945 If a .model does not exist, it will make an empty one and create 

946 the restored image from the residuals ( with additional smoothing if needed ). 

947 With algorithm='mtmfs', this will construct Taylor coefficient maps from 

948 the residuals and compute .alpha and .alpha.error. 

949 restoringbeam ize to use. 

950  

951 - restoringbeam='' or [''] 

952 A Gaussian fitted to the PSF main lobe (separately per image plane). 

953  

954 - restoringbeam='10.0arcsec' 

955 Use a circular Gaussian of this width for all planes 

956  

957 - restoringbeam=['8.0arcsec','10.0arcsec','45deg'] 

958 Use this elliptical Gaussian for all planes 

959  

960 - restoringbeam='common' 

961 Automatically estimate a common beam shape/size appropriate for 

962 all planes. 

963  

964 Note : For any restoring beam different from the native resolution 

965 the model image is convolved with the beam and added to 

966 residuals that have been convolved to the same target resolution. 

967 pbcor the output restored image 

968  

969 A new image with extension .image.pbcor will be created from 

970 the evaluation of .image / .pb for all pixels above the specified pblimit. 

971  

972 Note : Stand-alone PB-correction can be triggered by re-running 

973 sdintimaging with the appropriate imagename and with 

974 niter=0, calcpsf=False, calcres=False, pbcor=True, vptable='vp.tab' 

975 ( where vp.tab is the name of the vpmanager file. 

976 See the inline help for the 'vptable' parameter ) 

977  

978 Note : Multi-term PB correction that includes a correction for the 

979 spectral index of the PB has not been enabled for the 4.7 release. 

980 Please use the widebandpbcor task instead. 

981 ( Wideband PB corrections are required when the amplitude of the 

982 brightest source is known accurately enough to be sensitive 

983 to the difference in the PB gain between the upper and lower 

984 end of the band at its location. As a guideline, the artificial spectral 

985 index due to the PB is -1.4 at the 0.5 gain level and less than -0.2 

986 at the 0.9 gain level at the middle frequency ) 

987 weighting Weighting scheme (natural,uniform,briggs,superuniform,radial, briggsabs) 

988  

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

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

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

992  

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

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

995 the weightgrid will follow the sample density 

996 pattern on the uv-plane. This weighting scheme 

997 provides the maximum imaging sensitivity at the 

998 expense of a possibly fat PSF with high sidelobes. 

999 It is most appropriate for detection experiments 

1000 where sensitivity is most important. 

1001  

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

1003 original data weights divided by the total weight of 

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

1005 ' data_weight / total_wt_per_cell '. 

1006  

1007 The weightgrid is as close to flat as possible resulting 

1008 in a PSF with a narrow main lobe and suppressed 

1009 sidelobes. However, since heavily sampled areas of 

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

1011 sensitivity is not as high as with natural weighting. 

1012 It is most appropriate for imaging experiments where 

1013 a well behaved PSF can help the reconstruction. 

1014  

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

1016 'data_weight / ( A \* total_wt_per_cell + B ) ' where 

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

1018  

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

1020 robust = +2.0 maps to natural weighting. 

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

1022  

1023 Robust/Briggs weighting generates a PSF that can 

1024 vary smoothly between 'natural' and 'uniform' and 

1025 allow customized trade-offs between PSF shape and 

1026 imaging sensitivity. 

1027 weighting='briggsabs' : Experimental option. 

1028 Same as Briggs except the formula is different A= 

1029 robust\*robust and B is dependent on the 

1030 noise per visibility estimated. Giving noise='0Jy' 

1031 is a not a reasonable option. 

1032 In this mode (or formula) robust values 

1033 from -2.0 to 0.0 only make sense (2.0 and 

1034 -2.0 will get the same weighting) 

1035  

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

1037 the total_wt_per_cell is replaced by the 

1038 total_wt_within_NxN_cells around the uv cell of 

1039 interest. ( N = subparameter 'npixels' ) 

1040  

1041 This method tends to give a PSF with inner 

1042 sidelobes that are suppressed as in uniform 

1043 weighting but with far-out sidelobes closer to 

1044 natural weighting. The peak sensitivity is also 

1045 closer to natural weighting. 

1046  

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

1048  

1049 This method approximately minimizes rms sidelobes 

1050 for an east-west synthesis array. 

1051  

1052 weighting='briggsbwtaper' : A modified version of Briggs weighting for cubes where an inverse uv taper, 

1053 which is proportional to the fractional bandwidth of the entire cube, 

1054 is applied per channel. The objective is to modify cube (perchanweightdensity = True) 

1055 imaging weights to have a similar density to that of the continuum imaging weights. 

1056 This is currently an experimental weighting scheme being developed for ALMA. 

1057  

1058  

1059 For more details on weighting please see Chapter3 

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

1061 robust Robustness parameter for Briggs weighting. 

1062  

1063 robust = -2.0 maps to uniform weighting. 

1064 robust = +2.0 maps to natural weighting. 

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

1066 noise noise parameter for briggs abs mode weighting 

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

1068 (0 defaults to -/+ 3 pixels) 

1069  

1070 npixels -- uv-box used for weight calculation 

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

1072 around a point is used to calculate weight density. 

1073  

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

1075  

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

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

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

1079 7 pixels on a side. 

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

1081  

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

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

1084 down relative to lower spatial frequencies to suppress artifacts 

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

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

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

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

1089  

1090 uvtaper = [bmaj, bmin, bpa] 

1091  

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

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

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

1095 FWHM=5 kilo-lambda 

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

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

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

1099 in aperture plane 

1100 niter Maximum number of iterations 

1101  

1102 A stopping criterion based on total iteration count. 

1103 Currently the parameter type is defined as an integer therefore the integer value  

1104 larger than 2147483647 will not be set properly as it causes an overflow. 

1105  

1106 Iterations are typically defined as the selecting one flux component 

1107 and partially subtracting it out from the residual image. 

1108  

1109 niter=0 : Do only the initial major cycle (make dirty image, psf, pb, etc) 

1110  

1111 niter larger than zero : Run major and minor cycles. 

1112  

1113 Note : Global stopping criteria vs major-cycle triggers 

1114  

1115 In addition to global stopping criteria, the following rules are 

1116 used to determine when to terminate a set of minor cycle iterations 

1117 and trigger major cycles [derived from Cotton-Schwab Clean, 1984] 

1118  

1119 'cycleniter' : controls the maximum number of iterations per image 

1120 plane before triggering a major cycle. 

1121 'cyclethreshold' : Automatically computed threshold related to the 

1122 max sidelobe level of the PSF and peak residual. 

1123 Divergence, detected as an increase of 10% in peak residual from the 

1124 minimum so far (during minor cycle iterations) 

1125  

1126 The first criterion to be satisfied takes precedence. 

1127  

1128 Note : Iteration counts for cubes or multi-field images : 

1129 For images with multiple planes (or image fields) on which the 

1130 deconvolver operates in sequence, iterations are counted across 

1131 all planes (or image fields). The iteration count is compared with 

1132 'niter' only after all channels/planes/fields have completed their 

1133 minor cycles and exited either due to 'cycleniter' or 'cyclethreshold'. 

1134 Therefore, the actual number of iterations reported in the logger 

1135 can sometimes be larger than the user specified value in 'niter'. 

1136 For example, with niter=100, cycleniter=20,nchan=10,threshold=0, 

1137 a total of 200 iterations will be done in the first set of minor cycles 

1138 before the total is compared with niter=100 and it exits. 

1139  

1140 Note : Additional global stopping criteria include 

1141 - no change in peak residual across two major cycles 

1142 - a 50% or more increase in peak residual across one major cycle 

1143 gain Loop gain 

1144  

1145 Fraction of the source flux to subtract out of the residual image 

1146 for the CLEAN algorithm and its variants. 

1147  

1148 A low value (0.2 or less) is recommended when the sky brightness 

1149 distribution is not well represented by the basis functions used by 

1150 the chosen deconvolution algorithm. A higher value can be tried when 

1151 there is a good match between the true sky brightness structure and 

1152 the basis function shapes. For example, for extended emission, 

1153 multiscale clean with an appropriate set of scale sizes will tolerate 

1154 a higher loop gain than Clark clean (for example). 

1155 threshold Stopping threshold (number in units of Jy, or string) 

1156  

1157 A global stopping threshold that the peak residual (within clean mask) 

1158 across all image planes is compared to. 

1159  

1160 threshold = 0.005 : 5mJy 

1161 threshold = '5.0mJy' 

1162  

1163 Note : A 'cyclethreshold' is internally computed and used as a major cycle 

1164 trigger. It is related what fraction of the PSF can be reliably 

1165 used during minor cycle updates of the residual image. By default 

1166 the minor cycle iterations terminate once the peak residual reaches 

1167 the first sidelobe level of the brightest source. 

1168  

1169 'cyclethreshold' is computed as follows using the settings in 

1170 parameters 'cyclefactor','minpsffraction','maxpsffraction','threshold' : 

1171  

1172 psf_fraction = max_psf_sidelobe_level \* 'cyclefactor' 

1173 psf_fraction = max(psf_fraction, 'minpsffraction'); 

1174 psf_fraction = min(psf_fraction, 'maxpsffraction'); 

1175 cyclethreshold = peak_residual \* psf_fraction 

1176 cyclethreshold = max( cyclethreshold, 'threshold' ) 

1177  

1178 If nsigma is set (>0.0), the N-sigma threshold is calculated (see 

1179 the description under nsigma), then cyclethreshold is further modified as, 

1180  

1181 cyclethreshold = max( cyclethreshold, nsgima_threshold ) 

1182  

1183  

1184 'cyclethreshold' is made visible and editable only in the 

1185 interactive GUI when sdintimaging is run with interactive=True. 

1186 nsigma Multiplicative factor for rms-based threshold stopping 

1187  

1188 N-sigma threshold is calculated as nsigma \* rms value per image plane determined 

1189 from a robust statistics. For nsigma > 0.0, in a minor cycle, a maximum of the two values, 

1190 the N-sigma threshold and cyclethreshold, is used to trigger a major cycle 

1191 (see also the descreption under 'threshold'). 

1192 Set nsigma=0.0 to preserve the previous sdintimaging behavior without this feature. 

1193 The top level parameter, fastnoise is relevant for the rms noise calculation which is used  

1194 to determine the threshold. 

1195 cycleniter Maximum number of minor-cycle iterations (per plane) before triggering 

1196 a major cycle 

1197  

1198 For example, for a single plane image, if niter=100 and cycleniter=20, 

1199 there will be 5 major cycles after the initial one (assuming there is no 

1200 threshold based stopping criterion). At each major cycle boundary, if 

1201 the number of iterations left over (to reach niter) is less than cycleniter, 

1202 it is set to the difference. 

1203  

1204 Note : cycleniter applies per image plane, even if cycleniter x nplanes 

1205 gives a total number of iterations greater than 'niter'. This is to 

1206 preserve consistency across image planes within one set of minor 

1207 cycle iterations. 

1208 cyclefactor Scaling on PSF sidelobe level to compute the minor-cycle stopping threshold. 

1209  

1210 Please refer to the Note under the documentation for 'threshold' that 

1211 discussed the calculation of 'cyclethreshold' 

1212  

1213 cyclefactor=1.0 results in a cyclethreshold at the first sidelobe level of 

1214 the brightest source in the residual image before the minor cycle starts. 

1215  

1216 cyclefactor=0.5 allows the minor cycle to go deeper. 

1217 cyclefactor=2.0 triggers a major cycle sooner. 

1218 minpsffraction PSF fraction that marks the max depth of cleaning in the minor cycle 

1219  

1220 Please refer to the Note under the documentation for 'threshold' that 

1221 discussed the calculation of 'cyclethreshold' 

1222  

1223 For example, minpsffraction=0.5 will stop cleaning at half the height of 

1224 the peak residual and trigger a major cycle earlier. 

1225 maxpsffraction PSF fraction that marks the minimum depth of cleaning in the minor cycle 

1226  

1227 Please refer to the Note under the documentation for 'threshold' that 

1228 discussed the calculation of 'cyclethreshold' 

1229  

1230 For example, maxpsffraction=0.8 will ensure that at least the top 20 

1231 percent of the source will be subtracted out in the minor cycle even if 

1232 the first PSF sidelobe is at the 0.9 level (an extreme example), or if the 

1233 cyclefactor is set too high for anything to get cleaned. 

1234 interactive Modify masks and parameters at runtime 

1235  

1236 interactive=True will trigger an interactive GUI at every major cycle 

1237 boundary (after the major cycle and before the minor cycle). 

1238  

1239 Options for runtime parameter modification are : 

1240  

1241 Interactive clean mask : Draw a 1/0 mask (appears as a contour) by hand. 

1242 If a mask is supplied at the task interface or if 

1243 automasking is invoked, the current mask is 

1244 displayed in the GUI and is available for manual 

1245 editing. 

1246  

1247 Note : If a mask contour is not visible, please 

1248 check the cursor display at the bottom of 

1249 GUI to see which parts of the mask image 

1250 have ones and zeros. If the entire mask=1 

1251 no contours will be visible. 

1252  

1253  

1254 Operation buttons : -- Stop execution now (restore current model and exit) 

1255 -- Continue on until global stopping criteria are reached 

1256 without stopping for any more interaction 

1257 -- Continue with minor cycles and return for interaction 

1258 after the next major cycle. 

1259  

1260 Iteration control : -- max cycleniter : Trigger for the next major cycle 

1261  

1262 The display begins with 

1263 [ min( cycleniter, niter - itercount ) ] 

1264 and can be edited by hand. 

1265  

1266 -- iterations left : The display begins with [niter-itercount ] 

1267 and can be edited to increase or 

1268 decrease the total allowed niter. 

1269  

1270 -- threshold : Edit global stopping threshold 

1271  

1272 -- cyclethreshold : The display begins with the 

1273 automatically computed value 

1274 (see Note in help for 'threshold'), 

1275 and can be edited by hand. 

1276  

1277 All edits will be reflected in the log messages that appear 

1278 once minor cycles begin. 

1279 fullsummary Return dictionary with complete convergence history  

1280  

1281 fullsummary=True: A full version of the summary dictionary is returned. 

1282 Keys include 'iterDone','peakRes','modelFlux','cycleThresh' that record the 

1283 convergence state at the end of each set of minor cycle iterations 

1284 separately for each image plane (i.e. channel/stokes) being 

1285 deconvolved. Additional keys report the convergence state at the  

1286 start of minor cycle iterations, stopping criteria that triggered major  

1287 cycles, and a processor ID per channel, for parallel cube runs. 

1288  

1289 fullsummary=False (default): A shorten version of the summary dictionary is returned 

1290 with only 'iterDone','peakRes','modelFlux', and 'cycleThresh'. 

1291  

1292 Detailed information about the return dictionary fields may be found  

1293 at CASA Docs > Synthesis Imaging > Iteration Control > Returned Dictionary. 

1294 nmajor The nmajor parameter limits the number of minor and major cycle sets 

1295 that sdintimaging executes. It is defined as the number of major cycles after the  

1296 initial set of minor cycle iterations. The count of nmajor does  

1297 not include the initial residual calculation that occurs when calcres=True.  

1298  

1299 A setting of nmajor=-1 implies no limit (default -1).  

1300 A setting of nmajor=0 implies nothing other than the initial residual calculation 

1301 A setting of nmajor>0 imples that nmajor sets of minor and major cycles will  

1302 be done in addition to the initial residual calculation.  

1303  

1304 If the major cycle limit is reached, stopcode 9 will be returned. Other stopping 

1305 criteria (such as threshold) could cause sdintimaging to stop in fewer than this 

1306 number of major cycles. If sdintimaging reaches another stopping criteria, first 

1307 or at the same time as nmajor, then that stopcode will be returned instead. 

1308  

1309 Note however that major cycle ids in the log messages as well as in the return 

1310 dictionary do begin with 1 for the initial residual calculation, when it exists.  

1311  

1312 Example 1 : A run with 'nmajor=5' and 'calcres=True' will iterate for 

1313 5 major cycles (not counting the initial residual calculation). But, the return 

1314 dictionary will show 'nmajordone:6'. If 'calcres=False', then the return 

1315 dictionary will show 'nmajordone:5'.  

1316  

1317 Example 2 : For both the following cases, there will be a printout in the logs  

1318 "Running Major Cycle 1" and the return value will include "nmajordone: 1",  

1319 however there is a difference in the purpose of the major cycle and the  

1320 number of minor cycles executed: 

1321 Case 1; nmajor=0, calcres=True: The major cycle done is for the creation 

1322 of the residual, and no minor cycles are executed. 

1323 Case 2; nmajor=1, calcres=False: The major cycle is done as part of the 

1324 major/minor cycle loop, and 1 minor cycle will be executed. 

1325  

1326 Note : For sdintimaging, the 'nmajor' parameter is not implemented for 

1327 usedata='sdonly'. Other stopping criteria still apply as usual. 

1328 usemask Type of mask(s) to be used for deconvolution 

1329  

1330 user: (default) mask image(s) or user specified region file(s) or string CRTF expression(s) 

1331 subparameters: mask, pbmask 

1332 pb: primary beam mask 

1333 subparameter: pbmask 

1334  

1335 Example: usemask="pb", pbmask=0.2 

1336 Construct a mask at the 0.2 pb gain level. 

1337 (Currently, this option will work only with 

1338 gridders that produce .pb (i.e. mosaic and awproject) 

1339 or if an externally produced .pb image exists on disk) 

1340  

1341 auto-multithresh : auto-masking by multiple thresholds for deconvolution 

1342 subparameters : sidelobethreshold, noisethreshold, lownoisethreshold, negativethrehsold, smoothfactor, 

1343 minbeamfrac, cutthreshold, pbmask, growiterations, dogrowprune, minpercentchange, verbose 

1344 Additional top level parameter relevant to auto-multithresh: fastnoise 

1345  

1346 if pbmask is >0.0, the region outside the specified pb gain level is excluded from 

1347 image statistics in determination of the threshold. 

1348  

1349  

1350  

1351  

1352 Note: By default the intermediate mask generated by automask at each deconvolution cycle 

1353 is over-written in the next cycle but one can save them by setting 

1354 the environment variable, SAVE_ALL_AUTOMASKS="true". 

1355 (e.g. in the CASA prompt, os.environ['SAVE_ALL_AUTOMASKS']="true" ) 

1356 The saved CASA mask image name will be imagename.mask.autothresh#, where 

1357 # is the iteration cycle number. 

1358 mask Mask (a list of image name(s) or region file(s) or region string(s) 

1359  

1360  

1361 The name of a CASA image or region file or region string that specifies 

1362 a 1/0 mask to be used for deconvolution. Only locations with value 1 will 

1363 be considered for the centers of flux components in the minor cycle. 

1364 If regions specified fall completely outside of the image, sdintimaging will throw an error. 

1365  

1366 Manual mask options/examples : 

1367  

1368 mask='xxx.mask' : Use this CASA image named xxx.mask and containing 

1369 ones and zeros as the mask.  

1370 If the mask is only different in spatial coordinates from what is being made  

1371 it will be resampled to the target coordinate system before being used. 

1372 The mask has to have the same shape in velocity and Stokes planes 

1373 as the output image. Exceptions are single velocity and/or single 

1374 Stokes plane masks. They will be expanded to cover all velocity and/or 

1375 Stokes planes of the output cube. 

1376  

1377 [ Note : If an error occurs during image resampling or 

1378 if the expected mask does not appear, please try 

1379 using tasks 'imregrid' or 'makemask' to resample 

1380 the mask image onto a CASA image with the target 

1381 shape and coordinates and supply it via the 'mask' 

1382 parameter. ] 

1383  

1384  

1385 mask='xxx.crtf' : A text file with region strings and the following on the first line 

1386 ( #CRTFv0 CASA Region Text Format version 0 ) 

1387 This is the format of a file created via the viewer's region 

1388 tool when saved in CASA region file format. 

1389  

1390 mask='circle[[40pix,40pix],10pix]' : A CASA region string. 

1391  

1392 mask=['xxx.mask','xxx.crtf', 'circle[[40pix,40pix],10pix]'] : a list of masks 

1393  

1394  

1395  

1396  

1397  

1398 Note : Mask images for deconvolution must contain 1 or 0 in each pixel. 

1399 Such a mask is different from an internal T/F mask that can be 

1400 held within each CASA image. These two types of masks are not 

1401 automatically interchangeable, so please use the makemask task 

1402 to copy between them if you need to construct a 1/0 based mask 

1403 from a T/F one. 

1404  

1405 Note : Work is in progress to generate more flexible masking options and 

1406 enable more controls. 

1407 pbmask Sub-parameter for usemask: primary beam mask 

1408  

1409 Examples : pbmask=0.0 (default, no pb mask) 

1410 pbmask=0.2 (construct a mask at the 0.2 pb gain level) 

1411 sidelobethreshold Sub-parameter for "auto-multithresh": mask threshold based on sidelobe levels: sidelobethreshold \* max_sidelobe_level \* peak residual 

1412 noisethreshold Sub-parameter for "auto-multithresh": mask threshold based on the noise level: noisethreshold \* rms + location (=median) 

1413  

1414 The rms is calculated from MAD with rms = 1.4826\*MAD. 

1415 lownoisethreshold Sub-parameter for "auto-multithresh": mask threshold to grow previously masked regions via binary dilation: lownoisethreshold \* rms in residual image + location (=median) 

1416  

1417 The rms is calculated from MAD with rms = 1.4826\*MAD. 

1418 negativethreshold Sub-parameter for "auto-multithresh": mask threshold for negative features: -1.0* negativethreshold \* rms + location(=median) 

1419  

1420 The rms is calculated from MAD with rms = 1.4826\*MAD. 

1421 smoothfactor Sub-parameter for "auto-multithresh": smoothing factor in a unit of the beam 

1422 minbeamfrac Sub-parameter for "auto-multithresh": minimum beam fraction in size to prune masks smaller than mimbeamfrac \* beam 

1423 <=0.0 : No pruning 

1424 cutthreshold Sub-parameter for "auto-multithresh": threshold to cut the smoothed mask to create a final mask: cutthreshold \* peak of the smoothed mask 

1425 growiterations Sub-parameter for "auto-multithresh": Maximum number of iterations to perform using binary dilation for growing the mask 

1426 dogrowprune Experimental sub-parameter for "auto-multithresh": Do pruning on the grow mask 

1427 minpercentchange If the change in the mask size in a particular channel is less than minpercentchange, stop masking that channel in subsequent cycles. This check is only applied when noise based threshold is used and when the previous clean major cycle had a cyclethreshold value equal to the clean threshold. Values equal to -1.0 (or any value less than 0.0) will turn off this check (the default). Automask will still stop masking if the current channel mask is an empty mask and the noise threshold was used to determine the mask. 

1428 verbose he summary of automasking at the end of each automasking process 

1429 is printed in the logger. Following information per channel will be listed in the summary. 

1430  

1431 chan: channel number 

1432 masking?: F - stop updating automask for the subsequent iteration cycles 

1433 RMS: robust rms noise 

1434 peak: peak in residual image 

1435 thresh_type: type of threshold used (noise or sidelobe) 

1436 thresh_value: the value of threshold used 

1437 N_reg: number of the automask regions 

1438 N_pruned: number of the automask regions removed by pruning 

1439 N_grow: number of the grow mask regions 

1440 N_grow_pruned: number of the grow mask regions removed by pruning 

1441 N_neg_pix: number of pixels for negative mask regions 

1442  

1443 Note that for a large cube, extra logging may slow down the process. 

1444 fastnoise Only relevant when automask (user='multi-autothresh') and/or n-sigma stopping threshold (nsigma>0.0) are/is used. If it is set to True, a simpler but faster noise calucation is used.  

1445 In this case, the threshold values are determined based on classic statistics (using all 

1446 unmasked pixels for the calculations). 

1447  

1448 If it is set to False, the new noise calculation 

1449 method is used based on pre-existing mask.  

1450  

1451 Case 1: no exiting mask 

1452 Calculate image statistics using Chauvenet algorithm  

1453  

1454 Case 2: there is an existing mask 

1455 Calculate image statistics by classical method on the region 

1456 outside the mask and inside the primary beam mask. 

1457  

1458 In all cases above RMS noise is calculated from MAD. 

1459 restart images (and start from an existing model image) 

1460 or automatically increment the image name and make a new image set. 

1461  

1462 True : Re-use existing images. If imagename.model exists the subsequent 

1463 run will start from this model (i.e. predicting it using current gridder 

1464 settings and starting from the residual image). Care must be taken 

1465 when combining this option with startmodel. Currently, only one or 

1466 the other can be used. 

1467  

1468 startmodel='', imagename.model exists : 

1469 - Start from imagename.model 

1470 startmodel='xxx', imagename.model does not exist : 

1471 - Start from startmodel 

1472 startmodel='xxx', imagename.model exists : 

1473 - Exit with an error message requesting the user to pick 

1474 only one model. This situation can arise when doing one 

1475 run with startmodel='xxx' to produce an output 

1476 imagename.model that includes the content of startmodel, 

1477 and wanting to restart a second run to continue deconvolution. 

1478 Startmodel should be set to '' before continuing. 

1479  

1480 If any change in the shape or coordinate system of the image is 

1481 desired during the restart, please change the image name and 

1482 use the startmodel (and mask) parameter(s) so that the old model 

1483 (and mask) can be regridded to the new coordinate system before starting. 

1484  

1485 False : A convenience feature to increment imagename with '_1', '_2', 

1486 etc as suffixes so that all runs of sdintimaging are fresh starts (without 

1487 having to change the imagename parameter or delete images). 

1488  

1489 This mode will search the current directory for all existing 

1490 imagename extensions, pick the maximum, and adds 1. 

1491 For imagename='try' it will make try.psf, try_2.psf, try_3.psf, etc. 

1492  

1493 This also works if you specify a directory name in the path : 

1494 imagename='outdir/try'. If './outdir' does not exist, it will create it. 

1495 Then it will search for existing filenames inside that directory. 

1496  

1497 If outlier fields are specified, the incrementing happens for each 

1498 of them (since each has its own 'imagename'). The counters are 

1499 synchronized across imagefields, to make it easier to match up sets 

1500 of output images. It adds 1 to the 'max id' from all outlier names 

1501 on disk. So, if you do two runs with only the main field 

1502 (imagename='try'), and in the third run you add an outlier with 

1503 imagename='outtry', you will get the following image names 

1504 for the third run : 'try_3' and 'outtry_3' even though 

1505 'outry' and 'outtry_2' have not been used. 

1506 calcres Calculate initial residual image 

1507  

1508 This parameter controls what the first major cycle does. 

1509  

1510 calcres=False with niter greater than 0 will assume that 

1511 a .residual image already exists and that the minor cycle can 

1512 begin without recomputing it. 

1513  

1514 calcres=False with niter=0 implies that only the PSF will be made 

1515 and no data will be gridded. 

1516  

1517 calcres=True requires that calcpsf=True or that the .psf and .sumwt 

1518 images already exist on disk (for normalization purposes). 

1519  

1520 Usage example : For large runs (or a pipeline scripts) it may be 

1521 useful to first run sdintimaging with niter=0 to create 

1522 an initial .residual to look at and perhaps make 

1523 a custom mask for. Imaging can be resumed 

1524 without recomputing it. 

1525 calcpsf Calculate PSF 

1526  

1527 This parameter controls what the first major cycle does. 

1528  

1529 calcpsf=False will assume that a .psf image already exists 

1530 and that the minor cycle can begin without recomputing it. 

1531 RETURNS void 

1532 

1533 --------- examples ----------------------------------------------------------- 

1534 

1535  

1536  

1537 Please refer to the CASAdocs pages for the task sdintimaging for examples. 

1538  

1539  

1540 

1541 

1542 """ 

1543 

1544 _info_group_ = """imaging""" 

1545 _info_desc_ = """""" 

1546 

1547 def __call__( self, usedata='sdint', sdimage='', sdpsf='', sdgain=float(1.0), dishdia=float(0), vis='', selectdata=True, field='', spw='', timerange='', uvrange='', antenna='', scan='', observation='', intent='', datacolumn='corrected', imagename='', imsize=[ ], cell=[ ], phasecenter='', stokes='I', projection='SIN', startmodel='', specmode='mfs', reffreq='', nchan=int(-1), start='', width='', outframe='LSRK', veltype='radio', restfreq=[ ], interpolation='linear', perchanweightdensity=True, gridder='standard', facets=int(1), psfphasecenter='', wprojplanes=int(1), vptable='', mosweight=True, aterm=True, psterm=False, wbawp=True, cfcache='', usepointing=False, computepastep=float(360.0), rotatepastep=float(360.0), pointingoffsetsigdev=[ ], pblimit=float(0.2), deconvolver='hogbom', scales=[ ], nterms=int(2), smallscalebias=float(0.0), restoration=True, restoringbeam=[ ], pbcor=False, weighting='natural', robust=float(0.5), noise='1.0Jy', npixels=int(0), uvtaper=[ '' ], niter=int(0), gain=float(0.1), threshold=float(0.0), nsigma=float(0.0), cycleniter=int(-1), cyclefactor=float(1.0), minpsffraction=float(0.05), maxpsffraction=float(0.8), interactive=False, fullsummary=False, nmajor=int(-1), usemask='user', mask='', pbmask=float(0.0), sidelobethreshold=float(3.0), noisethreshold=float(5.0), lownoisethreshold=float(1.5), negativethreshold=float(0.0), smoothfactor=float(1.0), minbeamfrac=float(0.3), cutthreshold=float(0.01), growiterations=int(75), dogrowprune=True, minpercentchange=float(-1.0), verbose=False, fastnoise=True, restart=True, calcres=True, calcpsf=True ): 

1548 schema = {'usedata': {'type': 'cStr', 'coerce': _coerce.to_str}, 'sdimage': {'type': 'cStr', 'coerce': _coerce.to_str}, 'sdpsf': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cFloat', 'coerce': _coerce.to_float}]}, 'sdgain': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'dishdia': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'vis': {'anyof': [{'type': 'cReqPath', 'coerce': _coerce.expand_path}, {'type': 'cReqPathVec', 'coerce': [_coerce.to_list,_coerce.expand_pathvec]}]}, 'selectdata': {'type': 'cBool'}, '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]}]}, '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'}]}, 'intent': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'datacolumn': {'type': 'cStr', 'coerce': _coerce.to_str}, 'imagename': {'anyof': [{'type': 'cInt'}, {'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, '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]}]}, 'phasecenter': {'anyof': [{'type': 'cInt'}, {'type': 'cStr', 'coerce': _coerce.to_str}]}, 'stokes': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'I', 'IQUV', 'UV', 'RRLL', 'IQ', 'V', 'pseudoI', 'QU', 'YY', 'RR', 'Q', 'U', 'IV', 'XX', 'XXYY', 'LL' ]}, 'projection': {'type': 'cStr', 'coerce': _coerce.to_str}, 'startmodel': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'specmode': {'type': 'cVariant', 'coerce': [_coerce.to_variant] # <allowed> IS NOT ALLOWED FOR A PARAMETER OF TYPE any 

1549}, 'reffreq': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'nchan': {'type': 'cInt'}, 'start': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'width': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'outframe': {'type': 'cStr', 'coerce': _coerce.to_str}, 'veltype': {'type': 'cStr', 'coerce': _coerce.to_str}, 'restfreq': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'interpolation': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'nearest', 'linear', 'cubic' ]}, 'perchanweightdensity': {'type': 'cBool'}, 'gridder': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'widefield', 'wproject', 'imagemosaic', 'standard', 'awproject', 'wprojectft', 'mosaicft', 'ft', 'ftmosaic', 'mosaic', 'awprojectft', 'gridft' ]}, 'facets': {'type': 'cInt'}, 'psfphasecenter': {'anyof': [{'type': 'cInt'}, {'type': 'cStr', 'coerce': _coerce.to_str}]}, 'wprojplanes': {'type': 'cInt'}, 'vptable': {'type': 'cStr', 'coerce': _coerce.to_str}, 'mosweight': {'type': 'cBool'}, 'aterm': {'type': 'cBool'}, 'psterm': {'type': 'cBool'}, 'wbawp': {'type': 'cBool'}, 'cfcache': {'type': 'cStr', 'coerce': _coerce.to_str}, 'usepointing': {'type': 'cBool'}, 'computepastep': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'rotatepastep': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'pointingoffsetsigdev': {'anyof': [{'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'pblimit': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'deconvolver': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'clarkstokes_exp', 'mtmfs', 'mem', 'clarkstokes', 'hogbom', 'clark_exp', 'clark', 'asp', 'multiscale' ]}, 'scales': {'anyof': [{'type': 'cIntVec', 'coerce': [_coerce.to_list,_coerce.to_intvec]}, {'type': 'cFloatVec', 'coerce': [_coerce.to_list,_coerce.to_floatvec]}]}, 'nterms': {'type': 'cInt'}, 'smallscalebias': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'restoration': {'type': 'cBool'}, 'restoringbeam': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'pbcor': {'type': 'cBool'}, 'weighting': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'briggsabs', 'briggs', 'briggsbwtaper', 'natural', 'radial', 'superuniform', 'uniform' ]}, 'robust': {'type': 'cFloat', 'coerce': _coerce.to_float, 'min': -2.0, 'max': 2.0}, 'noise': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'npixels': {'type': 'cInt'}, 'uvtaper': {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}, 'niter': {'type': 'cInt'}, 'gain': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'threshold': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'nsigma': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'cycleniter': {'type': 'cInt'}, 'cyclefactor': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'minpsffraction': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'maxpsffraction': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'interactive': {'type': 'cBool'}, 'fullsummary': {'type': 'cBool'}, 'nmajor': {'type': 'cInt'}, 'usemask': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'user', 'pb', 'auto-multithresh' ]}, 'mask': {'anyof': [{'type': 'cStr', 'coerce': _coerce.to_str}, {'type': 'cStrVec', 'coerce': [_coerce.to_list,_coerce.to_strvec]}]}, 'pbmask': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'sidelobethreshold': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'noisethreshold': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'lownoisethreshold': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'negativethreshold': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'smoothfactor': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'minbeamfrac': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'cutthreshold': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'growiterations': {'type': 'cInt'}, 'dogrowprune': {'type': 'cBool'}, 'minpercentchange': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'verbose': {'type': 'cBool'}, 'fastnoise': {'type': 'cBool'}, 'restart': {'type': 'cBool'}, 'calcres': {'type': 'cBool'}, 'calcpsf': {'type': 'cBool'}} 

1550 doc = {'usedata': usedata, 'sdimage': sdimage, 'sdpsf': sdpsf, 'sdgain': sdgain, 'dishdia': dishdia, 'vis': vis, 'selectdata': selectdata, 'field': field, 'spw': spw, 'timerange': timerange, 'uvrange': uvrange, 'antenna': antenna, 'scan': scan, 'observation': observation, 'intent': intent, 'datacolumn': datacolumn, 'imagename': imagename, 'imsize': imsize, 'cell': cell, 'phasecenter': phasecenter, 'stokes': stokes, 'projection': projection, 'startmodel': startmodel, 'specmode': specmode, 'reffreq': reffreq, 'nchan': nchan, 'start': start, 'width': width, 'outframe': outframe, 'veltype': veltype, 'restfreq': restfreq, 'interpolation': interpolation, 'perchanweightdensity': perchanweightdensity, 'gridder': gridder, 'facets': facets, 'psfphasecenter': psfphasecenter, 'wprojplanes': wprojplanes, 'vptable': vptable, 'mosweight': mosweight, 'aterm': aterm, 'psterm': psterm, 'wbawp': wbawp, 'cfcache': cfcache, 'usepointing': usepointing, 'computepastep': computepastep, 'rotatepastep': rotatepastep, 'pointingoffsetsigdev': pointingoffsetsigdev, 'pblimit': pblimit, 'deconvolver': deconvolver, 'scales': scales, 'nterms': nterms, 'smallscalebias': smallscalebias, 'restoration': restoration, 'restoringbeam': restoringbeam, 'pbcor': pbcor, 'weighting': weighting, 'robust': robust, 'noise': noise, 'npixels': npixels, 'uvtaper': uvtaper, 'niter': niter, 'gain': gain, 'threshold': threshold, 'nsigma': nsigma, 'cycleniter': cycleniter, 'cyclefactor': cyclefactor, 'minpsffraction': minpsffraction, 'maxpsffraction': maxpsffraction, 'interactive': interactive, 'fullsummary': fullsummary, 'nmajor': nmajor, 'usemask': usemask, 'mask': mask, 'pbmask': pbmask, 'sidelobethreshold': sidelobethreshold, 'noisethreshold': noisethreshold, 'lownoisethreshold': lownoisethreshold, 'negativethreshold': negativethreshold, 'smoothfactor': smoothfactor, 'minbeamfrac': minbeamfrac, 'cutthreshold': cutthreshold, 'growiterations': growiterations, 'dogrowprune': dogrowprune, 'minpercentchange': minpercentchange, 'verbose': verbose, 'fastnoise': fastnoise, 'restart': restart, 'calcres': calcres, 'calcpsf': calcpsf} 

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

1552 _logging_state_ = _start_log( 'sdintimaging', [ 'usedata=' + repr(_pc.document['usedata']), 'sdimage=' + repr(_pc.document['sdimage']), 'sdpsf=' + repr(_pc.document['sdpsf']), 'sdgain=' + repr(_pc.document['sdgain']), 'dishdia=' + repr(_pc.document['dishdia']), 'vis=' + repr(_pc.document['vis']), 'selectdata=' + repr(_pc.document['selectdata']), 'field=' + repr(_pc.document['field']), 'spw=' + repr(_pc.document['spw']), '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']), 'intent=' + repr(_pc.document['intent']), 'datacolumn=' + repr(_pc.document['datacolumn']), 'imagename=' + repr(_pc.document['imagename']), 'imsize=' + repr(_pc.document['imsize']), 'cell=' + repr(_pc.document['cell']), 'phasecenter=' + repr(_pc.document['phasecenter']), 'stokes=' + repr(_pc.document['stokes']), 'projection=' + repr(_pc.document['projection']), 'startmodel=' + repr(_pc.document['startmodel']), 'specmode=' + repr(_pc.document['specmode']), 'reffreq=' + repr(_pc.document['reffreq']), 'nchan=' + repr(_pc.document['nchan']), 'start=' + repr(_pc.document['start']), 'width=' + repr(_pc.document['width']), 'outframe=' + repr(_pc.document['outframe']), 'veltype=' + repr(_pc.document['veltype']), 'restfreq=' + repr(_pc.document['restfreq']), 'interpolation=' + repr(_pc.document['interpolation']), 'perchanweightdensity=' + repr(_pc.document['perchanweightdensity']), 'gridder=' + repr(_pc.document['gridder']), 'facets=' + repr(_pc.document['facets']), 'psfphasecenter=' + repr(_pc.document['psfphasecenter']), 'wprojplanes=' + repr(_pc.document['wprojplanes']), 'vptable=' + repr(_pc.document['vptable']), 'mosweight=' + repr(_pc.document['mosweight']), 'aterm=' + repr(_pc.document['aterm']), 'psterm=' + repr(_pc.document['psterm']), 'wbawp=' + repr(_pc.document['wbawp']), 'cfcache=' + repr(_pc.document['cfcache']), 'usepointing=' + repr(_pc.document['usepointing']), 'computepastep=' + repr(_pc.document['computepastep']), 'rotatepastep=' + repr(_pc.document['rotatepastep']), 'pointingoffsetsigdev=' + repr(_pc.document['pointingoffsetsigdev']), 'pblimit=' + repr(_pc.document['pblimit']), 'deconvolver=' + repr(_pc.document['deconvolver']), 'scales=' + repr(_pc.document['scales']), 'nterms=' + repr(_pc.document['nterms']), 'smallscalebias=' + repr(_pc.document['smallscalebias']), 'restoration=' + repr(_pc.document['restoration']), 'restoringbeam=' + repr(_pc.document['restoringbeam']), 'pbcor=' + repr(_pc.document['pbcor']), 'weighting=' + repr(_pc.document['weighting']), 'robust=' + repr(_pc.document['robust']), 'noise=' + repr(_pc.document['noise']), 'npixels=' + repr(_pc.document['npixels']), 'uvtaper=' + repr(_pc.document['uvtaper']), 'niter=' + repr(_pc.document['niter']), 'gain=' + repr(_pc.document['gain']), 'threshold=' + repr(_pc.document['threshold']), 'nsigma=' + repr(_pc.document['nsigma']), 'cycleniter=' + repr(_pc.document['cycleniter']), 'cyclefactor=' + repr(_pc.document['cyclefactor']), 'minpsffraction=' + repr(_pc.document['minpsffraction']), 'maxpsffraction=' + repr(_pc.document['maxpsffraction']), 'interactive=' + repr(_pc.document['interactive']), 'fullsummary=' + repr(_pc.document['fullsummary']), 'nmajor=' + repr(_pc.document['nmajor']), 'usemask=' + repr(_pc.document['usemask']), 'mask=' + repr(_pc.document['mask']), 'pbmask=' + repr(_pc.document['pbmask']), 'sidelobethreshold=' + repr(_pc.document['sidelobethreshold']), 'noisethreshold=' + repr(_pc.document['noisethreshold']), 'lownoisethreshold=' + repr(_pc.document['lownoisethreshold']), 'negativethreshold=' + repr(_pc.document['negativethreshold']), 'smoothfactor=' + repr(_pc.document['smoothfactor']), 'minbeamfrac=' + repr(_pc.document['minbeamfrac']), 'cutthreshold=' + repr(_pc.document['cutthreshold']), 'growiterations=' + repr(_pc.document['growiterations']), 'dogrowprune=' + repr(_pc.document['dogrowprune']), 'minpercentchange=' + repr(_pc.document['minpercentchange']), 'verbose=' + repr(_pc.document['verbose']), 'fastnoise=' + repr(_pc.document['fastnoise']), 'restart=' + repr(_pc.document['restart']), 'calcres=' + repr(_pc.document['calcres']), 'calcpsf=' + repr(_pc.document['calcpsf']) ] ) 

1553 task_result = None 

1554 try: 

1555 task_result = _sdintimaging_t( _pc.document['usedata'], _pc.document['sdimage'], _pc.document['sdpsf'], _pc.document['sdgain'], _pc.document['dishdia'], _pc.document['vis'], _pc.document['selectdata'], _pc.document['field'], _pc.document['spw'], _pc.document['timerange'], _pc.document['uvrange'], _pc.document['antenna'], _pc.document['scan'], _pc.document['observation'], _pc.document['intent'], _pc.document['datacolumn'], _pc.document['imagename'], _pc.document['imsize'], _pc.document['cell'], _pc.document['phasecenter'], _pc.document['stokes'], _pc.document['projection'], _pc.document['startmodel'], _pc.document['specmode'], _pc.document['reffreq'], _pc.document['nchan'], _pc.document['start'], _pc.document['width'], _pc.document['outframe'], _pc.document['veltype'], _pc.document['restfreq'], _pc.document['interpolation'], _pc.document['perchanweightdensity'], _pc.document['gridder'], _pc.document['facets'], _pc.document['psfphasecenter'], _pc.document['wprojplanes'], _pc.document['vptable'], _pc.document['mosweight'], _pc.document['aterm'], _pc.document['psterm'], _pc.document['wbawp'], _pc.document['cfcache'], _pc.document['usepointing'], _pc.document['computepastep'], _pc.document['rotatepastep'], _pc.document['pointingoffsetsigdev'], _pc.document['pblimit'], _pc.document['deconvolver'], _pc.document['scales'], _pc.document['nterms'], _pc.document['smallscalebias'], _pc.document['restoration'], _pc.document['restoringbeam'], _pc.document['pbcor'], _pc.document['weighting'], _pc.document['robust'], _pc.document['noise'], _pc.document['npixels'], _pc.document['uvtaper'], _pc.document['niter'], _pc.document['gain'], _pc.document['threshold'], _pc.document['nsigma'], _pc.document['cycleniter'], _pc.document['cyclefactor'], _pc.document['minpsffraction'], _pc.document['maxpsffraction'], _pc.document['interactive'], _pc.document['fullsummary'], _pc.document['nmajor'], _pc.document['usemask'], _pc.document['mask'], _pc.document['pbmask'], _pc.document['sidelobethreshold'], _pc.document['noisethreshold'], _pc.document['lownoisethreshold'], _pc.document['negativethreshold'], _pc.document['smoothfactor'], _pc.document['minbeamfrac'], _pc.document['cutthreshold'], _pc.document['growiterations'], _pc.document['dogrowprune'], _pc.document['minpercentchange'], _pc.document['verbose'], _pc.document['fastnoise'], _pc.document['restart'], _pc.document['calcres'], _pc.document['calcpsf'] ) 

1556 except Exception as exc: 

1557 _except_log('sdintimaging', exc) 

1558 raise 

1559 finally: 

1560 task_result = _end_log( _logging_state_, 'sdintimaging', task_result ) 

1561 return task_result 

1562 

1563sdintimaging = _sdintimaging( ) 

1564