Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/ms.py: 78%

169 statements  

« prev     ^ index     » next       coverage.py v7.6.4, created at 2024-11-01 07:19 +0000

1##################### generated by xml-casa (v2) from ms.xml ######################## 

2##################### 419aab85376c97dfba31215cad1c384f ############################## 

3from __future__ import absolute_import 

4from .__casac__.ms import ms as _ms 

5 

6from .errors import create_error_string 

7from .typecheck import CasaValidator as _validator 

8_pc = _validator( ) 

9from .coercetype import coerce as _coerce 

10from .table import table as _wrap_table 

11from .msmetadata import msmetadata as _wrap_msmetadata 

12 

13class ms: 

14 _info_group_ = """ms""" 

15 _info_desc_ = """Operations on measurement sets""" 

16 ### self 

17 def __init__(self, *args, **kwargs): 

18 """This is the most commonly used constructor. It creates an ms tool 

19 which is attached to the specified measurement set table. 

20  

21 By default the table is opened read only to prevent you from 

22 accidently making changes to the measurement set. Set nomodify to 

23 False you you do intend to make changes. 

24  

25 Setting the lock argument to True will permanently lock the table 

26 preventing other processes from writing to the measurement set. 

27 Unless you expect this to happen, and want to prevent it, you 

28 should leave the lock argument at the default value which implies 

29 auto-locking. 

30  

31 The host argument specifies which machine the precompiled ms 

32 process should be started on. The default value starts it on the 

33 same machine as the one that casapy is running on. 

34  

35 In order to run the ms tool on a remote machine you need to 

36 satisfy all the following conditions. 

37 begin{itemize} 

38 item It must be possible to start casa on the remote machine 

39 item You must be able to log onto the remote machine without 

40 having to type a password 

41 item The CASAPATH environment variable must be defined on the 

42 remote machine. You may want to set this up in the relevant 

43 ``dot'' file eg., adding a line like 

44 texttt{source~/usr/local/aips++/aipsinit.csh} in your 

45 .cshrc file (for csh). 

46 end{itemize} 

47 One quick way to check if all three conditions are met is to type, 

48 on your local machine (rsh host 'echo $CASAPATH') where host is 

49 replaced by the name of the remote machine. If the value of the 

50 CASAPATH variable that is printed does not contain something like 

51 {aips-root~architecture~site~host} and that all the values are 

52 correct for the remote machine you can be certain that starting the 

53 ms tool, or any casa server, on the remote host will not work. 

54  

55 Each ms tool can only run one function at a time. To solve this 

56 you start two servers. The forcenewserver argument allows you to 

57 do this by overriding the default behaviour of having each ms tool 

58 share the same server. 

59  

60 This function returns an ms tool or fail if something went wrong, 

61 like an error in the measurement set name. 

62  

63  

64 """ 

65 self._swigobj = kwargs.get('swig_object',None) 

66 if self._swigobj is None: 

67 self._swigobj = _ms() 

68 

69 def open(self, thems='', nomodify=True, lock=False, check=False): 

70 """Use this function when you have detached (using the close function) 

71 the ms tool from a measurement set table and wish to reattach to another 

72 measurement set table. 

73  

74 If check=true, additional referential integrity checks on the MS 

75 are run. If any of these fail, an exception is thrown and the MS 

76 is not open (since it is not a valid MS). 

77  

78 """ 

79 return self._swigobj.open(thems, nomodify, lock, check) 

80 

81 def reset(self): 

82 """This function re-attaches the ms tool to the original MS, 

83 effectively discarding any prior operations, in particular any 

84 data selection operations using msselect function. 

85  

86 """ 

87 return self._swigobj.reset() 

88 

89 def close(self): 

90 """This function detaches the ms tool from the associated 

91 measurement set table after flushing all the cached changes. 

92 After calling this function the ms tool is not associated with 

93 any measurement set and using any function other than open or fromfits 

94 will result in an error message being sent to the logger. 

95  

96 This function can be useful to avoid synchronization problems 

97 which can occur when different processes have the same ms open. 

98  

99 """ 

100 return self._swigobj.close() 

101 

102 def done(self): 

103 """You should call close() when you are finished using the ms tool 

104 to close the measurement set table and free any associated file 

105 locks. The measurement set is not deleted. 

106  

107  

108 """ 

109 return self._swigobj.done() 

110 

111 def name(self): 

112 """This function returns the name of the measurement set table that 

113 is being manipulated. If the ms tool is not attached to any 

114 measurement set, this function will return the string ``none''. 

115  

116 """ 

117 return self._swigobj.name() 

118 

119 def iswritable(self): 

120 """This function returns True if the underlying MeasurementSet 

121 was opened for writing/update. 

122  

123 """ 

124 return self._swigobj.iswritable() 

125 

126 def nrow(self, selected=False): 

127 """This function returns the number of rows in the measurement set. 

128 If the optional argument selected is set to True, it returns the 

129 number of currently selected rows, otherwise it returns the 

130 number of rows in the original measurement set. 

131  

132 """ 

133 return self._swigobj.nrow(selected) 

134 

135 def getdata(self, items=[ ], ifraxis=False, ifraxisgap=int(0), increment=int(1), average=False): 

136 """This function reads the specified items from the currently 

137 selected measurement set and returns them in fields of a record. 

138 The main difference between this and direct access of the table, 

139 using the table tool, is that this function reads data from the 

140 selected measurement set, provides access to derived 

141 quantities like amplitude and flag_sum, and can reorder the 

142 data. 

143  

144 As with the ms.range function, the items to read are specified 

145 using a vector of strings. Allowable items include: 'amplitude', 

146 'corrected_amplitude', 'model_amplitude', 'ratio_amplitude', 

147 'residual_amplitude', 'obs_residual_amplitude', 'antenna1', 

148 'antenna2', 'axis_info', 'data', 'corrected_data', 'float_data', 

149 'model_data', 'ratio_data', 'residual_data', 

150 'obs_residual_data', 'feed1', 'feed2', 'field_id', 'flag', 

151 'flag_row', 'flag_sum', 'ha' (added to 'axis_info'), 

152 'ifr_number', 'imaginary', 'corrected_imaginary', 

153 'model_imaginary', 'ratio_imaginary', 'residual_imaginary', 

154 'obs_residual_imaginary', 'last' (added to 'axis_info'), 

155 'phase', 'corrected_phase', 'model_phase', 'ratio_phase', 

156 'residual_phase', 'obs_residual_phase', 'real', 

157 'corrected_real', 'ratio_real', 'residual_real', 

158 'obs_residual_real', 'scan_number', 'sigma', 'data_desc_id', 

159 'time', 'ut' (added to 'axis_info'), 'uvw', 'u', 'v', 'w', 

160 'uvdist', and 'weight'. Unrecognized items will result in a 

161 warning being sent to the logger. Corrected, model, and float 

162 visibilities will result in a warning if these columns do not 

163 exist. Duplicate items are silently ignored. 

164  

165 Note that 'ha', 'last', and 'ut' must be requested along with 

166 'axis_info' and ifraxis=True. This data will be found in a 

167 subrecord of the returned record's 'axis_info' with the key in 

168 uppercase. For example, for 'ut', the data is found in: 

169 rec['axis_info']['time_axis']['UT']. See more information 

170 about 'axis_info' below. 

171  

172 The record that is returned contains fields that correspond to 

173 each of the specified items. Most fields will contain an array. 

174 The array may be one, two or three dimensional depending on 

175 whether the corresponding row in the measurement set is a 

176 scalar, one-, or two-dimensional. Unless the ifraxis argument 

177 is set to True, the length of the last axis on these arrays 

178 will correspond to the number of rows in the selected 

179 measurement set. 

180  

181 If the ifraxis argument is set to True, the row axis is split 

182 into an interferometer axis and a time axis. For example, a 

183 measurement set with 90 rows, in an array with 6 telescopes (so 

184 that there are 15 interferometers), may have a data array of 

185 shape [4,32,90] if ifraxis is False, or [4,32,15,6] if ifraxis 

186 is True (assuming there are 4 correlations and 32 channels). If 

187 there are missing rows, as will happen if not all 

188 interferometers were used for all time-slots, then a default 

189 value will be inserted. 

190  

191 This splitting of the row axis may not happen for items where 

192 there is only a single value per row. For some items the 

193 returned vector will contain only as many values as there are 

194 interferometers and it is implicit that the same value should 

195 be used for all time slots. The antenna1, antenna2, feed1, 

196 feed2 and ifr_number items fall in this category. For other 

197 items, the returned vector will have as many values as there 

198 are time slots and it is implicit that the same value should be 

199 used for all interferometers. The field_id, scan_number, 

200 data_desc_id, and time items fall into this category. 

201  

202 The 'axis_info' item provides data labelling information. It 

203 returns a record with the following fields: corr_axis, 

204 freq_axis, ifr_axis, and time_axis. The latter two fields are 

205 not present if ifraxis is set to False. 

206  

207 1. The corr_axis field contains a string vector with elements like 

208 'RR' or 'XY' that indicates which polarizations were correlated 

209 together to produce the data. The length of this vector will 

210 always be the same as the length of the first axis of the data 

211 array. 

212  

213 2. The freq_axis field contains a record with two fields, chan_freq 

214 and resolution. Each of these fields contains vectors which 

215 indicate the centre frequency and spectral resolution (FWHM) 

216 of each channel. The length of these vectors will be the same 

217 as the length of the second axis in the data. 

218  

219 3. The ifr_axis field contains fields: ifr_number, ifr_name, 

220 ifr_shortname and baseline. The ifr_number is the same as 

221 returned by the 'ifr_number' item, 1000*antenna1+antenna2. 

222 The ifr_name and ifr_shortname are string vectors containing 

223 descriptions of the interferometer; ifr_name contains the names 

224 of the antenna pair separated by a hyphen, and ifr_shortname 

225 contains the ids of the antenna pair separated by a hyphen. 

226 The baseline is the Euclidian distance in meters between the two 

227 antennas. All of these vectors have a length equal to the number 

228 of interferometers in the selected measurement set, i.e., to the 

229 length of the third axis in the data when ifraxis is True. 

230  

231 4. The time_axis field contains the MJD seconds field and 

232 optionally the HA, UT, and LAST fields. To include the optional 

233 fields, you need to add 'ha', 'last' or 'ut' strings to the list 

234 of requested items. All of the fields in the time_axis record 

235 contain vectors that indicate the time at the midpoint of the 

236 observation and are in seconds. The MJD seconds field is since 

237 0 hours on the day having a modified julian day number of zero 

238 and the rest are since midnight prior to the start of the 

239 observation. 

240  

241 An optional gap size can be specified to visually separate 

242 groups of interferometers with the same antenna1 index (handy 

243 for identifying antennas in an interferometer vs time display). 

244 The default is no gap. 

245  

246 An optional increment can be specified to return data from every 

247 row matching the increment only. 

248  

249 When the average flag is set, the data will be averaged over the 

250 time axis if the ifraxis is True or the row axis i.e., different 

251 interferometers and times may be averaged together. In the 

252 latter case, some of the coordinate information, like 

253 antenna_id, will no longer make sense. When all data to be 

254 averaged is unflagged, the result is the averaged value and the 

255 corresponding flag is False. When all data is flagged, the 

256 result is set to zero and the corresponding flag is True. When 

257 data to be averaged is mixed (unflagged and flagged), only the 

258 unflagged values are averaged and the flag is set to False. 

259  

260 You need to call selectinit before calling this function. 

261 If you haven't then selectinit will be called for you with 

262 default arguments. 

263  

264 Items prefixed with corrected, model, residual or obs_residual 

265 are not available unless your measurement set has been processed 

266 either with the imager or calibrator tools. 

267  

268 """ 

269 return self._swigobj.getdata(items, ifraxis, ifraxisgap, increment, average) 

