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

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

2##################### c398d2c9adbb49acd894b261c1ce3ac6 ############################## 

3from __future__ import absolute_import 

4from .__casac__.table import table as _table 

5 

6from .errors import create_error_string 

7from .typecheck import CasaValidator as _validator 

8_pc = _validator( ) 

9from .coercetype import coerce as _coerce 

10from .tablerow import tablerow as _wrap_tablerow 

11_wrap_table = lambda swig_object: table(swig_object=swig_object) 

12 

13class table: 

14 _info_group_ = """table""" 

15 _info_desc_ = """Access tables from casapy""" 

16 ### self, tablename='', lockoptions={ }, nomodify=True 

17 def __init__(self, tablename='', lockoptions={ }, nomodify=True, *args, **kwargs): 

18 """Use this constructor to construct a table tool inside casapy from 

19 the name of a disk file containing a casa Table. A 

20 new table may also be created from a table descriptor 

21 (see tablecreatedesc). 

22 When creating a new table, detailed data manager information can be 

23 given using the texttt{dminfo} argument. This is a record as 

24 returned by the getdminfo 

25 function. 

26  

27 Most of the arguments are rarely used: most of the time, you'll 

28 just need to use the tablename, and perhaps nomodify. 

29  

30 A table can be shared by multiple processes by using the appropriate 

31 locking options. The possible options are: 

32 - auto: let the system take care of locking. At regular time 

33 intervals these autolocks are released to give other processes the 

34 opportunity to access the table. The aipsrc variable 

35 texttt{table.relinquish.reqautolocks.interval} defines the number 

36 of seconds between releasing autolocks on tables needed in another process. 

37 texttt{table.relinquish.allautolocks.interval} defines the number 

38 of seconds between releasing all autolocks. 

39 - autonoread: as auto, but no read locking is needed. This must be 

40 used with care, because it means that reading can be done while 

41 the table tool is not synchronized with the table file (as is 

42 normally done when a lock is acquired). The function texttt{resync} 

43 can be used to explicitly synchronize the table tool 

44 - user: the user takes care by explicit calls to lock and unlock 

45 - usernoread: as user and the no readlocking behaviour of autonoread. 

46 - permanent: use a permanent lock; the constructor fails when the table is 

47 already in use in another process 

48 - permanentwait: as above, but wait until the other process 

49 releases its lock 

50 - default: this is the default option. 

51 If the given table is already open, the locking option in use is not 

52 changed. Otherwise it reverts to auto. 

53 When auto locking is used, it is possible to give a record containing 

54 the fields option, interval, and/or maxwait. In this way advanced 

55 users have full control over the locking options. In practice this is 

56 hardly ever needed. 

57  

58 When creating a new table, the endian format in which the 

59 data should be stored, can be specified. The possible values are: 

60 - big: big endian format (as used on e.g. SUN) 

61 - little: little endian format (as used on e.g. PC) 

62 - local: use the endian format of the machine being used 

63 - aipsrc: use the endian format specified in aipsrc variable 

64 table.endianformat (which defaults to big). 

65 The default is aipsrc. 

66 Note that usually it is best to store data in local endian format, 

67 because that requires the least amount of byte swapping. However, 

68 if the table must be accessible with AIPS++ version 1.7 or before, 

69 big endian should be used. 

70  

71 When creating a new table, the table will normally reside on disk. It 

72 is, however, possible to specify that the table should be held in 

73 memory. In such a case the table is process specific, thus cannot be 

74 seen by other processes. Note that a memory table uses the MemoryStMan 

75 storage manager for all its stored columns, but it is still possible 

76 to use virtual columns as well. 

77 """ 

78 schema = {'tablename': {'type': 'cPath', 'coerce': _coerce.expand_path}, 'lockoptions': {'type': 'cDict'}, 'nomodify': {'type': 'cBool'}} 

79 doc = {'tablename': tablename, 'lockoptions': lockoptions, 'nomodify': nomodify} 

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

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

82 if self._swigobj is None: 

83 self._swigobj = _table(_pc.document['tablename'], _pc.document['lockoptions'], _pc.document['nomodify']) 

84 

85 def fromfits(self, tablename, fitsfile, whichhdu=int(1), storage='standard', convention='none', nomodify=True, ack=True): 

86 """Create a table from binary FITS format. This generates a CASA table 

87 from the binary FITS table in the given HDU (header unit) of the 

88 FITS file. Note that other FITS formats ({em e.g.} 

89 Image FITS and UVFITS) are read by other means. 

90 It is possible to specify the storage manager to use for the table: 

91 texttt{standard} is the default storage manager. 

92 texttt{incremental} is efficient for slowly varying data. 

93 texttt{memort} is for in memory use for e.g to grab given columns via getcol. 

94 """ 

95 return _wrap_table(swig_object=self._swigobj.fromfits(tablename, fitsfile, whichhdu, storage, convention, nomodify, ack)) 

96 

97 def fromascii(self, tablename, asciifile, headerfile='', autoheader=False, autoshape=[ int(-1) ], sep='', commentmarker='', firstline=int(0), lastline=int(-1), nomodify=True, columnnames=[ ], datatypes=[ ]): 

