Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/table.py: 82%
184 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-11-01 07:19 +0000
« prev ^ index » next coverage.py v7.6.4, created at 2024-11-01 07:19 +0000
1##################### generated by xml-casa (v2) from table.xml #####################
2##################### c398d2c9adbb49acd894b261c1ce3ac6 ##############################
3from __future__ import absolute_import
4from .__casac__.table import table as _table
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)
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.
27 Most of the arguments are rarely used: most of the time, you'll
28 just need to use the tablename, and perhaps nomodify.
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.
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.
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'])
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))
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.
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.
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.
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}
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:
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.
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.
186 To give a simple example of the form where the header information
187 is located at the top of the data file:
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.
198 Let us now give an example of a separate header file that one might use to get
199 interferometer data into casa:
201 begin{verbatim}
202 U V W TIME ANT1 ANT2 DATA
203 R R R D I I X1,0
204 end{verbatim}
206 The data file would then look like:
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).
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.
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}
237 Thus to continue the example above, one might wish to add keywords
238 as follows:
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).
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).
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.
270 Also note that ignored comment lines are counted, thus are used to
271 determine which lines are in the line range.
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)
278 def open(self, tablename='', lockoptions={ }, nomodify=True):
279 """Opens a disk file containing an existing casa Table.
281 Most of the time you just need to specify the tablename and perhaps
282 nomodify.
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)
310 def create(self, tablename='', tabledesc={ }, lockoptions={ }, endianformat='', memtype='', nrow=int(0), dminfo={ }):
311 """Create a new casa Table.
313 Most of the time you just need to specify the table's name and a description of
314 its format.
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)
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()
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
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:
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
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)
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()
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()
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.
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}.
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}.
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.
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))
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.
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)
484 def done(self):
485 """Effectively a synonym for function close.
486 """
487 return self._swigobj.done()
489 def iswritable(self):
490 """Test if the table is opened for write.
491 """
492 return self._swigobj.iswritable()
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)
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()
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)
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()
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()
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)
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()
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)
549 def browse(self):
550 """To start the browser, the environment variable
551 DISPLAY must be set.
552 """
553 return self._swigobj.browse()
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()
561 def createmultitable(self, outputTableName, tables, subdirname):
562 """
563 """
564 return self._swigobj.createmultitable(outputTableName, tables, subdirname)
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.
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)
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))
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))
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
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)
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).
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.
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))
634 def info(self):
635 """The info record contains information on the table.
636 """
637 return self._swigobj.info()
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)
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)
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)
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()
663 def rownumbers(self, tab={ }, nbytes=int(0)):
664 """!!!NOTE INPUT PARAMETERS IGNORED!!!
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!!!
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'.
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.
697 The function can be useful to get the correct values from the result of a
698 getcol or getcolslice on the original table.
700 !!!NOTE INPUT PARAMETERS IGNORED!!!
701 """
702 return self._swigobj.rownumbers(tab, nbytes)
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)
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)
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)
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)
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)
745 def ncols(self):
746 """
747 """
748 return self._swigobj.ncols()
750 def nrows(self):
751 """Note that rows are numbered starting at 0.
752 """
753 return self._swigobj.nrows()
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)
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)
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).
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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()
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)
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)
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)
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)
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)
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)
1002 def removekeyword(self, keyword=[ ]):
1003 """
1004 """
1005 return self._swigobj.removekeyword(keyword)
1007 def removecolkeyword(self, columnname, keyword=[ ]):
1008 """
1009 """
1010 return self._swigobj.removecolkeyword(columnname, keyword)
1012 def getdminfo(self):
1013 """This function returns the types and names of the data managers used.
1014 For each data manager it also returns the names of the columns served by it.
1015 The information is returned as a record containing a subrecord for
1016 each data manager. Each subrecord contains the fields TYPE, NAME and
1017 COLUMNS.
1018 """
1019 return self._swigobj.getdminfo()
1021 def keywordnames(self):
1022 """This function returns a vector of strings containing the names
1023 of all table keywords.
1024 """
1025 return self._swigobj.keywordnames()
1027 def fieldnames(self, keyword=''):
1028 """This function returns a vector of strings containing the names
1029 of all fields in the given table keyword.
1030 It is only valid if the keyword value is a record.
1031 If no keyword name is given, the names of all table keywords are returned.
1032 """
1033 return self._swigobj.fieldnames(keyword)
1035 def colkeywordnames(self, columnname):
1036 """This function returns a vector of strings containing the names
1037 of all keywords in the column with the given name..
1038 """
1039 return self._swigobj.colkeywordnames(columnname)
1041 def colfieldnames(self, columnname, keyword=''):
1042 """This function returns a vector of strings containing the names
1043 of all fields in the given keyword in the given column.
1044 It is only valid if the keyword value is a record.
1045 If no keyword name is given, the names of all keywords in the column
1046 are returned.
1047 """
1048 return self._swigobj.colfieldnames(columnname, keyword)
1050 def getdesc(self, actual=True):
1051 """The table description is a casapy record that contains a complete
1052 description of the layout
1053 of the table (except for the number of rows).
1055 By default the actual table description is returned (thus telling the
1056 actual shapes and data managers used). It is also possible to get
1057 the table description used when creating the table.
1058 """
1059 return self._swigobj.getdesc(actual)
1061 def getcoldesc(self, columnname):
1062 """The column description is a casapy record that contains a complete
1063 description of the layout
1064 of a specified column (except for the number of rows). It can be used
1065 to construct a table description.
1066 """
1067 return self._swigobj.getcoldesc(columnname)
1069 def ok(self):
1070 """Perform a number of sanity checks and return T if ok.
1071 Failure (returning F) is a sign of a bug.
1072 """
1073 return self._swigobj.ok()
1075 def clearlocks(self):
1076 """Occasionally a table will be inretrievably locked to another process no matter how much closing is done.
1077 So clearLocks will unlock all the files in the table cache that use AutoLocking.
1078 """
1079 return self._swigobj.clearlocks()
1081 def listlocks(self):
1082 """Occasionally a table will be inretrievably locked to another process no matter how much closing is done.
1083 So listLocks will list the offending tables (and unoffending ones, too), so we can figure out where the problem might be.
1084 """
1085 return self._swigobj.listlocks()
1087 def statistics(self, column, complex_value=''):
1088 """This function computes descriptive statistics on the table column.
1089 It returns the statistical values as a dictionary. The given
1090 column name must be a numerical column.
1091 If it is a complex valued column, the parameter complex_value defines
1092 which derived real value is used for the statistics computation.
1093 This method does not honor any flags in the input table.
1095 """
1096 return self._swigobj.statistics(column, complex_value)
1098 def showcache(self, verbose=True):
1099 """Show the contents of the table cache.
1100 """
1101 return self._swigobj.showcache(verbose)
1103 def testincrstman(self, column):
1104 """Checks consistency of an Incremental Store Manager bucket layout
1106 In case of corruption it returns False and a SEVERE msg is posted containing information about the location of the corrupted bucket
1109 """
1110 return self._swigobj.testincrstman(column)
1112 def row(self, columnnames=[ ], exclude=False):
1113 """Return a table accessor object which allows for accessing one or more rows from the table. A single
1114 row is returned as a dictionary and multiple rows are returned as a list of dictionaries. The contents
1115 of the dictionary by default includes all table columns, but it can be limited by using ``columnnames``
1116 parameter. The ``exclude`` parameter, which is ``False`` by default, indicates whether ``columnnames``
1117 lists the columns to *exclude* (``exclude=True``) or the columns to include (``exclude=False``).
1119 The returned table accessor object can also be used to store changes to a single row using the ``put``
1120 method. This accessor object remains connected to the table object that created it. Closing or deleting
1121 a table object invalidates any accessor objects that it created.
1123 """
1124 return _wrap_tablerow(swig_object=self._swigobj.row(columnnames, exclude))