270 

271 def putdata(self, items={ }): 

272 """This function allows you to write values from casapy variables 

273 back into the measurement set table. The main difference between 

274 this and directly accessing the table using the table tool is 

275 that this function writes data to the selected measurement set. 

276  

277 Unlike the getdata function, you can only put items that 

278 correspond to actual table columns. You cannot change the data 

279 shape either so that the number of correlations, channels and 

280 rows (or interferometers/time slots) must match the values in 

281 the selected measurement set. If the values were obtained using 

282 the getdata function with ifraxis argument set to True, then 

283 any default values added to fill in missing 

284 interferometer/timeslots pairs will be ignored when writing 

285 the modified values back using this function. 

286  

287 Allowable items include: 'data', 'corrected_data', 

288 'model_data', 'flag', 'flag_row', 'sigma', and 'weight'. 

289 'float_data' is currently not implemented for putdata. 

290  

291 The measurement set has to be opened for read/write access 

292 (nomodify=False) to be able to use this function. 

293  

294 You need to call selectinit before calling this function. 

295 If you haven't then selectinit will be called for you with 

296 default arguments. 

297  

298 Items prefixed with corrected, model, residual or obs_residual 

299 are not available unless your measurement set has been processed 

300 either with the imager or calibrator tools. 

301  

302 """ 

303 return self._swigobj.putdata(items) 

304 

305 def fromfits(self, msfile='', fitsfile='', nomodify=True, lock=False, obstype=int(0), host='', forcenewserver=False, antnamescheme='old'): 

306 """This function will convert a uvfits file to a measurement set table 

307 and then open the measurement set table. The newly created 

308 measurement set table will continue to exist after the tool has 

309 been closed. 

310  

311 Setting the lock argument to True will permanently lock the table 

312 preventing other processes from writing to the measurement set. 

313 Unless you expect this to happen, and want to prevent it, you 

314 should leave the lock argument at the default value which implies 

315 auto-locking. 

316  

317 Note that the variety of fits files that fromfits is able to 

318 interpret correctly is limited mostly to files similar to those 

319 produced by classic AIPS. In particular, it understands only binary 

320 table extensions for the antenna (AN), frequency (FQ) and source 

321 (SU) information and ignores other extensions. 

322  

323 This function returns True if it successfully attaches the ms tool 

324 to a newly created Measurement Set or False if something went 

325 wrong, like an error in a file name. 

326  

327 NOTE ON WEIGHTS 

328  

329 ms.fromfits() will generate a WEIGHT_SPECTRUM column in which it 

330 will fill the absolute value of the weight associated with each 

331 visibility in the uvfits file. Negative weights will have the 

332 associated FLAGs set to True. It will compute the associated WEIGHT 

333 value for that MS row to be the sum of the absolute values of the 

334 associated WEIGHT_SPECTRUM values. 

335  

336 """ 

337 return self._swigobj.fromfits(msfile, fitsfile, nomodify, lock, obstype, host, forcenewserver, antnamescheme) 

338 

339 def fromfitsidi(self, msfile='', fitsfile='', nomodify=True, lock=False, obstype=int(0)): 

340 """This function will convert a uvfits file to a measurement set table 

341 and then open the measurement set table. The newly created 

342 measurement set table will continue to exist after the tool has 

343 been closed. 

344  

345 Setting the lock argument to True will permanently lock the table 

346 preventing other processes from writing to the measurement set. 

347 Unless you expect this to happen, and want to prevent it, you 

348 should leave the lock argument at the default value which implies 

349 auto-locking. 

350  

351 Note that the variety of fits files that fromfits is able to 

352 interpret correctly is limited mostly to files similar to those 

353 produced by classic AIPS. In particular, it understands only binary 

354 table extensions for the antenna (AN), frequency (FQ) and source 

355 (SU) information and ignores other extensions. 

356  

357 This function returns True if it successfully attachs the ms tool 

358 to a newly created Measurement Set or False if something went 

359 wrong, like an error in a file name. 

360  

361 """ 

362 return self._swigobj.fromfitsidi(msfile, fitsfile, nomodify, lock, obstype) 

363 

364 def tofits(self, fitsfile='', column='corrected', field=[ ], spw=[ ], baseline=[ ], time='', scan=[ ], uvrange=[ ], taql='', writesyscal=False, multisource=False, combinespw=False, writestation=False, padwithflags=False, overwrite=False): 

365 """This function writes a uvfits file that contains the data in the 

366 measurement set associated with this tool. The fits file is always 

367 written in floating point format and the data are always stored in 

368 the primary array of the fits file. 

369  

370 IMPORTANT NOTE: In general, some of the data averaging features of 

371 this method have never worked properly. In general, users should 

372 run mstransform to select and average data prior to running 

373 tofits(). The associated input parameters are slowly being 

374 deprecated and removed. 

375  

376 If the measurement set has been imaged or calibrated in CASA, it 

377 may contain additional data columns. You need to select ONE of 

378 these columns to be written to the fits file. The possible 

379 options are: 

380  

381 1. observed This is the raw data as collected by the telescope. All 

382 interferometric measurement sets must contain this column. 

383 A synonym for 'observed' is 'data'. 

384 2. corrected This is the calibrated data. A synonym for 'corrected' is 

385 'corrected_data'. 

386 3. model This is the visibilites that would be measured using 

387 the current model of the sky. A synonym for 'model' is 

388 'model_data'. 

389  

390 The parsing of these strings is case insensitive. If any other 

391 option is specified then the observed data will be written. 

392  

393 By default a single-source uvfits file is written, but if the 

394 measurement set contains more than one field or if you set the 

395 multisource argument to True a multi-source uvfits file will be 

396 written. Because of limitations in the uvfits format you have to 

397 ensure that the data shape is fixed for all the data you intend to 

398 write to one fits file. See the general description of this tool 

399 for how you can select data to meet this condition. 

400  

401 The combinespw argument is used to control whether data from 

402 different spectral windows will be written as different entries in 

403 the fits FQ (frequency) table or combined as different IF's 

404 within one entry in the FQ table. You should normally only set 

405 this to True if you know that the data from different spectral 

406 windows were observed simultaneously, and the data in the 

407 measurement set can be equally divided between all the spectral 

408 windows (i.e. each window should have the same width). Use of 

409 this switch is recommended for data to be processed in classic 

410 AIPS and difmap (if possible, e.g., standard dual IF observations). 

411  

412 The padwithflags argument is only relevant if combinespw is True. 

413 If true, it will fill in data that is 'missing' with flags to fit 

414 the IF structure. This is appropriate if the MS had a few 

415 frequency-dependent flags applied, and was then time-averaged by 

416 split. If the spectral windows were observed at different times, 

417 padwithflags=True will add a large number of flags, making the 

418 output file significantly longer. It does not yet support spectral 

419 windows with different widths. 

420  

421 The fits GC (gain curve) and TY (system temperature) tables can 

422 be optionally written by setting the writesyscal argument to True. 

423 This is a rather WSRT-specific operation at the moment and may not 

424 work correctly for measurement sets from other telescopes. 

425  

426 One may overwrite the specified output file if it exists by 

427 specifying overwrite=True. 

428  

429 NOTE ON WEIGHTS 

430  

431 If the MS has no WEIGHT_SPECTRUM column, or if it does, but that 

432 column does not contain any data, ms.tofits() will compute the 

433 associated weight it writes to the uvfits file by taking the 

434 associated WEIGHT column value in the MS and dividing it by the 

435 number of channels associated with the spectral window of that 

436 visibility. 

437  

438 """ 

439 return self._swigobj.tofits(fitsfile, column, field, spw, baseline, time, scan, uvrange, taql, writesyscal, multisource, combinespw, writestation, padwithflags, overwrite) 

440 

441 def listfits(self, fitsfile): 

442 """List HDU and typical data rows in a uvfits file 

443  

444 """ 

445 return self._swigobj.listfits(fitsfile) 

446 

447 def asdmref(self, abspath=''): 

448 """If the MS is imported from an ASDM with option lazy=True, the DATA 

449 or FLOAT_DATA column of the MS is virtual and directly reads the 

450 visibilities from the ASDM. A reference to the original ASDM is 

451 stored with the MS. If the ASDM needs to be moved to a different 

452 path, the reference to it in the MS needs to be updated. This can 

453 be achieved with ms.asdmref(). 

454  

455 When called with an empty string (default), the method just reports 

456 the currently set ASDM path. 

457  

458 Return value is a string containing the new path if the path was 

459 successfully set or (in the case abspath was empty) the MS indeed 

460 contains a ASDM reference, i.e. was lazily imported. 

461  

462 If the ASDM does not contain an ASDM reference, the method returns 

463 an empty string. If abspath is not empty and there was an error 

464 setting the new reference, the method throws an exception. 

465  

466 """ 

467 return self._swigobj.asdmref(abspath) 

468 

469 def concatenate(self, msfile='', freqtol=[ ], dirtol=[ ], weightscale=float(1.), handling=int(0), destmsfile='', respectname=False): 

470 """This function concatenates two measurement sets together. 

471  

472 The data is copied from the measurement set specified in the 

473 msfile arguement to the end of the measurement set attached to the 

474 ms tool. If a lot of data needs to be copied this function may 

475 take some time. You need to open the measurement set for writing 

476 in order to use this function. 

477  

478 """ 

479 return self._swigobj.concatenate(msfile, freqtol, dirtol, weightscale, handling, destmsfile, respectname) 

480 

481 def testconcatenate(self, msfile='', freqtol=[ ], dirtol=[ ], respectname=False): 

482 """This function acts like ms.concatenate() with handling==3 (do not 

483 concatenate the MAIN and POINTING tables). This is useful for 

484 generating, e.g., SPECTRAL_WINDOW and FIELD tables which contain 

485 all used SPW and FIELD ids for a set of MSs without having to 

486 actually carry out a time-consuming concatenation on disk. The MAIN 

487 table in the resulting output MS is that of the original MS, i.e. 

488 it is not touched. 

489  

490 """ 

491 return self._swigobj.testconcatenate(msfile, freqtol, dirtol, respectname) 

492 

493 def virtconcatenate(self, msfile='', auxfilename='', freqtol=[ ], dirtol=[ ], weightscale=float(1.), respectname=True): 

494 """This function virtually concatenates two measurement sets together 

495 such that they can later be turned into a multi-MS with 

496 createmultims(). 

497  

498 You need to open the measurement set for writing in order to use 

499 this function. 

500  

501 """ 

502 return self._swigobj.virtconcatenate(msfile, auxfilename, freqtol, dirtol, weightscale, respectname) 

503 

504 def createmultims(self, outputTableName, tables, subtables, nomodify=True, lock=False, copysubtables=False, omitsubtables=[ ]): 

505 """ 

506 """ 

507 return self._swigobj.createmultims(outputTableName, tables, subtables, nomodify, lock, copysubtables, omitsubtables) 

508 

509 def ismultims(self): 

510 """ 

511 """ 

512 return self._swigobj.ismultims() 

513 

514 def split(self, outputms='', field=[ ], spw=[ ], step=[ int(1) ], baseline=[ ], timebin=[ ], time='', scan=[ ], uvrange=[ ], taql='', whichcol='DATA', tileshape=[ ], subarray=[ ], combine='', correlation='', intent='', obs=''): 

515 """This function splits out part of the MS into a new MS. Time and 

516 channel averaging can be performed in the process (but not in 

517 the same call). 

518  

519 When splitting multiple spectral windows, the parameters nchan, 

520 start, and step can be vectors, so that each spectral window has 

521 its own selection on averaging and number of output channels. But 

522 the option of using only one value for each of these parameters 

523 means that it will be replicated for all the spectral windows 

524 selected. 

525  

526 """ 