98 """Create a table from an ASCII file. Columnar data as well as 

99 table and column keywords may be specified. 

100 Once the table is created from the ASCII data, it is opened in the 

101 specified mode by the table tool. 

102  

103 The table columns are filled from a file containing the data values 

104 separated by a separator (one line per table row). The default 

105 separator is a blank. Blanks after the separator are ignored. 

106 If a non-blank separator is used, values can be empty. Such values 

107 default to 0, empty string, or F depending on the data type. E.g. 

108 1,,2, has 4 values of which the 2nd and 4th are empty and default to 0. 

109 Similarly if fewer values are given than needed, the missing values 

110 get the default value. 

111  

112 Either the data format can be explicitly specified or it can be found 

113 automatically. The former gives more control in ambiguous situations. 

114 Both scalar and array columns can be generated from the ASCII input. 

115 The format string determines the type and optional shape. 

116  

117 In automatic mode (texttt{autoheader=True}) the first line 

118 of the ASCII data is analyzed 

119 to deduce the data types. Only the types I, D, and A can be 

120 recognized. A number without decimal point or exponent is I (integer), 

121 otherwise it is D (double). Any other string is A (string). 

122 Note that a number may contain a leading sign (+ or -). 

123 The texttt{autoshape} argument can be used to specify if the input 

124 should be stored as multiple scalars (the default) or as a single 

125 array. In the latter case one axis in the shape can be defined as 

126 variable length by giving it the value 0. It means that the actual 

127 array shape in a row is determined by the number of values in the 

128 corresponding input line. 

129 Columns get the names texttt{Column1}, texttt{Column2}, etc.. 

130 For example: 

131 begin{enumerate} 

132 item 

133 texttt{autoshape=[]} (which is the default) means that all values 

134 are to be stored as scalar columns. 

135 item 

136 texttt{autoshape=0} means that all values in a row are to be stored as 

137 a variable length vector. 

138 item 

139 texttt{autoshape=10} defines a fixed length vector. If an input 

140 line contains less than 10 values, the vector is filled with default 

141 values. If more than 10 values, the latter values are ignored. 

142 item 

143 texttt{autoshape=[5,0]} defines a 2-dim array of which the 2nd axis is 

144 variable. Note that if an input line does not contain a multiple of 5 

145 values, the array is filled with default values. 

146 end{enumerate} 

147  

148 If the format of the table is explicitly specified, it has to be done 

149 either in the first two lines of the data file (named by the 

150 argument filename), or in a separate header file (named by the 

151 argument headerfile). In both forms, table keywords may also be 

152 specified before the column definitions. 

153 The column names and types can be described by two lines: 

154  

155 begin{enumerate} 

156 item The first line contains the names of the columns. 

157 These names may be enclosed in quotes (either single or double). 

158 item The second line contains the data type and optionally the shape 

159 of each column. Valid types are: 

160 begin{itemize} 

161 item S for Short data 

162 item I for Integer data 

163 item R for Real data 

164 item D for Double Precision data 

165 item X for Complex data (Real followed by Imaginary) 

166 item Z for Complex data (Amplitude then Phase) 

167 item DX for Double Precision Complex data (Real followed by Imaginary) 

168 item DZ for Double Precision Complex data (Amplitude then Phase) 

169 item A for ASCII data (a value must be enclosed in single or double quotes 

170 if it contains whitespace) 

171 item B for Boolean data (False are empty string, 0, or any string 

172 starting with F, f, N, or n). 

173 end{itemize} 

174 end{enumerate} 

175 If a column is an array, the shape has to be given after the data type 

176 without any whitespace. E.g. texttt{I10} defines an integer vector 

177 of length 10. texttt{A2,5} defines a 2-dim string array with shape 

178 [2,5]. Note that texttt{I} is not the same as texttt{I1} as the 

179 first one defines a scalar and the other one a vector with length 1. 

180 The last column can have one variable length axis denoted by the value 

181 0. It "consumes" the remainder of the input line. 

182  

183 If the argument headerfile is set then the header information is 

184 read from that file instead of the first lines of the data file. 

185  

186 To give a simple example of the form where the header information 

187 is located at the top of the data file: 

188  

189 begin{verbatim} 

190 COLI COLF COLD COLX COLZ COLS 

191 I R D X Z A 

192 1 1.1 1.11 1.12 1.13 1.14 1.15 Str1 

193 10 11 12 13 14 15 16 "" 

194 end{verbatim} 

195 Note that a complex number consists of 2 numbers. 

196 Also note that an empty string can be given. 

197  

198 Let us now give an example of a separate header file that one might use to get 

199 interferometer data into casa: 

200  

201 begin{verbatim} 

202 U V W TIME ANT1 ANT2 DATA 

203 R R R D I I X1,0 

204 end{verbatim} 

205  

206 The data file would then look like: 

207  

208 begin{verbatim} 

209 124.011 54560.0 3477.1 43456789.0990 1 2 4.327 -0.1132 

210 34561.0 45629.3 3900.5 43456789.0990 1 3 5.398 0.4521 

211 end{verbatim} 

212 Note that the DATA column is defined as a 2-dim array of 1 

213 correlation and a variable number of channels, so the actual number of 

214 channels is determined by the input. In this example both rows will 

215 have 1 channel (note that a complex value contains 2 values). 

216  

217 Tables may have keywords in addition to the columns. The keywords 

218 are useful for holding information that is global to the entire 

219 table (such as author, revision, history, {em etc,}). 

220 The keywords in the header definitions must preceed the column descriptions. 

221 They must be enclosed between a line that starts with ".key..." and 

222 a line that starts with ".endkey..." (where ... can be anything). 

223 Between these two lines each 

224 line should contain the following as listed below. 

225 A table keywordset and column keywordsets can be specified. 

226 The latter can be specified by specifying the column name after the 

227 .keywords string. 

228  

229 begin{itemize} 

230 item The keyword name, e.g., ANYKEY 

231 item The datatype and optional shape of the keyword 

232 (cf. list of valid types above) 

233 item The value or values for the keyword (the keyword may contain 

234 a scalar or an array of values). e.g., 3.14159 21.78945 

235 end{itemize} 

236  

237 Thus to continue the example above, one might wish to add keywords 

238 as follows: 

239  

240 begin{verbatim} 

241 .keywords 

242 DATE A "97/1/16" 

243 REVISION D 2.01 

244 AUTHOR A "Tim Cornwell" 

245 INSTRUMENT A "VLA" 

246 .endkeywords 

247 .keywords TIME 

248 UNIT A "s" 

249 .endkeywords 

250 U V W TIME ANT1 ANT2 DATA 

251 R R R D I I X1,0 

252 end{verbatim} 

253 Similarly to the column format string, the keyword formats can also 

254 contain shape information. The only difference is that if no shape is 

255 given, a keyword can have multiple values (making it a vector). 

256  

257 It is possible to ignore comment lines in the header and data file 

258 by giving the texttt{commentmarker}. It indicates that lines 

259 starting with the given marker are ignored. Note that the marker can 

260 be a regular expression (e.g. texttt{' *//'} tells that lines starting 

261 with // and optionally preceeded by blanks have to be ignored). 

262  

263 With the arguments texttt{firstline} and texttt{lastline} one can 

264 specify which lines have to be taken from the input file. A negative value 

265 means 1 for texttt{firstline} or end-of-file for texttt{lastline}. 

266 Note that if the headers and data are combined in one file, 

267 these line arguments apply to the whole file. If headers and data are in 

268 separate files, these line arguments apply to the data file only. 

269  

270 Also note that ignored comment lines are counted, thus are used to 

271 determine which lines are in the line range. 

272  

273 The number of rows is determined by the number of lines read from the data 

274 file. 

275 """ 