527 return self._swigobj.split(outputms, field, spw, step, baseline, timebin, time, scan, uvrange, taql, whichcol, tileshape, subarray, combine, correlation, intent, obs) 

528 

529 def partition(self, outputms='', field=[ ], spw=[ ], baseline=[ ], timebin=[ ], time='', scan=[ ], uvrange=[ ], taql='', whichcol='DATA', tileshape=[ ], subarray=[ ], combine='', intent='', obs=''): 

530 """This function splits out part of the MS into a new MS. Time 

531 averaging can be performed in the process. Unlike split, the 

532 subtables and IDs (ANTENNA1, DATA_DESCRIPTION_ID, etc.) are never 

533 changed to account for the selection. 

534  

535 As a side effect of that property, partition cannot select by 

536 channel or correlation, or average channels. It CAN select by 

537 spectral window(s). 

538  

539 """ 

540 return self._swigobj.partition(outputms, field, spw, baseline, timebin, time, scan, uvrange, taql, whichcol, tileshape, subarray, combine, intent, obs) 

541 

542 def summary(self, verbose=False, listfile='', listunfl=False, cachesize=float(50), overwrite=False, wantreturn=True): 

543 """This method will print a summary of the measurement set to the 

544 system logger. The verbose argument provides some control on how 

545 much information is displayed. 

546  

547 For especially large datasets, the cachesize parameter can be 

548 increased for possibly better performance. 

549  

550 This method can also return, in the header argument, a record 

551 containing the following fields: 

552 1. nrow Number of rows in the measurement set 

553 2. name Name of the measurement set 

554  

555 DESCRIPTION OF ALGORITHM TO CALCULATE THE NUMBER OF UNFLAGGED ROWS 

556  

557 The number of unflagged rows will only be computed if listunflis 

558 True. The number of unflagged rows (the nUnflRows columns in the 

559 scans and fields portions of the listing) is calculated by summing 

560 the fractional unflagged bandwidth for each row (and hence why the 

561 number of unflagged rows, in general, is not an integer). Thus a 

562 row which has half of its total bandwidth flagged contributes 0.5 

563 rows to the unflagged row count. A row with 20 of 32 channels of 

564 homogeneous width contributes 20/32 = 0.625 rows to the unflagged 

565 row count. A row with a value of False in the FLAG_ROW column is 

566 not counted in the number of unflagged rows. 

567  

568 """ 

569 return self._swigobj.summary(verbose, listfile, listunfl, cachesize, overwrite, wantreturn) 

570 

571 def getscansummary(self): 

572 """This function will return a summary of the main table as a 

573 structure 

574  

575 """ 

576 return self._swigobj.getscansummary() 

577 

578 def getspectralwindowinfo(self): 

579 """This method will get a summary of the spectral window actually 

580 used in this ms. To be precise those reference by the data 

581 description table. 

582  

583 """ 

584 return self._swigobj.getspectralwindowinfo() 

585 

586 def getreferencedtables(self): 

587 """ 

588 """ 

589 return self._swigobj.getreferencedtables() 

590 

591 def getfielddirmeas(self, dircolname='PHASE_DIR', fieldid=int(0), time=float(0), format='measure'): 

592 """This function returns the direction measures from the given 

593 direction column of the MS FIELD table as a either a measure 

594 dictionary or sexigesimal string representation. 

595 If there is an ephemeris attached, this will give you the time dependent 

596 direction for the given direction column including the offset which each 

597 field may have to the ephemeris it is referencing. You can use the value 

598 "EPHEMERIS_DIR" for parameter "dircolname" to access the unaltered ephemeris 

599 direction without any potential mosaic offsets. 

600  

601 """ 

602 return self._swigobj.getfielddirmeas(dircolname, fieldid, time, format) 

603 

604 def listhistory(self): 

605 """This function lists the contents of the measurement set history 

606 table. 

607  

608 """ 

609 return self._swigobj.listhistory() 

610 

611 def writehistory(self, message='', parms='', origin='MSHistoryHandler::addMessage()', msname='', app='ms'): 

612 """This function adds a row to the history table of the specified 

613 measurement set containing any message that the user wishes to 

614 record. By default the history entry is written to the history 

615 table of the measurement set that is currently open, the message 

616 origin is recorded as 'MSHistoryHandler::addMessage()', the 

617 originating application is 'ms' and the input parameters field is 

618 empty. 

619  

620 """ 

621 return self._swigobj.writehistory(message, parms, origin, msname, app) 

622 

623 def writehistory_batch(self, messages=[ ], parms='', origin='MSHistoryHandler::addMessage()', msname='', app='ms'): 

624 """This function works as writehistory but adds a list of messages to 

625 the history table, instead of a single message. Each message is written 

626 into in a new row. It is recommended for efficiency, as adding rows one 

627 at a time can be rather slow, causing for example a delay of the order 

628 of 10-30 seconds when writing the history at the end of a normal flagdata 

629 command (with 70+ parameter rows). 

630  

631 """ 

632 return self._swigobj.writehistory_batch(messages, parms, origin, msname, app) 

633 

634 def statistics(self, column='', complex_value='', useflags=True, useweights=False, spw='', field='', baseline='', uvrange='', time='', correlation='', scan='', intent='', array='', obs='', reportingaxes='', timeaverage=False, timebin='0s', timespan='', maxuvwdistance=float(0.0), doquantiles=True): 

635 """This function computes descriptive statistics on the measurement 

636 set. It returns the statistical values as a python dictionary. The 

637 given column name must be a numerical column. If it is a complex 

638 valued column, the parameter complex_value defines which derived 

639 real value is used for the statistics computation. 

640  

641 """ 

642 return self._swigobj.statistics(column, complex_value, useflags, useweights, spw, field, baseline, uvrange, time, correlation, scan, intent, array, obs, reportingaxes, timeaverage, timebin, timespan, maxuvwdistance, doquantiles) 

643 

644 def statisticsold(self, column='', complex_value='', useflags=True, spw='', field='', baseline='', uvrange='', time='', correlation='', scan='', array='', obs=''): 

645 """DEPRECATED: Please use the ms::statistics() function in place of 

646 ms::statisticsold(). 

647  

648 This function computes descriptive statistics on the measurement 

649 set. It returns the statistical values as a python dictionary. The 

650 given column name must be a numerical column. If it is a complex 

651 valued column, the parameter complex_value defines which derived 

652 real value is used for the statistics computation. 

653  

654 """ 

655 return self._swigobj.statisticsold(column, complex_value, useflags, spw, field, baseline, uvrange, time, correlation, scan, array, obs) 

656 

657 def range(self, items=[ ], useflags=True, blocksize=int(10)): 

658 """This function returns the range of values in the currently 

659 selected measurement set for the items specified. 

660  

661 Possible items include 'amplitude', 'corrected_amplitude', 

662 'model_amplitude', 'antenna1', 'antenna2', 'antennas', 

663 'array_id', 'chan_freq', 'corr_names', 'corr_types', 'feed1', 

664 'feed2', 'field_id', 'fields', 'float_data', 'ifr_number' 

665 (1000*antenna1 + antenna2), 'imaginary', 'corrected_imaginary', 

666 'model_imaginary', 'num_corr', 'num_chan', 'phase', 

667 'corrected_phase', 'model_phase', 'phase_dir', 'real', 

668 'corrected_real', 'model_real', 'ref_frequency', 'rows', 

669 'scan_number', 'sigma', 'data_desc_id', 'time', 'times', 'u', 

670 'v', 'w', 'uvdist', and 'weight'. Note that corrected, model, 

671 and float versions are available only if these columns are 

672 present in the data. 

673  

674 You specify items in which you are interested using a string 

675 vector where each element is a case insensitive item name. This 

676 function will then return a record that has fields corresponding 

677 to each of the specified items. Each field will contain the 

678 range of the specified item. For many items the range will be 

679 the minimum and maximum values but for some it will be a list of 

680 unique values. Unrecognized items are ignored. 

681  

682 By default the FLAG column is used to exclude flagged data 

683 before any ranges are determined, but you can set useflags=False 

684 to include flagged data in the range. However, if you average 

685 in frequency, flagging will still be applied. 

686  

687 You can influence the memory use and the reading speed using 

688 the blocksize argument - it specifies how big a block of data 

689 to read at once (in MB). For large datasets on machines with 

690 lots of memory you may speed things up by setting this higher 

691 than the default (10 MB). 

692  

693 For some items, you need to call selectinit to select a portion 

694 of the data with a unique shape prior to calling this function. 

695  

696 Items prefixed with corrected, model, residual or obs_residual 

697 are not available unless your measurement set has been processed 

698 either with the imager or calibrator tools. 

699  

700 """ 

701 return self._swigobj.range(items, useflags, blocksize) 

702 

703 def lister(self, options='', datacolumn='data', field='', spw='', antenna='', timerange='', correlation='', scan='', feed='', array='', observation='', uvrange='', average='', showflags=False, msselect='', pagerows=int(50), listfile=''): 

704 """This tool lists measurement set visibility data under a number of 

705 input selection conditions. The measurement set data columns that 

706 can be listed are: the raw data, corrected data, model data, and 

707 residual (corrected - model) data. 

708  

709 The output table format is dynamic. Field, Spectral Window, and 

710 Channel columns are not displayed if the column contents are 

711 uniform. For example, if ``spw = `1' '' is specified, the spw 

712 column will not be displayed. When a column is not displayed, a 

713 message is sent to the logger and terminal indicating that the 

714 column values are uniform and listing the uniform value. 

715  

716 Table column descriptions: 

717  

718 Date/Time Average date and time of data sample interval 

719 Intrf Interferometer baseline (antenna names) 

720 UVDist uv-distance (units of wavelength) 

721 Fld Field ID 

722 SpW Spectral Window ID 

723 Chn Channel number 

724 Correlated polarization Correlated polarizations (eg: RR, LL, XY) 

725  

726 Sub-columns: 

727  

728 Amp Visibility amplitude 

729 Phs Visibility phase 

730 Wt Weight of visibility measurement 

731 F Flag: `F' = flagged datum; ` ' = unflagged 

732  

733 """ 

734 return self._swigobj.lister(options, datacolumn, field, spw, antenna, timerange, correlation, scan, feed, array, observation, uvrange, average, showflags, msselect, pagerows, listfile) 

735 

736 def metadata(self, cachesize=float(50)): 

737 """Get the MS metadata associated with this MS. 

738 """ 

739 return _wrap_msmetadata(swig_object=self._swigobj.metadata(cachesize)) 

740 

741 def msselect(self, items={ }, onlyparse=False): 

742 """A return value of True implies that the combination of all 

743 selection expressions resulted in a non-Null combined TaQL 

744 expression. False implies that the combined TaQL could not be 

745 formed (i.e. it is Null, and the "selected MS" will be the same as 

746 the input MS). 

747  

748 The details of selection expressions are desribed in the 

749 MSSelection Memo. 

750  

751 Note that this function can be called multiple times but the 

752 result is cumulative. Each selection will work on the data 

753 already selected from all previous calls of this function. Use 

754 the function reset() to reset all selections to NULL (original 

755 dataset). 

756  

757 """ 

758 return self._swigobj.msselect(items, onlyparse) 

759 

760 def msselectedindices(self): 

761 """The return indices are the result of parsing the MSSelection 

762 expressions provided in the msselect function. 

763  

764 """ 

765 return self._swigobj.msselectedindices() 

766 

767 def msseltoindex(self, vis='', spw=[ ], field=[ ], baseline=[ ], time=[ ], scan=[ ], uvrange=[ ], observation=[ ], polarization=[ ], taql=''): 

768 """Utility function that will return the ids of the selection used. 

769  

770 """ 

771 return self._swigobj.msseltoindex(vis, spw, field, baseline, time, scan, uvrange, observation, polarization, taql) 

772 