276 return self._swigobj.fromascii(tablename, asciifile, headerfile, autoheader, autoshape, sep, commentmarker, firstline, lastline, nomodify, columnnames, datatypes) 

277 

278 def open(self, tablename='', lockoptions={ }, nomodify=True): 

279 """Opens a disk file containing an existing casa Table. 

280  

281 Most of the time you just need to specify the tablename and perhaps 

282 nomodify. 

283  

284 A table can be shared by multiple processes by using the appropriate 

285 locking options. The possible options are: 

286 - auto: let the system take care of locking. At regular time 

287 intervals these autolocks are released to give other processes the 

288 opportunity to access the table. 

289 - autonoread: as auto, but no read locking is needed. This must be 

290 used with care, because it means that reading can be done while 

291 the table tool is not synchronized with the table file (as is 

292 normally done when a lock is acquired). The function texttt{resync} 

293 can be used to explicitly synchronize the table tool 

294 - user: the user takes care by explicit calls to lock and unlock 

295 - usernoread: as user and the no readlocking behaviour of autonoread. 

296 - permanent: use a permanent lock; the constructor fails when the table is 

297 already in use in another process 

298 - permanentwait: as above, but wait until the other process 

299 releases its lock 

300 - default: this is the default option. 

301 If the given table is already open, the locking option in use is not 

302 changed. Otherwise it reverts to auto. 

303 When auto locking is used, it is possible to give a record containing 

304 the fields option, interval, and/or maxwait. In this way advanced 

305 users have full control over the locking options. In practice this is 

306 hardly ever needed. 

307 """ 

308 return self._swigobj.open(tablename, lockoptions, nomodify) 

309 

310 def create(self, tablename='', tabledesc={ }, lockoptions={ }, endianformat='', memtype='', nrow=int(0), dminfo={ }): 

311 """Create a new casa Table. 

312  

313 Most of the time you just need to specify the table's name and a description of 

314 its format. 

315  

316 A table can be shared by multiple processes by using the appropriate 

317 locking options. The possible options are: 

318 - auto: let the system take care of locking. At regular time 

319 intervals these autolocks are released to give other processes the 

320 opportunity to access the table. 

321 - autonoread: as auto, but no read locking is needed. This must be 

322 used with care, because it means that reading can be done while 

323 the table tool is not synchronized with the table file (as is 

324 normally done when a lock is acquired). The function texttt{resync} 

325 can be used to explicitly synchronize the table tool 

326 - user: the user takes care by explicit calls to lock and unlock 

327 - usernoread: as user and the no readlocking behaviour of autonoread. 

328 - permanent: use a permanent lock; the constructor fails when the table is 

329 already in use in another process 

330 - permanentwait: as above, but wait until the other process 

331 releases its lock 

332 - default: this is the default option. 

333 If the given table is already open, the locking option in use is not 

334 changed. Otherwise it reverts to auto. 

335 When auto locking is used, it is possible to give a record containing 

336 the fields option, interval, and/or maxwait. In this way advanced 

337 users have full control over the locking options. In practice this is 

338 hardly ever needed. 

339 """ 

340 return self._swigobj.create(tablename, tabledesc, lockoptions, endianformat, memtype, nrow, dminfo) 

341 

342 def flush(self): 

343 """Until a flush is performed, the results of all operations 

344 are not reflected in any change to the 

345 disk file. Hence you {em must} do a flush to write the changes 

346 to disk. 

347 """ 

348 return self._swigobj.flush() 

349 

350 def fromASDM(self, tablename, xmlfile): 