773 def selectinit(self, datadescid=int(0), reset=False): 

774 """A measurement set can contain data with a variety of different 

775 shapes (as described in the overall description to this tool). To 

776 allow functions to return data in fixed shape arrays you need to 

777 select, using this function, rows that contain the same data shape. 

778 You do not need to use this function if all the data in your 

779 measurement set has only one shape. 

780  

781 The DATA_DESC_ID column in the measurement set contains a value 

782 that maps to a particular row in the POLARIZATION and 

783 SPECTRAL_WINDOW subtables. Hence all rows with the same value in 

784 the DATA_DESC_ID column must have the same data shape. To select 

785 all the data where the DATA_DESC_ID value is N you call this 

786 function with the datadescid argument set to N. 

787  

788 It is possible to have a measurement set with differing values in 

789 the DATA_DESC_ID column but where all the data is a fixed shape. 

790 For example this will occur if the reference frequency changes but 

791 the number of spectral channels is fixed. In cases like this all 

792 the data can be selected and this function does not need to be 

793 used. 

794  

795 To return to the completely unselected measurement set, set the 

796 reset argument to True. This will allow you to access the full 

797 range of rows in the measurement set, rather than just the 

798 selected measurement set. 

799  

800 The datadescid must always be a non-negative integer. 

801  

802 """ 

803 return self._swigobj.selectinit(datadescid, reset) 

804 

805 def select(self, items={ }): 

806 """This function will select a subset of the current measurement set 

807 based on the range of values for each field in the input record. 

808 The range function will return a record that can be altered and 

809 used as the argument for this function. A successful selection 

810 returns True. Unrecognized fields are ignored. 

811  

812 Allowable items for select include: 'antenna1', 'antenna2', 

813 'array_id', 'feed1', 'feed2', 'field_id', 'ifr_number', 'rows', 

814 'scan_number', 'data_desc_id', 'time', 'times', 'u', 'v', 'w', 

815 and 'uvdist'. 

816  

817 You need to call selectinit before 

818 calling this function. If you haven't then selectinit will be 

819 called for you with default arguments. 

820  

821 Repeated use of this function, with different arguments, will 

822 further refine the selection, resulting in a successively smaller 

823 selected measurement set. If the selected measurement set does not 

824 contain any rows then this function will return False and send a 

825 warning message in the logger. Otherwise this function will return 

826 True. To undo all the selections you need to use the selectinit 

827 function (with reset=True). 

828  

829 """ 

830 return self._swigobj.select(items) 

831 

832 def selecttaql(self, msselect=''): 

833 """This function will select a subset of the current measurement set 

834 based on the standard TaQL selection string given. 

835  

836 Repeated use of this function, with different arguments, will 

837 further refine the selection, resulting in a successively smaller 

838 selected measurement set. If the selected measurement set does not 

839 contain any rows then this function will return False and send a 

840 warning message in the logger. Otherwise this function will return 

841 True. To undo all the selections you need to use the selectinit 

842 function (with reset=True). Note that index values used in the 

843 TaQL string are zero-based as are all tool indices. 

844  

845 """ 

846 return self._swigobj.selecttaql(msselect) 

847 

848 def selectchannel(self, nchan=int(1), start=int(0), width=int(1), inc=int(1)): 

849 """This function allows you to select a subset of the frequency 

850 channels in the current measurement set. This function can also 

851 average, over frequency channels, prior to providing the values to 

852 the user. 

853  

854 Selection on channels is not allowed using either the select or 

855 command functions, as they can only select entire rows in a 

856 measurement set. Channel selection involves accessing only some of 

857 the values in a row. Like all the selection functions, this 

858 function does not change the current measurement but updates the 

859 measurement set selection parameters so that functions like 

860 getdata will return the desired subset of the data. Repeated use 

861 of this function will overwrite any previous channel selection. 

862  

863 There are four parameters, the number of output channels, the 

864 first input channel to use, the number of input channels to 

865 average into one output channel, and the increment in the input 

866 spectrum for the next output channel. All four parameters need to 

867 be specified. 

868  

869 When all data to be averaged is unflagged, the result is the 

870 averaged value and the corresponding flag is False. When all data 

871 is flagged, the result is set to zero and the corresponding flag is 

872 True. When data to be averaged is mixed (unflagged and flagged), 

873 only the unflagged values are averaged and the flag is set to 

874 False. 

875  

876 This function return True if the selection was successful, and 

877 False if not. In the latter case an error message will also be sent 

878 to the logger. 

879  

880 You need to call selectinit before calling this function. 

881 If you haven't then selectinit will be called for you with default 

882 arguments. 

883  

884 """ 

885 return self._swigobj.selectchannel(nchan, start, width, inc) 

886 

887 def selectpolarization(self, wantedpol=[ ]): 

888 """This function allows you to select a subset of the polarizations 

889 in the current measurement set. This function can also setup 

890 conversion to different polarization representations. 

891  

892 You specify the polarizations using a string vector. Allowable 

893 strings are include I, Q, U, V, RR, RL, LR, LL, XX, YY, XY, 

894 YX. These string must be specified in upper case. If the 

895 polarizations match those present in the measurement set they will 

896 be selected directly, otherwise all polarizations are read and 

897 then a conversion step is done. If the conversion cannot be done 

898 then an error will be produced when you try to access the data. 

899  

900 This function return True if the selection was successful, and 

901 False if not. 

902  

903 You need to call selectinit before calling this function. 

904 If you haven't then selectinit will be called for you with default 

905 arguments. 

906  

907 """ 

908 return self._swigobj.selectpolarization(wantedpol) 

909 

910 def statwt(self, combine='', timebin=int(1), slidetimebin=False, chanbin='spw', minsamp=int(2), statalg='classic', fence=float(-1), center='mean', lside=True, zscore=float(-1), maxiter=int(-1), fitspw='', excludechans=False, wtrange=[ ], preview=False, datacolumn='corrected'): 

911 """IF NOT RUN IN PREVIEW MODE, THIS APPLICATION WILL MODIFY THE 

912 WEIGHT, WEIGHT SPECTRUM, FLAG, AND FLAG_ROW COLUMNS OF THE INPUT 

913 MS. IF YOU WANT A PRISTINE COPY OF THE INPUT MS TO BE PRESERVED, 

914 YOU SHOULD MAKE A COPY OF IT BEFORE RUNNING THIS APPLICATION. 

915  

916 This application computes weights for the WEIGHT and 

917 WEIGHT_SPECTRUM (if present) columns based on the variance of 

918 values in the CORRECTED_DATA or DATA column. If the MS does not 

919 have the specified data column, the application will fail. The 

920 following algorithm is used: 

921  

922 1. For unflagged data in each sample, create two sets of values, 

923 one set is composed solely of the real part of the data values, 

924 the other set is composed solely of the imaginary part of the 

925 data values. 

926 2. Compute the weighted (by exposure time) variance of each of 

927 these sets, v_r and v_i. The weighted variance per unit 

928 inverse eposure time, v, is computed using 

929  

930 v = sum(e_i * (V_i - <V>)^2)/N, 

931  

932 where e_i is the exposure time for real/imaginary part of 

933 visibility V_i and 

934  

935 <V> = sum(e_i * V_i)/sum(e_i) 

936  

937 is the weighted mean of all the visibilities in the set, and N 

938 is the number of (unflagged) visibilities. 

939 3. Compute v_eq = (v_r + v_i)/2. 

940 4. Compute the normalized variance, v_norm = v_eq * <e>, where 

941  

942 <e> = sum(e_i)/N 

943  

944 is the mean of the exposure times. The associated weight of 

945 visibility V_i is e_i/v_eq. The weight will have unit of (data 

946 unit)^(-2), e.g., Jy^(-2). The visibility weights are what this 

947 application computes and writes. 

948  

949 Data are aggregated on a per-baseline, per-data description ID 

950 basis. Data are aggregated in bins determined by the specified 

951 values of the timebin and chanbin parameters. By default, data for 

952 separate correlations are aggregated separately. This behavior can 

953 be overridden by specifying combine="corr" (see below). 

954  

955 RULES REGARDING CREATING/INITIALIZING WEIGHT_SPECTRUM COLUMN 

956  

957 1. If run in preview mode (preview=True), no data are modified and 

958 no columns are added. 

959 2. Else if datacolumn equals 'residual' or 'residual_data' and 

960 a CORRECTED_DATA column exists, the WEIGHT and WEIGHT_SPECTRUM 

961 columns are not modified. 

962 3. Else if the MS already has a WEIGHT_SPECTRUM and this column has 

963 been initialized (has values), it will be populated with 

964 the new weights. The WEIGHT column will be populated with the 

965 corresponding median values of the associated WEIGHT_SPECTRUM 

966 array. 

967 4. Else if the frequency range specified for the sample is not the 

968 default ("spw"), the WEIGHT_SPECTRUM column will be created (if 

969 it doesn't already exist) and the new weights will be written to 

970 it. The WEIGHT column should be populated with the 

971 corresponding median values of the WEIGHT_SPECTRUM array. 

972 5. Otherwise the single value for each spectral window will be 

973 written to the WEIGHT column; the WEIGHT_SPECTRUM column will 

974 not be added if it doesn't already exist, and if it does, it 

975 will remain uninitialized (no values will be written to it). 

976  

977 In cases where columns are added and initialized, the 

978 WEIGHT_SPECTRUM values will be set equal to the corresponding 

979 WEIGHT values, and the SIGMA_SPECTRUM values will be set to the 

980 corresponding SIGMA values. 

981  

982 CAUTION: For some cases when only a subset of data is selected 

983 and the WEIGHT_SPECTRUM and/or SIGMA_SPECTRUM columns are created, 

984 there is a known code issue in which these columns are not properly 

985 created and initialized for the specified subset of data, although 

986 they are properly initialized for the entire dataset. In such cases, 

987 an exception will be thrown. Because the columns are created for the 

988 entire dataset, the user simply needs to rerun the statwt task using 

989 the same parameters and the task should complete as expected. Should 

990 this condition occur when the user is using the ms.statwt() tool 

991 method, the user should close the ms tool, and then reopen it using 

992 the same data set and configure the same selection, and rerun 

993 ms.statwt(). The tool method should then complete as expected. 

994  

995 RULES FOR MODIFYING WEIGHT, WEIGHT_SPECTRUM, SIGMA, and SIGMA_SPECTRUM 

996  

997 1. If datacolum='corrected' or 'residual' then values are written 

998 to the WEIGHT and WEIGHT_SPECTRUM (if applicable) columns only. 

999 2. If datacolumn='data' or 'residual_data' and the 'CORRECTED_DATA' 

1000 column does not exist, then values are written to the WEIGHT and 

1001 WEIGHT_SPECTRUM (if applicable) columns and values in the SIGMA 

1002 and SIGMA_SPECTRUM are set to 1/sqrt(newly computed weight). If 

1003 a weight value is 0, the corresponding sigma value is -1. 

1004 3. If datacolumn='data' or 'residual_data' and the 'CORRECTED_DATA' 

1005 column does exist, then the WEIGHT and WEIGHT_SPECTRUM columns 

1006 are not updated and values in the SIGMA and 

1007 SIGMA_SPECTRUM are set to 1/sqrt(of the newly computed weight). 

1008 If a weight value is 0, the corresponding sigma value is -1. 

1009 In this case, you should either split out the DATA column and 

1010 run statwt, or run with datacolumn='corrected' or 'residual' 

1011 to update WEIGHT/WEIGHT_SPECTRUM. Otherwise the data are 

1012 internally not consistent. 

1013  

1014 TIME BINNING 

1015  

1016 One of two algorithms can be used for time binning. If 

1017 slidetimebin=True, then a sliding time bin of the specified width 

1018 is used. If slidetimebin=False, then block time processing is used. 

1019 The sliding time bin algorithm will generally be both more memory 

1020 intensive and take longer than the block processing algorithm. Each 

1021 algorithm is discussed in detail below. 

1022  

1023 If the value of timebin is an integer, this value represents the 

1024 number of contiguous, unique time stamps (from the MS TIME column) 

1025 that should be used for averaging. 

1026  

1027 Block Time Processing 

1028  

1029 The data are processed in contiguous time blocks in this case. This 

1030 means that all WEIGHT_SPECTRUM values will be set to the same value 

1031 for all data within the same time bin/channel bin/correlation bin 

1032 (see the section on channel binning and description of combine="corr" 

1033 for more details on channel binning and correlation binning). 

1034  

1035 If timebin is specified as a time quantity (eg, '110s'), then the 

1036 time bins are not necessarily contiguous and are not necessarily the 

1037 same width. The start of a bin is always coincident with a value 

1038 from the TIME column, So for example, if values from the TIME column 

1039 are [20s, 60s, 100s, 140s, 180s, 230s], and timebin = 110s, the 

1040 first bin would start at 20s and run to 130s, so that data from 

1041 timestamps 20s, 60s, and 100s will be included in the first bin. The 

1042 second bin would start at 140s, so that data for timestamps 140s, 

1043 180s, and 230s would be included in the second bin. 

1044  

1045 In the case where timebin is an integer, this denotes the number of 

1046 contigous timestamps that should be binned together. Note that, in 

1047 this case, for rows "left over" in the upper edge of the bin, their 

1048 values are computed using timebin that would include rows with times 

1049 earlier than them. For example, in an MS with 8 rows in one block 

1050 to be processed and timebin=3, timestamps 1, 2, and 3 would be used 

1051 to compute the weights of the first three three rows, and rows 4, 5, 

1052 and 6 would be used to compute weights for the next three rows as 

1053 expected. Rows 7 and 8 are "left over" rows, but three rows (as per 

1054 the integer timebin specification) are still used to compute them. 

1055 Row 7 and 8 weights are computed by combining data in rows 6, 7, and 8. 

1056  

1057 Sliding Time Window Processing 

1058  

1059 In the sliding time window case, in the case where timebin is a time 

1060 quantity, the time window is always centered on the timestamp of the 

1061 row in question and extends +/-timebin/2 around that timestamp, subject 

1062 the the time block boundaries. 

1063  

1064 In the case where timebin is an integer, there are two cases to 

1065 consider: 

1066  

1067 timebin is odd: In this case the target row's data and the data from 

1068 the +/-(n-1)/2 rows around the target row are also used. 

1069  

1070 timebin is even: In this case, the target row's data and the data from 

1071 the n/2 rows after the target row and the n/2 - 1 rows before the target 

1072 row are used. 

1073  

1074 When timebin is an int, for "edge" rows, the timebin extends from the 

1075 edge of the block to the corresponding timebin value of rows away from 

1076 the edge, so that the timebin is not symmetrical around the target rows, 

1077 but includes the number of rows specified by the timebin value. 

1078  

1079 OVERRIDING DEFAULT BLOCK BOUNDARIES 

1080  

1081 Rows with the same baselines and data description IDs which are included 

1082 in that window are used for determining the weight of that row. The 

1083 boundaries of the time block to which the window is restricted are 

1084 determined by changes in FIELD_ID, ARRAY_ID, and SCAN_NUMBER. One can 

1085 override this behavior for FIELD_ID and/or SCAN_NUMBER by specifying the 

1086 combine parameter (see below). Unlike the time block processing algorithm, 

1087 this sliding time window algorithm requires that details of all rows for 

1088 the time window in question are kept in memory, and thus the sliding 

1089 window algorithm in general and the block processing row when timebin is 

1090 an int, requires more memory than the block processing method when 

1091 timebin is a quantity. Also, unlike the block processing method which 

1092 computes a single value for all weights within a single bin, the sliding 

1093 window method requires that each row (along with each channel and 

1094 correlation bin) be processed individually, so in general the sliding 

1095 window method will take longer than the block processing method. 

1096  

1097 CHANNEL BINNING 

1098  

1099 The width of channel bins is specified via the chanbin parameter. 

1100 Channel binning occurs within individual spectral windows; bins 

1101 never span multiple spectral windows. Each channel will be included 

1102 in exactly one bin. 

1103  

1104 The default value "spw" indicates that all channels in each 

1105 spectral window are to be included in a single bin. 

1106  

1107 Any other string value is interpreted as a quantity, and so should 

1108 have frequency units, eg "1MHz". In this case, the channel 

1109 frequencies from the CHAN_FREQ column of the SPECTRAL_WINDOW 

1110 subtable of the MS are used to determine the bins. The first bin 

1111 starts at the channel frequency of the 0th channel in the spectral 

1112 window. Channels with frequencies that differ by less than the 

1113 value specified by the chanbin parameter are included in this bin. 

1114 The next bin starts at the frequency of the first channel outside 

1115 the first bin, and the process is repeated until all channels have 

1116 been binned. 

1117  

1118 If specified as an integer, the value is interpreted as the number 

1119 of channels to include in each bin. The final bin in the spectral 

1120 window may not necessarily contain this number of channels. For 

1121 example, if a spectral window has 15 channels, and chanbin is 

1122 specified to be 6, then channels 0-5 will comprise the first bin, 

1123 channels 6-11 the second, and channels 12-14 the third, so that 

1124 only three channels will comprise the final bin. 

1125  

1126 MINIMUM REQUIRED NUMBER OF VISIBILITIES 

1127  

1128 The minsamp parameter allows the user to specify the minimum number 

1129 of unflagged visibilities that must be present in a sample for that 

1130 sample's weight to be computed. If a sample has less than this 

1131 number of unflagged points, the associated weights of all the 

1132 points in the sample are set to zero, and all the points in the 

1133 sample are flagged. 

1134  

1135 AGGREGATING DATA ACROSS BOUNDARIES 

1136  

1137 By default, data are not aggregated across changes in values in the 

1138 columns ARRAY_ID, SCAN_NUMBER, STATE_ID, FIELD_ID, and 

1139 DATA_DESC_ID. One can override this behavior for SCAN_NUMBER, 

1140 STATE_ID, and FIELD_ID by specifying the combine parameter. For 

1141 example, specifying combine="scan" will ignore scan boundaries when 

1142 aggregating data. Specifying combine="field, scan" will ignore both 

1143 scan and field boundaries when aggregating data. 

1144  

1145 Also by default, data for separate correlations are aggregated 

1146 separately. Data for all correlations within each spectral window 

1147 can be aggregated together by specifying "corr" in the combine 

1148 parameter. 

1149  

1150 Any combination and permutation of "scan", "field", "state", and 

1151 "corr" are supported by the combine parameter. Other values will be 

1152 silently ignored. 

1153  

1154 STATISTICS ALGORITHMS 

1155  

1156 The supported statistics algorithms are described in detail in the 

1157 imstat and ia.statistics() help. For the current application, these 

1158 algorithms are used to compute vr and vi (see above), such that the 

1159 set of the real parts of the visibilities and the set of the 

1160 imaginary parts of the visibilities are treated as independent data 

1161 sets. 

1162  

1163 RANGE OF ACCEPTABLE WEIGHTS 

1164  

1165 The wtrange parameter allows one to specify the acceptable range 

1166 (inclusive, except for zero) for weights. Data with weights 

1167 computed to be outside this range will be flagged. If not specified 

1168 (empty array), all weights are considered to be acceptable. If 

1169 specified, the array must contain exactly two nonnegative numeric 

1170 values. Note that data with weights of zero are always flagged. 

1171  

1172 INCLUDING CHANNELS 

1173  

1174 Channels can be included in the computation of the weights by 

1175 specifying the fitspw parameter. This parameter accepts a 

1176 valid MS channel selection string. Data associated with the 

1177 selected channels will be used in computing the weights; all other 

1178 channels will be excluded from the computation of weights. By 

1179 default (empty string), all channels are included. 

1180  

1181 PREVIEW MODE 

1182  

1183 By setting preview=True, the application is run in "preview" mode. 

1184 In this mode, no data in the input MS are changed, although the 

1185 amount of data that the application would have flagged is reported. 

1186  

1187 DATA COLUMN 

1188  

1189 The datacolumn parameter can be specified to indicate which data 

1190 column should be used for computing the weights. The values 

1191 "corrected" for the CORRECTED_DATA column and "data" for the DATA 

1192 column are supported (minimum match, case insensitive). One may 

1193 specify 'residual' in which case the values used are the result of 

1194 the CORRECTED_DATA column - model, or 'residual_data' in which 

1195 case the values used are the DATA column - model, where model 

1196 is the CORRECTED_DATA column if it exists, or if it doesn't, 

1197 the virtual source model if one exists, or if that doesn't, then 

1198 no model is used and the 'residual' and 'residual_data' cases 

1199 are equivalent to the 'corrected' and 'data' cases, respectively. 

1200 The last two options are to allow for operation on timescales or 

1201 frequency ranges which are larger than that over which the sky 

1202 signal is expected to be constant. This situation arises in eg, 

1203 OTF mapping, and also perhaps with sources with significant 

1204 spectral structure. In cases where a necessary column doesn't 

1205 exist, an exception will be thrown and no data will be changed. 

1206 NOTE: It is the user's responsibility to ensure that a model has 

1207 been set for all selected fields before using datacolumn='residual' 

1208 or 'residual_data'. 

1209  

1210 RETURN VALUE 

1211  

1212 In all cases, the mean and variance of the set of all weights computed 

1213 by the application is reported and returned in a dictionary with keys 

1214 'mean' and 'variance'. Weights for which there are corresponding flags 

1215 (=True) prior to running the application are excluded from the 

1216 computation of these statistics. If the WEIGHT_SPECTRUM values are 

1217 available, they are used to compute the statistics, otherwise, 

1218 the WEIGHT values are used. The returned statistics are always computed 

1219 using the classic algorithm; the value of statalg has no impact on how 

1220 they are computed. 

1221  

1222 OTHER CONSIDERATIONS 

1223  

1224 Flagged values are not used in computing the weights, although the 

1225 associated weights of these values are updated. 

1226  

1227 If the variance for a set of data is 0, all associated flags for 

1228 that data are set to True, and the corresponding weights are set to 

1229 0. 

1230  

1231 Because data are modified in the input MS, the nomodify parameter 

1232 must be set to False when opening the associated MS tool. 

1233  

1234 """ 

1235 return self._swigobj.statwt(combine, timebin, slidetimebin, chanbin, minsamp, statalg, fence, center, lside, zscore, maxiter, fitspw, excludechans, wtrange, preview, datacolumn) 

1236 

1237 def oldstatwt(self, dorms=False, byantenna=True, sepacs=True, fitspw=[ ], fitcorr=[ ], combine='', timebin=[ ], minsamp=int(3), field=[ ], spw=[ ], antenna='', timerange='', scan=[ ], intent='', array=[ ], correlation='', obs='', datacolumn='corrected_data'): 

1238 """NOT IMPLEMENTED YET. 

1239  

1240 This function estimates the noise from the scatter of the 

1241 visibilities, sets SIGMA to it, and WEIGHT to SIGMA**-2. 

1242  

1243 Ideally the visibilities used to estimate the scatter, as selected 

1244 by fitspw and fitcorr, should be pure noise. If you know for 

1245 certain that they are, then setting dorms to True will give the 

1246 best result. Otherwise, use False (standard sample standard 

1247 deviation). More robust scatter estimates like the interquartile 

1248 range or median absolute deviation from the median are not offered 

1249 because they require sorting by value, which is not possible for 

1250 complex numbers. 

1251  

1252 To beat down the noise of the noise estimate, the sample size per 

1253 estimate can be made larger than a single spw and baseline. (Using 

1254 combine='spw' is to interpolate between spws with line-free 

1255 channels is recommended when an spw has no line-free channels.) 

1256 timebin smooths the noise estimate over time. windowtype sets the 

1257 type of time smoothing. 

1258  

1259 WEIGHT and SIGMA will not be changed for samples that have fewer 

1260 than minsamp visibilities. Selected visibilities for which no 

1261 noise estimate is made will be flagged. Note that minsamp is 

1262 effectively at least 2 if dorms is False, and 1 if it is True. 

1263  

1264 """ 