351 """.keywords 

352 DATE A "07/7/23" 

353 REVISION D 0 

354 AUTHOR A "Paulo C. Cortes" 

355 INSTRUMENT A "ALMA" 

356 .endkeywords 

357  

358 The main function for this task is to create a CASA::Table from a XML ASDM Table. The classes asdmCasaXMLUtil and asdmCasaSaxHandler are the main objects which 

359 implement the task. The asdmCasaSaxHandler encapsulate all the operations 

360 returning a reference to a CASA::Table. The class uses xerces-c to parse the 

361 XML table and creates the CASA::Table. The implementation assumes the integrity 

362 of the XML data, it not attempting to check whether the XML data meets a 

363 column format or not. In detail, an ArrayString column should agree with 

364 the following format: nd nx ... data, where nd is the number of dimensions, 

365 nx is the size of the first dimension (implemented upto a cube, i.e. nx,ny,nz), 

366 and data is the array itself which should have the appropiate number of 

367 elements. For example, a VectorString column could be: 1 2 "I" "Q" or 

368 dimension 1, size 2, and two string elements. Due to the lack of data type 

369 spefication in the XML tables, the column names are hardcoded into the 

370 asdmCasaSaxHandler based on the ASDM specification (see 

371 http://aramis.obspm.fr/~alma/ASDM/ASDMEntities/index.html). 

372 While missing data from a table column will be accepted by the task, 

373 any new column beyond the specification has to be added into the class, also, 

374 any change in data types form the specificatin will produce a crash, CASA 

375 is picky with data types integrity. So far, the list of tables included in 

376 the class is: 

377  

378 AlmaCorrelatorMode.xml, 

379 Antenna.xml 

380 ConfigDescription.xml, 

381 DataDescription.xml, 

382 ExecBlock.xml, 

383 Feed.xml, 

384 Field.xml, 

385 Main.xml, 

386 Polarization.xml, 

387 Processor.xml, 

388 Receiver.xml, 

389 SBSummary.xml, 

390 Scan.xml, 

391 Source.xml, 

392 SpectralWindow.xml, 

393 State.xml, 

394 Station.xml, 

395 Subscan.xml, 

396 SwitchCycle.xml, 

397 CalCurve.xml, 

398 CalData.xml, 

399 CalPhase.xml 

400  

401 more tables will follow. The usage of fromASDM is simple, it gets two 

402 string, tablename and xmlfile, where tablename is the CASA::Table to be 

403 written and xmlfile represents the ASDM XML table. To call it do: 

404 tb.fromasdm(tablename,xmlfile) 

405 """ 

406 return self._swigobj.fromASDM(tablename, xmlfile) 

407 

408 def resync(self): 

409 """Acquiring a read or write lock automatically synchronizes the internals 

410 of the table tool with the actual contents of the table files. 

411 In this way different processes accessing the same table always 

412 use the same table data. 

413 However, a table can be used without read locking. In that case 

414 the table tool internals are not synchronized automatically. 

415 The resync function offers a way to do explicit synchronization. 

416 It is only useful if the table is opened with locking mode 

417 texttt{autonoread} or texttt{usernoread}. 

418 """ 

419 return self._swigobj.resync() 

420 

421 def close(self): 

422 """First a flush is done, then the table is closed inside casapy and 

423 is no longer available for use. 

424 """ 

425 return self._swigobj.close() 

426 

427 def copy(self, newtablename, deep=False, valuecopy=False, dminfo={ }, endian='aipsrc', memorytable=False, returnobject=False, norows=False): 

428 """Copy the table. All subtables are also copied. 

429 References to another table are preserved. 

430  

431 The argument texttt{deep} determines how a reference table (i.e. the 

432 result of a query) is copied. By default 

433 a file copy is made, thus the resulting table still contains 

434 references and no actual data. If, however, texttt{deep=True} is given, 

435 a deep copy is made which means that the actual data are copied. Also 

436 all subtables are copied. 

437 Normally a plain table is copied by copying the files. However, 

438 if texttt{deep=True} and texttt{valuecopy=True} are given, a plain table is 

439 copied by copying all its values and subtables. This is useful to 

440 reorganize the tables, i.e. to regain file space that is wasted by 

441 frequent updates to a table. 

442 The argument texttt{dminfo} can be used to specify explicit data 

443 manager info for the columns in the new plain table. It can be used to 

444 change, for example, a storage manager from IncrStMan to StandardStMan. 

445 The texttt{dminfo} is a record as returned by the 

446 getdminfo 

447 If texttt{dminfo} is a non-empty record, it forces texttt{valuecopy=True}. 

448  

449 The standard operation is make the copy to a plain table. It is, 

450 however, possible to copy to a memory table by giving texttt{memorytable=True}. 

451  

452 The endian format for the newly created table can be specified. This 

453 is only meaningful if a deep copy is made to a plain table. 

454 The possible values are: 

455 - big: big endian format (as used on e.g. SUN) 

456 - little: little endian format (as used on e.g. PC) 

457 - local: use the endian format of the machine being used 

458 - aipsrc: use the endian format specified in aipsrc variable 

459 table.endianformat (which defaults to big). 

460 The default is aipsrc. 

461  

462 Normally the texttt{copy} function only copies the table and does not 

463 create a new table tool object. The user can do that by opening the newly 

464 created table in the standard way. However, it is possible to get an 

465 object back by using texttt{returnobject=True}. An object is always 

466 returned if the copy is made to a memory table. 

467 """ 

468 return _wrap_table(swig_object=self._swigobj.copy(newtablename, deep, valuecopy, dminfo, endian, memorytable, returnobject, norows)) 

469 

470 def copyrows(self, outtable, startrowin=int(0), startrowout=int(-1), nrow=int(-1)): 

471 """Copy rows from this table to another. By default all rows of this 

472 table are appended to the output table. It is possible though to 

473 control which rows are copied. 

474 Rows are added to the output table as needed. 

475 Because no rows can be added to a reference table, it is only possible 

476 to overwrite existing rows in such tables. 

477  

478 Only the data of columns existing in both tables will be copied. 

479 Thus by making a reference table consisting of a few columns, it 

480 is possible to copy those columns only. 

481 """ 

482 return self._swigobj.copyrows(outtable, startrowin, startrowout, nrow) 

483 

484 def done(self): 

485 """Effectively a synonym for function close. 

486 """ 

487 return self._swigobj.done() 

488 

489 def iswritable(self): 

490 """Test if the table is opened for write. 

491 """ 