1265 return self._swigobj.oldstatwt(dorms, byantenna, sepacs, fitspw, fitcorr, combine, timebin, minsamp, field, spw, antenna, timerange, scan, intent, array, correlation, obs, datacolumn) 

1266 

1267 def regridspw(self, outframe='LSRK', mode='chan', restfreq=float(-3E30), interpolation='LINEAR', start=float(-3E30), center=float(-3E30), bandwidth=float(-1.), chanwidth=float(-1.), hanning=True): 

1268 """This function permits you to transform the spectral data of your 

1269 measurement set to a given reference frame. The present reference 

1270 frame information in the MS is examined and the transformation 

1271 performed accordingly. Since all such transformations are linear in 

1272 frequency, a pure change of reference frame only affects the 

1273 channel boundary definitions. 

1274  

1275 In addition, the function permits you to permanently regrid the 

1276 data, i.e. reduce the channel number and/or move the boundaries 

1277 using several interpolation methods (selected using parameter 

1278 "interpolation"). The new channels are equidistant in frequency (if 

1279 parameter "mode" is chosen to be vrad or freq, or equidistant in 

1280 wavelength if parameter "mode" is chosen to be vopt or wave). If 

1281 "mode" is chosen to be "chan", the regridding is performed by 

1282 combining the existing channels, i.e. not moving but just 

1283 eliminating channel boundaries where necessary. 

1284  

1285 The regridding is applied to the channel definition and all data of 

1286 the MS, i.e. all columns which contain arrays whose dimensions 

1287 depend on the number of channels. The input parameters are verified 

1288 before any modification is made to the MS. 

1289  

1290 The target reference frame can be set by providing the name of a 

1291 standard reference frame (LSRK, LSRD, BARY, GALACTO, LGROUP, CMB, 

1292 TOPO, GEO, or SOURCE, default = no change of frame) in parameter 

1293 "outframe". For each field in the MS, the channel frequencies are 

1294 transformed from their present reference frame to the one given by 

1295 parameter "outframe". 

1296  

1297 If the regridding parameters are set, they are interpreted in the 

1298 "outframe" reference frame. The regridding is applied to the data 

1299 after the reference frame transformation. 

1300  

1301 """ 

1302 return self._swigobj.regridspw(outframe, mode, restfreq, interpolation, start, center, bandwidth, chanwidth, hanning) 

1303 

1304 def cvel(self, mode='channel', nchan=int(-1), start=[ ], width=[ ], interp='linear', phasec=[ ], restfreq=[ ], outframe='', veltype='radio', hanning=True): 

1305 """This function permits you to transform the spectral data of your 

1306 measurement set to a given reference frame and/or regrid it. It 

1307 will combine all spectral windows of the MS into one. 

1308  

1309 """ 

1310 return self._swigobj.cvel(mode, nchan, start, width, interp, phasec, restfreq, outframe, veltype, hanning) 

1311 

1312 def hanningsmooth(self, datacolumn='corrected'): 

1313 """This function Hanning smooths the frequency channels with a 

1314 weighted running average of: 

1315 smoothedData[i] = 0.25*correctedData[i-1] + 0.50*correctedData[i] 

1316 + 0.25*correctedData[i-1] 

1317 The first and last channels are flagged. Inclusion of a flagged 

1318 value in an average causes that averaged data value to be flagged. 

1319  

1320 """ 

1321 return self._swigobj.hanningsmooth(datacolumn) 

1322 

1323 def cvelfreqs(self, spwids=[ int(0) ], fieldids=[ int(0) ], obstime='', mode='channel', nchan=int(-1), start=[ ], width=[ ], phasec=[ ], restfreq=[ ], outframe='', veltype='radio', verbose=True): 

1324 """Take the spectral grid of a given spectral window, tranform and 

1325 regrid it as prescribed by the given grid parameters (same as in 

1326 cvel and clean) and return the transformed values as a list. The MS 

1327 is not modified. Useful for tests of gridding parameters before 

1328 using them in cvel or clean. 

1329  

1330 """ 

1331 return self._swigobj.cvelfreqs(spwids, fieldids, obstime, mode, nchan, start, width, phasec, restfreq, outframe, veltype, verbose) 

1332 

1333 def contsub(self, outputms='', fitspw=[ ], fitorder=int(1), combine='', spw='*', unionspw='*', field='', scan='', intent='', correlation='', obs='', whichcol='CORRECTED_DATA'): 

1334 """DEPRECATED: This function is deprecated and will be removed in an 

1335 upcoming release. 

1336  

1337 NOT FULLY IMPLEMENTED YET. uvcontsub uses the cb tool for now. 

1338 (The only reason to implement it in ms is to save time and disk 

1339 space.) 

1340  

1341 This function estimates the continuum emission of the MS and writes 

1342 a MS with that estimate subtracted, using the ms tool. The 

1343 estimate is made, separately for the real and imaginary parts of 

1344 each baseline, by fitting a low order polynomial to the unflagged 

1345 visibilities selected by fitspw (depending on combine). 

1346  

1347 """ 

1348 return self._swigobj.contsub(outputms, fitspw, fitorder, combine, spw, unionspw, field, scan, intent, correlation, obs, whichcol) 

1349 

1350 def continuumsub(self, field=[ ], fitspw=[ ], spw=[ ], solint=[ ], fitorder=int(0), mode='subtract'): 

1351 """DEPRECATED: This function is deprecated and will be removed in an 

1352 upcoming release. 

1353  

1354 This function provides a means of continuum determination and 

1355 subtraction by fitting a polynomial of desired order to a subset of 

1356 channels in each time-averaged uv spectrum. The fit is used to 

1357 model the continuum in all channels (not just those used in the 

1358 fit), for subtraction, if desired. 

1359  

1360 Use the fitspw parameter to limit the spectral windows processed and 

1361 the range of channels used to estimate the continuum in each (avoid 

1362 channels containing spectral lines). 

1363  

1364 The default solution interval 'int' will result in per-integration 

1365 continuum fits for each baseline. 

1366  

1367 The mode parameter indicates how the continuum model (the result of 

1368 the fit) should be used: 

1369 - 'subtract' will store the continuum model in the MODEL_DATA column 

1370 and subtract it from the CORRECTED_DATA column 

1371 - 'replace' will replace the CORRECTED_DATA column with the 

1372 continuum model (useful if you want to image the continuum model 

1373 result) 

1374 - 'model' will only store the continuum model in the MODEL_DATA 

1375 column (the CORRECTED_DATA is unaffected). 

1376  

1377 It is important to start the ms tool with nomodify=False so that 

1378 changes to the dataset will be allowed (see example below). For 

1379 now, the only way to recover the un-subtracted CORRECTED_DATA 

1380 column is to use calibrater.correct() again. 

1381  

1382 Note that the MODEL_DATA and CORRECTED_DATA columns must be present 

1383 for continuumsub to work correctly. The function will warn the 

1384 user if they are not present, and abort. To add these scratch 

1385 columns, close the ms tool, then start a calibrater or an imager 

1386 tool, which will add the scratch columns. Then restart the ms 

1387 tool, and try continuumsub again. 

1388  

1389 """ 

1390 return self._swigobj.continuumsub(field, fitspw, spw, solint, fitorder, mode) 

1391 

1392 def uvsub(self, reverse=False): 

1393 """This function subtracts model visibility data from corrected 

1394 visibility data leaving the residuals in the corrected data column. 

1395 If the parameter reverse is set True, this process is reversed. 

1396  

1397 """ 

1398 return self._swigobj.uvsub(reverse) 

1399 

1400 def addephemeris(self, id=int(-1), ephemerisname='', comment='', field=[ ]): 

1401 """ 

1402 """ 

1403 return self._swigobj.addephemeris(id, ephemerisname, comment, field) 

1404 

1405 def timesort(self, newmsname=''): 

1406 """This function sorts the main table of the measurement set by the 

1407 contents of the column TIME in ascending order and writes a copy of 

1408 the MS with the sorted main table into newmsfile. 

1409  

1410 If no newmsname is given, a sorted copy of the MS is written into a 

1411 new MS under the name x.sorted (where x is the name of the original 

1412 MS). The original MS is then closed and deleted. The new MS is 

1413 renamed to the name of the original MS and then reopened. 

1414  

1415 """ 

1416 return self._swigobj.timesort(newmsname) 

1417 

1418 def sort(self, newmsname='', columns=[ ]): 

1419 """This function sorts the main table of the measurement set by the 

1420 contents of the input set of columns in ascending order and writes 

1421 a copy of the MS with the sorted main table into newmsfile. 

1422  

1423 If no newmsname is given, a sorted copy of the MS is written into a 

1424 new MS under the name x.sorted (where x is the name of the original 

1425 MS). The original MS is then closed and deleted. The new MS is 

1426 renamed to the name of the original MS and then reopened. 

1427  

1428 """ 

1429 return self._swigobj.sort(newmsname, columns) 

1430 

1431 def iterinit(self, columns=[ ], interval=float(0.0), maxrows=int(0), adddefaultsortcolumns=True): 

1432 """Specify the columns to iterate over and the time interval to use 

1433 for the TIME column iteration. The columns are specified by their 

1434 MS column name and must contain scalar values. 

1435  

1436 Note that the following default sort columns are always added to 

1437 the specified columns: array_id, field_id, data_desc_id and time. 

1438 This is so that the iterator can keep track of the coordinates 

1439 associated with the data (field direction, frequency, etc.). If you 

1440 want to sort on these columns last instead of first, you need to 

1441 include them in the columns specified. If you don't want to sort on 

1442 these columns at all, you can set adddefaultsortcolumns to False. 

1443  

1444 You may want to use iteration for a large dataset. After calling 

1445 iterinit, you must call iterorigin before attempting to retrieve 

1446 data with getdata. 

1447  

1448 You need to call selectinit before calling this. 

1449  

1450 """ 

1451 return self._swigobj.iterinit(columns, interval, maxrows, adddefaultsortcolumns) 

1452 

1453 def iterorigin(self): 

1454 """Set or reset the iterator to the start of the currently specified 

1455 iteration. You need to call this after iterinit, before attempting 

1456 to retrieve data with getdata. You may also use iterorigin to set 

1457 the iterator back to the start before you reach the end of the 

1458 data. 

1459  

1460 """ 

1461 return self._swigobj.iterorigin() 

1462 

1463 def iternext(self): 

1464 """This sets the currently selected table (as accessed with getdata) 

1465 to the next iteration. If there is no more data, the function 

1466 returns False and the selection is reset to that before the 

1467 iteration started. You need to call iterinit and iterorigin 

1468 before calling this. 

1469  

1470 """ 

1471 return self._swigobj.iternext() 

1472 

1473 def iterend(self): 

1474 """This sets the currently selected table (as accessed with 

1475 getdata) to the table that was selected before iteration 

1476 started. Use this to end the iteration prematurely. There is no 

1477 need to call this if you continue iterating until iternext 

1478 returns False. 

1479  

1480 See the example below. 

1481  

1482 """ 

1483 return self._swigobj.iterend() 

1484 

1485 def ngetdata(self, items=[ ], ifraxis=False, ifraxisgap=int(0), increment=int(1), average=False): 