492 return self._swigobj.iswritable() 

493 

494 def isopened(self, tablename): 

495 """Test if the table is opened in the process this function is invoked 

496 """ 

497 return self._swigobj.isopened(tablename) 

498 

499 def endianformat(self): 

500 """Get the endian format used for this table. 

501 It returns a string with value 'big' or 'little'. 

502 """ 

503 return self._swigobj.endianformat() 

504 

505 def lock(self, write=True, nattempts=int(0)): 

506 """Try to acquire a read or write lock on the table. Nothing will be 

507 done if the table is already correctly locked by this process. 

508 It is only needed when user locking is used. 

509 When the lock is acquired, the internal caches will be synchronized 

510 with the (possibly changed) contents of the table. 

511 It is possible to specify the number of attempts to do (1 per 

512 second) in case the table is locked by another process. The default 0 

513 is trying indefinitely. 

514 """ 

515 return self._swigobj.lock(write, nattempts) 

516 

517 def unlock(self): 

518 """The table is flushed and the lock on the table is released. 

519 This function is only needed when user locking is used. 

520 However, it is also possible to use it with auto locking. In that case 

521 the lock will automatically be re-acquired before the next table operation. 

522 """ 

523 return self._swigobj.unlock() 

524 

525 def datachanged(self): 

526 """This function tests if data in the table have changed (by another 

527 process) since the last call to this function. 

528 """ 

529 return self._swigobj.datachanged() 

530 

531 def haslock(self, write=True): 

532 """Has this process a read or write lock on the table? 

533 """ 

534 return self._swigobj.haslock(write) 

535 

536 def lockoptions(self): 

537 """Get the lock options used for this table. 

538 It returns a record with the fields: option, interval and maxwait. 

539 The record can be used as the lockoptions argument when opening a table. 

540 """ 

541 return self._swigobj.lockoptions() 

542 

543 def ismultiused(self, checksubtables=False): 

544 """Is the table still in use in another process? 

545 If so, the table cannot be deleted. 

546 """ 

547 return self._swigobj.ismultiused(checksubtables) 

548 

549 def browse(self): 

550 """To start the browser, the environment variable 

551 DISPLAY must be set. 

552 """ 

553 return self._swigobj.browse() 

554 

555 def name(self): 

556 """Gives the name of the casa table on disk that the 

557 table tool has open. 

558 """ 

559 return self._swigobj.name() 

560 

561 def createmultitable(self, outputTableName, tables, subdirname): 

562 """ 

563 """ 

564 return self._swigobj.createmultitable(outputTableName, tables, subdirname) 

565 

566 def toasciifmt(self, asciifile, headerfile='', columns=[ ], sep=''): 

567 """Write a table into an ASCII format approximately compatible with fromascii except that in order to permit variable shaped arrays (as they often occur in MSs), array values are output enclosed in square brackets. 

568 The separator between values can be specified and defaults to a blank. Note that columns containing 

569 invalid data or record type data are ignored and a warning is issued. 

570  

571 If the argument headerfile is set then the header information is 

572 written to that file instead of the first two lines of the data file. 

573 """ 

574 return self._swigobj.toasciifmt(asciifile, headerfile, columns, sep) 

575 

576 def taql(self, taqlcommand='TaQL expression'): 

577 """This method Expose TaQL to the user. 

578 Details on TaQL maybe found at https://casacore.github.io/casacore-notes/199.html 

579 """ 

580 return _wrap_table(swig_object=self._swigobj.taql(taqlcommand)) 

581 

582 def query(self, query='String', name='', sortlist='', columns='', style=''): 

583 """Make a table from a query applied to the current table. It is possible to 

584 specify column(s) and/or expressions to sort on and to specify the 

585 columns to be contained in the output table. See the example below. 

586 A new "on-the-fly" table tool is returned. The new (reference) table 

587 can be given a name and will then be written to disk. Note that the 

588 resulting table is just a reference to the original table. One can 

589 make a deep copy of the query result using the copy function (see example). 

590 """ 

591 return _wrap_table(swig_object=self._swigobj.query(query, name, sortlist, columns, style)) 

592 

593 def calc(self, expr, prefix='using style base0, endincl, fortranorder', showtaql=False): 

594 """Get the result from the calculation of an expression on a table 

595  

596 The expression can be any expression that can be given in the WHERE 

597 clause of a SELECT expression (thus including subqueries). 

598 The given expression determines if the result is a scalar, a vector, 

599 or a record containing arrays. See the examples below. 

600 """ 

601 return self._swigobj.calc(expr, prefix, showtaql) 

602 

603 def selectrows(self, rownrs, name=''): 

604 """Create a (reference) table containing a given subset of rows. 

605 It is, for instance, useful when a selection is done 

606 on another table containing the row numbers in the main table. 

607 It can be useful to apply the casapy function unique to those 

608 row numbers, otherwise the same row might be included multiple 

609 times (see example). 

610  

611  

612  

613 It is possible to give a name to the resulting table. If given, 

614 the resulting table is made persistent with that table name. 

615 Otherwise the table is transient and disappears when closed or when 

616 casapy exits. 

617  

618 The rownumbers function returns a 

619 vector containing the row number in the main table for each row in the 

620 selection table. 

621 Thus given a row number vector texttt{rownrs}, the following is 

622 always true. 

623 begin{verbatim} 

624 rownrs == tb.selectrows(rownrs).rownumbers() 

625 end{verbatim} 

626 However, it is not true when selectrows is used on a selection table. 

627 because texttt{rownumbers} does not return the row number in that 

628 selection table but in the main table. 

629 It means that one has to take great care when using 

630 texttt{selectrows} on a selection table. 

631 """ 

632 return _wrap_table(swig_object=self._swigobj.selectrows(rownrs, name)) 

633 

634 def info(self): 

635 """The info record contains information on the table. 

636 """ 

637 return self._swigobj.info() 

638 

639 def putinfo(self, value): 

640 """The info record contains information on the table. It is 

641 written by applications, and used to determine what type of 

642 information is stored in a table. 

643 """ 

644 return self._swigobj.putinfo(value) 

645 

646 def addreadmeline(self, value): 

647 """A readme line is part of the info record associated with a table. 

648 It is to inform the user, and is not used by any application directly. 

649 """ 

650 return self._swigobj.addreadmeline(value) 

651 

652 def summary(self, recurse=False): 

653 """A (terse) summary of the table contents is sent to the defaultlogger. 

654 """ 

655 return self._swigobj.summary(recurse) 

656 

657 def colnames(self): 

658 """The names of the columns in the table are returned as a vector 

659 of Strings. 

660 """ 

661 return self._swigobj.colnames() 

662 

663 def rownumbers(self, tab={ }, nbytes=int(0)): 

664 """!!!NOTE INPUT PARAMETERS IGNORED!!! 

665  

666 This function can be useful after a selection or a sort. 

667 It returns the row numbers of the rows in this table with respect 

668 to the given table. If no table is given, the original table is used. 

669 For example: 

670 begin {verbatim} 

671 !!!NOTE INPUT PARAMETERS IGNORED!!! 

672  

673 tb.open('3C273XC1.MS') 

674 t1=tb.selectrows([1,3,5,7,9]) 

675 t1.rownumbers() 

676 # [1L, 3L, 5L, 7L, 9L] 

677 t2=t1.selectrows([2,4]) 

678 t2.rownumbers(t1) 

679 # [2L, 4L] 

680 t2.rownumbers(tb.name()) 

681 # [5L, 9L] 

682 t2.rownumbers() 

683 # [5L, 9L] 

684 end{verbatim} 

685 The last statements show that the function returns the row numbers 

686 referring to the given table. Table t2 contains rows 2 and 4 in table t1, 

687 which are rows 5 and 9 in table '3C273XC1.MS'. 

688  

689 Note that when a table is opened using its name, that table can 

690 be a reference table. Thus in the example above 

691 the last 2 statements may give different results depending on the fact 

692 if 3C273XC1.MS is a reference table or not. 

693 The function should always be called with a table argument. 

694 The ability of omitting the argument is only present for backward 

695 compatibility. 

696  

697 The function can be useful to get the correct values from the result of a 

698 getcol or getcolslice on the original table. 

699  

700 !!!NOTE INPUT PARAMETERS IGNORED!!! 

701 """ 

702 return self._swigobj.rownumbers(tab, nbytes) 

703 

704 def setmaxcachesize(self, columnname, nbytes): 

705 """It can sometimes be useful to limit the size of the cache used by 

706 a column stored with the tiled storage manager. 

707 This function requires some more knowledge about the table system 

708 and is not meant for the casual user. 

709 """ 

710 return self._swigobj.setmaxcachesize(columnname, nbytes) 

711 

712 def isscalarcol(self, columnname): 

713 """A column may contain either scalars or arrays in each cell. 

714 This tool function tests if the specified column has scalar contents. 

715 """ 

716 return self._swigobj.isscalarcol(columnname) 

717 

718 def isvarcol(self, columnname): 

719 """This functions tells if the column contains variable shaped arrays. 

720 If so, the function texttt{getvarcol} should be used to get the 

721 entire column. Otherwise texttt{getcol} can be used. 

722 """ 

723 return self._swigobj.isvarcol(columnname) 

724 

725 def coldatatype(self, columnname): 

726 """A column may contain various data types. This tool function returns the 

727 type of the column as a string. 

728 """ 

729 return self._swigobj.coldatatype(columnname) 

730 

731 def colarraytype(self, columnname): 

732 """The possible column array types are defined as: 

733 begin{description} 

734 item[FixedShape] FixedShape means that the shape of the array must be the 

735 same in each cell of the column. If not given, the array 

736 shape may vary. Option Direct forces FixedShape. 

737 item[Direct] Direct means that the data is directly stored in the 

738 table. Direct forces option FixedShape. If not given, the array is 

739 indirect, which implies that the data will be stored in a 

740 separate file. 

741 end{description} 

742 """ 

743 return self._swigobj.colarraytype(columnname) 

744 

745 def ncols(self): 

746 """ 

747 """ 

748 return self._swigobj.ncols() 

749 

750 def nrows(self): 

751 """Note that rows are numbered starting at 0. 

752 """ 

753 return self._swigobj.nrows() 

754 

755 def addrows(self, nrow=int(1)): 

756 """Rows can be added to the end of a table that was opened nomodify=False. 

757 The new rows are empty. 

758 """ 

759 return self._swigobj.addrows(nrow) 

760 

761 def removerows(self, rownrs): 

762 """Remove the row numbers specified in the vector from the table. 

763 It fails when the table does not support row removal. 

764 """ 

765 return self._swigobj.removerows(rownrs) 

766 

767 def addcols(self, desc, dminfo={ }): 

768 """Columns can be added to a table that was opened nomodify=False. 

769 The new columns will be filled with a default value (0 or blank). 

770  

771  

772 !!!THESE COLUMN DESCRIPTION FUNCTIONS HAVE NOT BEEN IMPLEMENTED!!! 

773 For each column to be added a column description has to be setup 

774 using function 

775 tablecreatescalarcoldesc or 

776 tablecreatearraycoldesc. 

777 When multiple columns are used, they have to be combined in a single 

778 record using 

779 tablecreatedesc. 

780 It is possible to specify data manager info in order to define a 

781 data manager (storage manager or virtual column engine) for the 

782 columns to be added. 

783 """ 