1486 """DEPRECATED: Please use the ms::getdata() function in place 

1487 of ms::ngetdata(). 

1488  

1489 This method extracts the data as specified in the items 

1490 parameter. The data is returned as a record with each item 

1491 as a separate key in the record (all in lower case). 

1492  

1493 Unless the iterator was initialized with a niterinit(), this 

1494 method initializes the iterator as niterinit([".."],0.0,0,False). 

1495  

1496 """ 

1497 return self._swigobj.ngetdata(items, ifraxis, ifraxisgap, increment, average) 

1498 

1499 def niterinit(self, columns=[ ], interval=float(0.0), maxrows=int(0), adddefaultsortcolumns=True): 

1500 """DEPRECATED: Please use the ms::iterinit() function in place 

1501 of ms::niterinit(). 

1502  

1503 """ 

1504 return self._swigobj.niterinit(columns, interval, maxrows, adddefaultsortcolumns) 

1505 

1506 def niterorigin(self): 

1507 """DEPRECATED: Please use the ms::iterorigin() function in place 

1508 of ms::niterorigin(). 

1509  

1510 Set or reset the iterator to the start of the currently 

1511 specified iteration. You need to call this before attempting to 

1512 iteratively retrieve data with ngetdata. You can set the 

1513 iteration back to the start before you reach the end of the 

1514 data. You need to call iterinit before calling this. See the 

1515 example below. 

1516  

1517 """ 

1518 return self._swigobj.niterorigin() 

1519 

1520 def niternext(self): 

1521 """DEPRECATED: Please use the ms::iternext() function in place 

1522 of ms::niternext(). 

1523  

1524 This sets the currently selected table (as accessed with 

1525 ngetdata) to the next iteration. If there is no more data, the 

1526 function returns False. You need to call iterinit and 

1527 iterorigin before calling this. See the example below. 

1528  

1529 """ 

1530 return self._swigobj.niternext() 

1531 

1532 def niterend(self): 

1533 """DEPRECATED: Please use the ms::iterend() function in place 

1534 of ms::niterend(). 

1535  

1536 The serves redundant purpose and is here only for backward 

1537 compatibility. 

1538  

1539 This method returns True if there are no more iterations left. 

1540 I.e., the iterations have ended. This same information is also 

1541 returned by niternext(). 

1542  

1543 With the use of the VisibilityIterator in the niterinit(), 

1544 niterorigin(), niternext() methods, the iterator is set to the 

1545 original state by calling niterinit() at any time. 

1546  

1547 See the example below. 

1548  

1549 """ 

1550 return self._swigobj.niterend() 

1551 

1552 def nrowold(self, selected=False): 

1553 """DEPRECATED: Please use the ms::nrow() function in place of 

1554 ms::nrowold(). 

1555  

1556 This function returns the number of rows in the measurement 

1557 set. If the optional argument selected is set to True, it returns 

1558 the number of currently selected rows, otherwise it returns the 

1559 the number of rows in the original measurement. 

1560  

1561 """ 

1562 return self._swigobj.nrowold(selected) 

1563 

1564 def rangeold(self, items=[ ], useflags=True, blocksize=int(10)): 

1565 """DEPRECATED: Please use the ms::range() function in place of 

1566 ms::rangeold(). 

1567  

1568 This function will return the range of values in the currently 

1569 selected measurement set for the items specified. Possible items 

1570 include most scalar columns, interferometer number 

1571 (1000*antenna1+antenna2), uvdist(ance), u, v, w, amplitude, phase, 

1572 real and imaginary components of the data (and corrected and model 

1573 versions of these - if these columns are present). See the table 

1574 at the top of the document to find the exact list. 

1575  

1576 You specify items in which you are interested using a string 

1577 vector where each element is a case insensitive item name. This 

1578 function will then return a record that has fields corresponding 

1579 to each of the specified items. Each field will contain the range 

1580 of the specified item. For many items the range will be the 

1581 minimum and maximum values but for some it will be a list of 

1582 unique values. Unrecognized items are ignored. 

1583  

1584 By default the FLAG column is used to exclude flagged data before 

1585 any ranges are determined, but you can set useflags=False to 

1586 include flagged data in the range. However, if you average in 

1587 frequency, flagging will still be applied. 

1588  

1589 You can influence the memory use and the reading speed using 

1590 the blocksize argument - it specifies how big a block of data 

1591 to read at once (in MB). For large datasets on machines with lots 

1592 of memory you may speed things up by setting this higher than the 

1593 default (10 MB). 

1594  

1595 For some items, you need to call selectinitold to select a portion 

1596 of the data with a unique shape prior to calling this function. 

1597  

1598 Items prefixed with corrected, model, residual or obs_residual 

1599 are not available unless your measurement set has been processed 

1600 either with the imager or calibrator tools. 

1601  

1602 """ 

1603 return self._swigobj.rangeold(items, useflags, blocksize) 

1604 

1605 def selectinitold(self, datadescid=int(0), reset=False): 

1606 """DEPRECATED: Please use the ms::selectinit() function in place of 

1607 ms::selectinitold(). 

1608  

1609 A measurement set can contain data with a variety of different 

1610 shapes (as described in the overall description to this tool). To 

1611 allow functions to return data in fixed shape arrays you need to 

1612 select, using this function, rows that contain the same data 

1613 shape. You do not need to use this function if all the data in 

1614 your measurement set has only one shape. 

1615  

1616 The DATA_DESC_ID column in the measurement set contains a 

1617 value that maps to a particular row in the POLARIZATION and 

1618 SPECTRAL_WINDOW subtables. Hence all rows with the same 

1619 value in the DATA_DESC_ID column must have the same data 

1620 shape. To select all the data where the DATA_DESC_ID value 

1621 is $N$ you call this function with the datadescid argument set to 

1622 $N$. 

1623  

1624 It is possible to have a measurement set with differing values in 

1625 the DATA_DESC_ID column but where all the data is a fixed 

1626 shape. For example this will occur if the reference frequency 

1627 changes but the number of spectral channels is fixed. In cases 

1628 like this all the data can be selected, using this function with 

1629 an argument of zero. If the data shape does change and you call 

1630 this function with an datadescid set to zero the return value will be False. In all other cases it 

1631 will be True. 

1632  

1633 To return to the completely unselected measurement set, set the 

1634 reset argument to True. This will allow you to access the full 

1635 range of rows in the measurement set, rather than just the 

1636 selected measurement set. 

1637  

1638 The datadescid must always be a non-negative integer. 

1639  

1640 """ 

1641 return self._swigobj.selectinitold(datadescid, reset) 

1642 

1643 def selectold(self, items={ }): 

1644 """DEPRECATED: Please use the ms::select() function in place of 

1645 ms::selectold(). 

1646  

1647 This function will select a subset of the current measurement set 

1648 based on the range of values for each field in the input record. 

1649 The rangeold function will return a record that can be altered and 

1650 used as the argument for this function. A successful selection 

1651 returns True. Unrecognized fields are ignored. 

1652  

1653 Allowable items for selectold include: antenna1, antenna2, 

1654 array_id, feed1, feed2, field_id, ifr_number, rows, scan_number, 

1655 data_desc_id, time, times, u, v, w, and uvdist. 

1656  

1657 You need to call selectinitold before 

1658 calling this function. If you haven't then selectinitold will be 

1659 called for you with default arguments. 

1660  

1661 Repeated use of this function, with different arguments, will 

1662 further refine the selection, resulting in a successively smaller 

1663 selected measurement set. If the selected measurement set does not 

1664 contain any rows then this function will return False and send a 

1665 warning message in the logger. Otherwise this function will return 

1666 True. To undo all the selections you need to use the selectinitold 

1667 function (with reset=True). 

1668  

1669 """ 

1670 return self._swigobj.selectold(items) 

1671 

1672 def selecttaqlold(self, msselect=''): 

1673 """DEPRECATED: Please use the ms::selecttaql() function in place of 

1674 ms::selecttaqlold(). 

1675  

1676 This function will select a subset of the current measurement set 

1677 based on the standard TaQL selection string given. 

1678  

1679 Repeated use of this function, with different arguments, will 

1680 further refine the selection, resulting in a successively smaller 

1681 selected measurement set. If the selected measurement set does not 

1682 contain any rows then this function will return False and send a 

1683 warning message in the logger. Otherwise this function will return 

1684 True. To undo all the selections you need to use the selectinitold 

1685 function (with reset=True). Note that index values used in the TaQL 

1686 string are zero-based as are all tool indices. 

1687  

1688  

1689 """ 

1690 return self._swigobj.selecttaqlold(msselect) 

1691 

1692 def selectchannelold(self, nchan=int(1), start=int(0), width=int(1), inc=int(1)): 

1693 """DEPRECATED: Please use the ms::selectchannel() function in place of 

1694 ms::selectchannelold(). 

1695  

1696 This function allows you to select a subset of the frequency 

1697 channels in the current measurement set. This function can also 

1698 average, over frequency channels, prior to providing the values to 

1699 the user. 

1700  

1701 Selection on channels is not allowed using either the select or 

1702 command functions as they can only select entire rows in a 

1703 measurement set. Channel selection involves accessing only some of 

1704 the values in a row. Like all the selection functions this 

1705 function does not change the current measurement but updates the 

1706 measurement set selection parameters so that functions like 

1707 getdataold will return the desired subset of the data. Repeated 

1708 use of this function will overwrite any previous channel selection. 

1709  

1710 There are four parameters, the number of output channels, the 

1711 first input channel to use, the number of input channels to 

1712 average into one output channel, and the increment in the input 

1713 spectrum for the next output channel. All four parameters need to 

1714 be specified. 

1715  

1716 When all data to be averaged is unflagged, the result is the 

1717 averaged value and the corresponding flag is False. When all data 

1718 is flagged, the result is set to zero and the corresponding flag is 

1719 True. When data to be averaged is mixed (unflagged and flagged), 

1720 only the unflagged values are averaged and the flag is set to 

1721 False. 

1722  

1723 This function return True if the selection was successful, and 

1724 False if not. In the latter case an error message will also be sent 

1725 to the logger. 

1726  

1727 You need to call selectinitold before 

1728 calling this function. If you haven't then selectinitold will be 

1729 called for you with default arguments. 

1730  

1731 """ 

1732 return self._swigobj.selectchannelold(nchan, start, width, inc) 

1733 

1734 def selectpolarizationold(self, wantedpol=[ ]): 

1735 """DEPRECATED: Please use the ms::selectpolarization() function in 

1736 place of ms::selectpolarizationold(). 

1737  

1738 This function allows you to select a subset of the polarizations 

1739 in the current measurement set. This function can also setup 

1740 conversion to different polarization representations. 

1741  

1742 You specify the polarizations using a string vector. Allowable 

1743 strings are include I, Q, U, V, RR, RL, LR, LL, XX, YY, XY, 

1744 YX. These string must be specified in upper case. If the 

1745 polarizations match those present in the measurement set they will 

1746 be selected directly, otherwise all polarizations are read and 

1747 then a conversion step is done. If the conversion cannot be done 

1748 then an error will be produced when you try to access the data. 

1749  

1750 This function return True if the selection was successful, and 

1751 False if not. 

1752  

1753 You need to call selectinitold before 

1754 calling this function. If you haven't then selectinitold will be 

1755 called for you with default arguments. 

1756  

1757 """ 

1758 return self._swigobj.selectpolarizationold(wantedpol) 

1759 

1760 def getdataold(self, items=[ ], ifraxis=False, ifraxisgap=int(0), increment=int(1), average=False): 