784 return self._swigobj.addcols(desc, dminfo) 

785 

786 def renamecol(self, oldname, newname): 

787 """A column can be renamed in a table that was opened nomodify=False. 

788 However, renaming is not possible in a (reference) table resulting 

789 from a select or sort operation. 

790 """ 

791 return self._swigobj.renamecol(oldname, newname) 

792 

793 def removecols(self, columnames): 

794 """Columns can be removed from a table that was opened nomodify=False. 

795 It may not always be possible to remove a column, because some data 

796 managers do not support column removal. However, if all columns of 

797 a data manager are removed, it will always succeed. It results in the 

798 removal of the entire data manager (and its possible files). 

799 Note that function getdminfo 

800 can be used to find which columns are served by which data manager. 

801 """ 

802 return self._swigobj.removecols(columnames) 

803 

804 def iscelldefined(self, columnname, rownr=int(0)): 

805 """A column containing variable shaped arrays can have an empty cell 

806 (if no array has been put into it). This function tests if a cell 

807 is defined (thus is not empty). 

808 Note that a scalar column and a fixed shape array column cannot have 

809 empty cells. 

810 """ 

811 return self._swigobj.iscelldefined(columnname, rownr) 

812 

813 def getcell(self, columnname, rownr=int(0)): 

814 """A cell is the value at one row in one column. It may be a scalar 

815 or an array. 

816 """ 

817 return self._swigobj.getcell(columnname, rownr) 

818 

819 def getcellslice(self, columnname, rownr, blc, trc, incr=[ int(1) ]): 

820 """A cell is the value at one row in one column. It must be an array. 

821 The slice must be specified as blc, trc with an optional stride. 

822 In blc and trc -1 can be used to indicate all values for a dimension 

823 (-1 in blc is equivalent to 0, so -1 is especially useful for trc). 

824 """ 

825 return self._swigobj.getcellslice(columnname, rownr, blc, trc, incr) 

826 

827 def getcol(self, columnname, startrow=int(0), nrow=int(-1), rowincr=int(1)): 

828 """The entire column (or part of it) is returned. Warning: it might be big! 

829 The functions can only be used if all arrays in the column have the 

830 same shape. That is guaranteed for columns containing scalars or fixed 

831 shaped arrays. For columns containing variable shaped arrays it only 

832 succeeds if all those arrays happen to have the same shape. 

833 Note that function texttt{getvarcol} can be used to get a column of 

834 arbitrary shaped arrays, which also handles empty cells correctly. 

835 Function texttt{isvarcol} tells if a column contains variable shaped arrays. 

836 shaped 

837 """ 

838 return self._swigobj.getcol(columnname, startrow, nrow, rowincr) 

839 

840 def getvarcol(self, columnname, startrow=int(0), nrow=int(-1), rowincr=int(1)): 

841 """Function texttt{getcol} can only used if values in the column cells to get 

842 have the same shape. Function texttt{getvarcol} addresses this limitation by 

843 returning the values as a record instead of an array. Each field in 

844 the record contains the value for a column cell. If the value is 

845 undefined (i.e. the cell does not contain a value), the unset value is 

846 put in the record. Each field name is the letter r followed by the 

847 row number. The length of the record is the number of rows to get. 

848 Note that the function texttt{isvarcol} tells if a column contains 

849 variable shaped arrays. 

850 """ 

851 return self._swigobj.getvarcol(columnname, startrow, nrow, rowincr) 

852 

853 def getcolslice(self, columnname, blc, trc, incr, startrow=int(0), nrow=int(-1), rowincr=int(1)): 

854 """A slice from the entire column (or part of it) is returned. 

855 Warning: it might be big! 

856 In blc and trc -1 can be used to indicate all values for a dimension 

857 (-1 in blc is equivalent to 1, so -1 is especially useful for trc). 

858 Note that blc and trc should not contain the row number, only the 

859 blc and trc of the arrays in the column. 

860 """ 

861 return self._swigobj.getcolslice(columnname, blc, trc, incr, startrow, nrow, rowincr) 

862 

863 def getcoliter(self, columnname, startrow=int(0), nrow=int(-1), rowincr=int(1), torecord=False): 

864 """This function returns an iterator that will allow for retrieval of the elements 

865 of one or more table columns (or a subset of the columns). 

866 """ 

867 return self._swigobj.getcoliter(columnname, startrow, nrow, rowincr, torecord) 

868 

869 def putcell(self, columnname, rownr, thevalue=[ ]): 

870 """A cell is the the value at one row in one column. It 

871 may be a scalar or an array. 

872 """ 

873 return self._swigobj.putcell(columnname, rownr, thevalue) 

874 

875 def putcellslice(self, columnname, rownr, value=[ ], blc=[ ], trc=[ ], incr=[ int(1) ]): 

876 """A cell is the value at one row in one column. It must be an array. 

877 The slice must be specified as blc, trc with an optional stride. 

878 In blc and trc -1 can be used to indicate all values for a dimension 

879 (-1 in blc is equivalent to 0, so -1 is especially useful for trc). 

880 """ 

881 return self._swigobj.putcellslice(columnname, rownr, value, blc, trc, incr) 

882 

883 def putcol(self, columnname, value=[ ], startrow=int(0), nrow=int(-1), rowincr=int(1)): 

884 """ 

885 """ 

886 return self._swigobj.putcol(columnname, value, startrow, nrow, rowincr) 

887 

888 def putvarcol(self, columnname, value, startrow=int(0), nrow=int(-1), rowincr=int(1)): 

889 """texttt{putcol} can only used if values in the column cells to put 

890 have the same shape. texttt{putvarcol} addresses this limitation by 

891 passing the values as a record instead of an array. Each field in 

892 the record contains the value for a column cell. So the length of the 

893 record has to match the number of rows to put. If a value is the unset 

894 value, no put is done for that row. 

895 """ 

896 return self._swigobj.putvarcol(columnname, value, startrow, nrow, rowincr) 

897 

898 def putcolslice(self, columnname, value=[ ], blc=[ ], trc=[ ], incr=[ int(1) ], startrow=int(0), nrow=int(-1), rowincr=int(1)): 

899 """In blc and trc, -1 can be used to indicate all values for a dimension 

900 (-1 in blc is equivalent to 0, so -1 is especially useful for trc). 

901 Note that blc and trc should not contain the row number, only the 

902 blc and trc of the arrays in the column. 

903 """ 

904 return self._swigobj.putcolslice(columnname, value, blc, trc, incr, startrow, nrow, rowincr) 

905 

906 def getcolshapestring(self, columnname, startrow=int(0), nrow=int(-1), rowincr=int(1)): 

907 """The shapes of the arrays in the entire column (or part of it) are 

908 returned as strings like [20,3]. When the column contains fixed shaped 

909 arrays, a single string is returned. Otherwise a vector of strings is 

910 returned. 

911 """ 

912 return self._swigobj.getcolshapestring(columnname, startrow, nrow, rowincr) 

913 

914 def getkeyword(self, keyword=[ ]): 

915 """The value of the given table keyword is returned. The value can be of any 

916 type, including a record and a table. 

917 If a keyword is a table, its value is returned as a string containing 

918 the table name prefixed by 'Table: '. 

919 It is possible that the value of a keyword is a record itself 

920 (arbitrarily deeply nested). A field in such a subrecord can be 

921 read by separating the name with dots. 

922 """ 

923 return self._swigobj.getkeyword(keyword) 

924 

925 def getkeywords(self): 

926 """The values of all table keywords are returned. The values can be of any 

927 type, including a record and a table. 

928 If a keyword is a table, its value is returned as a string containing 

929 the table name prefixed by 'Table: '. 

930 """ 

931 return self._swigobj.getkeywords() 

932 

933 def getcolkeyword(self, columnname, keyword=[ ]): 

934 """The value of the given column keyword is returned. The value can be of any 

935 type, including a record and a table. 

936 If a keyword is a table, its value is returned as a string containing 

937 the table name prefixed by 'Table: '. 

938 It is possible that the value of a keyword is a record itself 

939 (arbitrarily deeply nested). A field in such a subrecord can be 

940 read by separating the name with dots. 

941 """ 

942 return self._swigobj.getcolkeyword(columnname, keyword) 

943 

944 def getcolkeywords(self, columnname): 

945 """The values of all keywords for the given column are returned. 

946 The values can be of any type, including a record and a table. 

947 If a keyword is a table, its value is returned as a string containing 

948 the table name prefixed by 'Table: '. 

949 """ 

950 return self._swigobj.getcolkeywords(columnname) 

951 

952 def putkeyword(self, keyword=[ ], value=[ ], makesubrecord=False): 

953 """Put a table keyword. The value of the keyword can be a scalar or 

954 an array of any type or it can be a record. 

955 It is possible to define a keyword holding a subtable. In that 

956 case a special string containing the name of the subtable will be 

957 passed to the table client. 

958 It is possible that the value of a keyword is a record itself 

959 (arbitrarily deeply nested). A field in such a subrecord can be 

960 written by separating the name with dots. If a subrecord does not 

961 exist, an error is returned unless texttt{makesubrecord=True} is given. 

962 In such a case intermediate records are created when needed. 

963 """ 

964 return self._swigobj.putkeyword(keyword, value, makesubrecord) 

965 

966 def putkeywords(self, value): 

967 """Put multiple table keywords. All fields in the given record are put 

968 as table keywords. The value of each field can be a scalar or 

969 an array of any type or it can be a record. 

970 It is also possible to define a keyword holding a subtable. 

971 This can be done by giving the keyword a string value consisting of 

972 the subtable name prefixed by 'Table: '. 

973 """ 

974 return self._swigobj.putkeywords(value) 

975 

976 def putcolkeyword(self, columnname, keyword=[ ], value=[ ]): 

977 """Put a keyword in the given column. 

978 The value of the keyword can be a scalar or 

979 an array of any type or it can be a record. 

980 It is possible to define a keyword holding a subtable. In that 

981 case a special string containing the name of the subtable will be 

982 passed to the table client. 

983 It is possible that the value of a keyword is a record itself 

984 (arbitrarily deeply nested). A field in such a subrecord can be 

985 written by separating the name with dots. If a subrecord does not 

986 exist, an error is returned unless texttt{makesubrecord=True} is given. 

987 In such a case intermediate records are created when needed. 

988 """ 

989 return self._swigobj.putcolkeyword(columnname, keyword, value) 

990 

991 def putcolkeywords(self, columnname, value): 

992 """Put multiple keywords in the given column. 

993 All fields in the given record are put 

994 as column keywords. The value of each field can be a scalar or 

995 an array of any type or it can be a record. 

996 It is also possible to define a keyword holding a subtable. 

997 This can be done by giving the keyword a string value consisting of 

998 the subtable name prefixed by 'Table: '. 

999 """ 

1000 return self._swigobj.putcolkeywords(columnname, value) 

1001 

1002 def removekeyword(self, keyword=[ ]): 

1003 """ 

1004 """ 

1005 return self._swigobj.removekeyword(keyword) 

1006 

1007 def removecolkeyword(self, columnname, keyword=[ ]): 

1008 """ 

1009 """ 

1010 return self._swigobj.removecolkeyword(columnname, keyword) 

1011 

1012 def getdminfo(self): 

1013 """This function returns the types and names of the data managers used.