1761 """DEPRECATED: Please use the ms::getdata() function in place 

1762 of ms::getdataold(). 

1763  

1764 This function will read the specified items from the currently 

1765 selected measurement set and returns them in fields of a record. 

1766 The main difference between this and direct access of the table, 

1767 using the table tool, is that this function reads data from the 

1768 selected measurement set, it provides access to derived 

1769 quantities like amplitude and flag_sum and it can reorder the 

1770 data. 

1771  

1772 The items to read are specified, as with the rangeold function, 

1773 using a vector of strings. Allowable items include: amplitude, 

1774 corrected_amplitude, model_amplitude, ratio_amplitude, 

1775 residual_amplitude, obs_residual_amplitude, antenna1, antenna2, 

1776 axis_info, data, corrected_data, model_data, ratio_data, 

1777 residual_data, obs_residual_data, feed1, feed2, field_id, flag, 

1778 flag_row, flag_sum, ha (added to axis_info), ifr_number, imaginary, 

1779 corrected_imaginary, model_imaginary, ratio_imaginary, 

1780 residual_imaginary, obs_residual_imaginary, last (added to 

1781 axis_info), phase, corrected_phase, model_phase, ratio_phase, 

1782 residual_phase, obs_residual_phase, real, corrected_real, 

1783 ratio_real, residual_real, obs_residual_real, scan_number, sigma, 

1784 data_desc_id, time, ut (added to axis_info), uvw, u, v, w, uvdist, 

1785 and weight. Unrecognized items will result in a warning being sent 

1786 to the logger. Duplicate items are silently ignored. 

1787  

1788 The record that is returned contains fields that correspond to 

1789 each of the specified items. Most fields will contain an array. The 

1790 array may be one, two or three dimensional depending on whether the 

1791 corresponding row in the measurement set is a scalar, one or two 

1792 dimensional. Unless the ifraxis argument is set to True the length 

1793 of the last axis on these arrays will correspond to the number of 

1794 rows in the selected measurement set. 

1795  

1796 If the ifraxis argument is set to True, the row axis is split into 

1797 an interferometer axis and a time axis. For example a measurement 

1798 set with 90 rows, in an array with 6 telescopes (so that there are 

1799 15 interferometers), may have a data array of shape [4,32,90] 

1800 if ifraxis is False or [4,32,15,6], if ifraxis is True (assuming 

1801 there are 4 correlations and 32 channels). If there are missing 

1802 rows as will happen if not all interferometers where used for all 

1803 time-slots then a default value will be inserted. 

1804  

1805 This splitting of the row axis may not happen for items where 

1806 there is only a single value per row. For some items the returned 

1807 vector will contain only as many values as there are 

1808 interferometers and it is implicit that the same value should be 

1809 used for all time slots. The antenna1, antenna2, feed1, feed2, and 

1810 ifr_number items fall in this category. For other items the 

1811 returned vector will have as many values as there are time slots 

1812 and it is implicit that the same value should be used for all 

1813 interefometers. The field_id, scan_number, data_desc_id, and 

1814 time items fall into this category. 

1815  

1816 The axis_info item provides data labelling information. It 

1817 returns a record with the following fields: corr_axis, freq_axis, 

1818 ifr_axis and time_axis. The latter two fields are not present if 

1819 ifr_axis is set to False. The corr_axis field contains a string 

1820 vector with elements like 'RR' or 'XY' that indicates which 

1821 polarizations where correlated together to produce the data. The 

1822 length of this vector will always be the same as the length of the 

1823 first axis of the data array. The freq_axis field contains a record 

1824 with two fields, chan_freq and resolution. Each of these fields 

1825 contains vectors which indicate the centre frequency and spectral 

1826 resolution (FWHM) of each channel. The length of these vectors will 

1827 be the same as the length of the second axis in the data. The 

1828 ifr_axis field contains fields: ifr_number, ifr_name, 

1829 ifr_shortname, and baseline. The ifr_number is the same as returned 

1830 by the ifr_item, the ifr_name and ifr_shortname are string vecors 

1831 containing descriptions of the interferometer and the baseline is 

1832 the Euclidian distance, in meters between the two antennas. All of 

1833 these vectors have a length equal to the number of interferometers 

1834 in the selected measurement set ie., to the length of the third 

1835 axis in the data when ifraxis is True. The time_axis field contains 

1836 the MJD seconds field and optionally the HA, UT, and LAST fields. 

1837 To include the optional fields you need to add the ha, last or ut 

1838 strings to the list of requested items. All the fields in the 

1839 time_axis record contain vectors that indicate the time at the 

1840 midpoint of the observation and are in seconds. The MJD seconds 

1841 field is since 0 hours on the day having a modified julian day 

1842 number of zero and the rest are since midnight prior to the start 

1843 of the observation. 

1844  

1845 An optional gap size can be specified to visually separate groups 

1846 of interferometers with the same antenna1 index (handy for 

1847 identifying antennas in an interferometer vs time display). The 

1848 default is no gap. 

1849  

1850 An optional increment can be specified to return data from every 

1851 row matching the increment only. 

1852  

1853 When the average flag is set, the data will be averaged over the 

1854 time axis if the ifraxis is True or the row axis i.e., different 

1855 interferometers and times may be averaged together. In the latter 

1856 case, some of the coordinate information, like antenna_id, will 

1857 no longer make sense. When all data to be averaged is unflagged, 

1858 the result is the averaged value and the corresponding flag is 

1859 False. When all data is flagged, the result is set to zero and the 

1860 corresponding flag is True. When data to be averaged is mixed 

1861 (unflagged and flagged), only the unflagged values are averaged and 

1862 the flag is set to False. 

1863  

1864 You need to call selectinitold before 

1865 calling this function. If you haven't then selectinitold will be 

1866 called for you with default arguments. 

1867  

1868 Items prefixed with corrected, model, residual or obs_residual are 

1869 not available unless your measurement set has been processed either 

1870 with the imager or calibrator tools. 

1871  

1872 """ 

1873 return self._swigobj.getdataold(items, ifraxis, ifraxisgap, increment, average) 

1874 

1875 def putdataold(self, items={ }): 

1876 """DEPRECATED: Please use the ms::putdata() function in place 

1877 of ms::putdataold(). 

1878  

1879 This function allows you to write values from casapy variables back 

1880 into the measurement set table. The main difference between this 

1881 and directly accessing the table using the table tool is that this 

1882 function writes data to the selected measurement set. 

1883  

1884 Unlike the getdataold function you can only put items that 

1885 correspond to actual table columns. You cannot change the data 

1886 shape either so that the number of correlations, channels and rows 

1887 (or intereferometers/time slots) must match the values in the 

1888 selected measurement set. If the values were obtained using the 

1889 getdataold function with ifraxis argument set to True, then any 

1890 default values added to fill in missing intereferometer/timeslots 

1891 pairs will be ignored when writing the modified values back using 

1892 this function. 

1893  

1894 Allowable items include: data, corrected_data, model_data, flag, 

1895 flag_row, sigma, and weight. 

1896  

1897 The measurement set has to be opened for read/write access to be 

1898 able to use this function. 

1899  

1900 You need to call selectinitold before 

1901 calling this function. If you haven't then selectinitold will be 

1902 called for you with default arguments. 

1903  

1904 Items prefixed with corrected, model, residual or obs_residual are 

1905 not available unless your measurement set has been processed either 

1906 with the imager or calibrator tools. 

1907  

1908 """ 

1909 return self._swigobj.putdataold(items) 

1910 

1911 def iterinitold(self, columns=[ ], interval=float(0.0), maxrows=int(0), adddefaultsortcolumns=True): 

1912 """DEPRECATED: Please use the ms::iterinit() function in place 

1913 of ms::iterinitold(). 

1914  

1915 Specify the columns to iterate over and the time interval to use 

1916 for the TIME column iteration. The columns are specified by their 

1917 MS column name and must contain scalar values. 

1918  

1919 Note that the following columns are always added to the specified 

1920 columns: array_id, field_id, data_desc_id and time. This is so that 

1921 the iterator can keep track of the coordinates associated with the 

1922 data (field direction, frequency, etc.). If you want to sort on 

1923 these columns last instead of first, you need to include them in 

1924 the columns specified. If you don't want to sort on these columns 

1925 at all, you can set adddefaultsortcolumns to False. 

1926  

1927 You may want to use iteration for a large dataset. After calling 

1928 iterinitold, you must call iteroriginold before attempting to 

1929 retrieve data with getdataold. 

1930  

1931 You need to call selectinitold before calling this. 

1932  

1933 """ 

1934 return self._swigobj.iterinitold(columns, interval, maxrows, adddefaultsortcolumns) 

1935 

1936 def iteroriginold(self): 

1937 """DEPRECATED: Please use the ms::iterorigin() function in place 

1938 of ms::iteroriginold(). 

1939  

1940 Set or reset the iterator to the start of the currently specified 

1941 iteration. You need to call this after iterinitold, before 

1942 attempting to retrieve data with getdataold. You may also use 

1943 iteroriginold to set the iteration back to the start before you 

1944 reach the end of the data. 

1945  

1946 """ 

1947 return self._swigobj.iteroriginold() 

1948 

1949 def iternextold(self): 

1950 """DEPRECATED: Please use the ms::iternext() function in place 

1951 of ms::iternextold(). 

1952  

1953 This sets the currently selected table (as accessed with 

1954 getdataold) to the next iteration. If there is no more data, the 

1955 function returns False and the selection is reset to that before 

1956 the iteration started. You need to call iterinitold and 

1957 iteroriginold before calling this. 

1958  

1959 """ 

1960 return self._swigobj.iternextold() 

1961 

1962 def iterendold(self): 

1963 """DEPRECATED: Please use the ms::iterend() function in place 

1964 of ms::iterendold(). 

1965  

1966 This sets the currently selected table (as accessed with 

1967 getdataold) to the table that was selected 

1968 before iteration started. Use this to end the iteration 

1969 prematurely. There is no need to call this if you continue 

1970 iterating until iternextold returns False. 

1971  

1972 See the example below. 

1973  

1974 """ 

1975 return self._swigobj.iterendold() 

1976 

1977 def continuumsubold(self, field=[ ], fitspw=[ ], spw=[ ], solint=[ ], fitorder=int(0), mode='subtract'): 

1978 """DEPRECATED: This function is deprecated and will be removed in an 

1979 upcoming release. 

1980  

1981 This function provides a means of continuum determination and 

1982 subtraction by fitting a polynomial of desired order to a subset 

1983 of channels in each time-averaged uv spectrum. The fit is used 

1984 to model the continuum in all channels (not just those used in 

1985 the fit), for subtraction, if desired. Use the fitspw parameter 

1986 to limit the spectral windows processed and the range of channels 

1987 used to estimate the continuum in each (avoid channels 

1988 containing spectral lines). The default solution interval 'int' 

1989 will result in per-integration continuum fits for each baseline. 

1990 The mode parameter indicates how the continuum model (the result 

1991 of the fit) should be used: 'subtract' will store the continuum 

1992 model in the MODEL_DATA column and subtract it from the 

1993 CORRECTED_DATA column; 'replace' will replace the CORRECTED_DATA 

1994 column with the continuum model (useful if you want to image the 

1995 continuum model result); and 'model' will only store the 

1996 continuum model in the MODEL_DATA column (the CORRECTED_DATA is 

1997 unaffected). 

1998  

1999 It is important to open the dataset with nomodify=False so that 

2000 changes will be allowed (see example below). 

2001  

2002 For now, the only way to recover the un-subtracted CORRECTED_DATA 

2003 column is to use calibrater.correct() again. 

2004  

2005 Note that the MODEL_DATA and CORRECTED_DATA columns must be 

2006 present for continuumsubold to work correctly. The function will 

2007 warn the user if they are not present, and abort. To add these 

2008 scratch columns, close the ms tool, then start a calibrater or an 

2009 imager tool, which will add the scratch columns. Then restart 

2010 the ms tool, and try continuumsubold again. 

2011  

2012 """ 

2013 return self._swigobj.continuumsubold(field, fitspw, spw, solint, fitorder, mode) 

2014