Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatools/__casac__/table.py: 60%
258 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 19:53 +0000
1# This file was automatically generated by SWIG (http://www.swig.org).
2# Version 3.0.12
3#
4# Do not make changes to this file unless you know what you are doing--modify
5# the SWIG interface file instead.
7from sys import version_info as _swig_python_version_info
8if _swig_python_version_info >= (2, 7, 0):
9 def swig_import_helper():
10 import importlib
11 pkg = __name__.rpartition('.')[0]
12 mname = '.'.join((pkg, '_table')).lstrip('.')
13 try:
14 return importlib.import_module(mname)
15 except ImportError:
16 return importlib.import_module('_table')
17 _table = swig_import_helper()
18 del swig_import_helper
19elif _swig_python_version_info >= (2, 6, 0):
20 def swig_import_helper():
21 from os.path import dirname
22 import imp
23 fp = None
24 try:
25 fp, pathname, description = imp.find_module('_table', [dirname(__file__)])
26 except ImportError:
27 import _table
28 return _table
29 try:
30 _mod = imp.load_module('_table', fp, pathname, description)
31 finally:
32 if fp is not None:
33 fp.close()
34 return _mod
35 _table = swig_import_helper()
36 del swig_import_helper
37else:
38 import _table
39del _swig_python_version_info
41try:
42 _swig_property = property
43except NameError:
44 pass # Python < 2.2 doesn't have 'property'.
46try:
47 import builtins as __builtin__
48except ImportError:
49 import __builtin__
51def _swig_setattr_nondynamic(self, class_type, name, value, static=1):
52 if (name == "thisown"):
53 return self.this.own(value)
54 if (name == "this"):
55 if type(value).__name__ == 'SwigPyObject':
56 self.__dict__[name] = value
57 return
58 method = class_type.__swig_setmethods__.get(name, None)
59 if method:
60 return method(self, value)
61 if (not static):
62 if _newclass:
63 object.__setattr__(self, name, value)
64 else:
65 self.__dict__[name] = value
66 else:
67 raise AttributeError("You cannot add attributes to %s" % self)
70def _swig_setattr(self, class_type, name, value):
71 return _swig_setattr_nondynamic(self, class_type, name, value, 0)
74def _swig_getattr(self, class_type, name):
75 if (name == "thisown"):
76 return self.this.own()
77 method = class_type.__swig_getmethods__.get(name, None)
78 if method:
79 return method(self)
80 raise AttributeError("'%s' object has no attribute '%s'" % (class_type.__name__, name))
83def _swig_repr(self):
84 try:
85 strthis = "proxy of " + self.this.__repr__()
86 except __builtin__.Exception:
87 strthis = ""
88 return "<%s.%s; %s >" % (self.__class__.__module__, self.__class__.__name__, strthis,)
90try:
91 _object = object
92 _newclass = 1
93except __builtin__.Exception:
94 class _object:
95 pass
96 _newclass = 0
98class table(_object):
99 """Proxy of C++ casac::table class."""
101 __swig_setmethods__ = {}
102 __setattr__ = lambda self, name, value: _swig_setattr(self, table, name, value)
103 __swig_getmethods__ = {}
104 __getattr__ = lambda self, name: _swig_getattr(self, table, name)
105 __repr__ = _swig_repr
107 def __init__(self, *args, **kwargs):
108 """__init__(self, _tablename, _lockoptions, _nomodify) -> table"""
109 this = _table.new_table(*args, **kwargs)
110 try:
111 self.this.append(this)
112 except __builtin__.Exception:
113 self.this = this
115 def fromfits(self, *args, **kwargs):
116 """
117 fromfits(self, _tablename, _fitsfile, _whichhdu, _storage, _convention, _nomodify, _ack) -> table
121 Summary:
122 Create a casa table from a binary FITS file
124 Description:
127 Create a table from binary FITS format. This generates a CASA table
128 from the binary FITS table in the given HDU (header unit) of the
129 FITS file. Note that other FITS formats ({em e.g.}
130 Image FITS and UVFITS) are read by other means.
131 It is possible to specify the storage manager to use for the table:
132 texttt{standard} is the default storage manager.
133 texttt{incremental} is efficient for slowly varying data.
134 texttt{memort} is for in memory use for e.g to grab given columns via getcol.
136 Input Parameters:
137 tablename Name of table to be created
138 fitsfile Name of FITS file to be read
139 whichhdu Which HDU to read (0-relative to primary HDU i.e. 1 is the smallest valid value)
140 storage Storage manager to use (standard or incremental or memory)
141 convention Convention to use (sdfits or none)
142 nomodify Open Read-only?
143 ack Acknowledge creations, etc
145 --------------------------------------------------------------------------------
147 """
148 return _table.table_fromfits(self, *args, **kwargs)
151 def fromascii(self, *args, **kwargs):
152 """
153 fromascii(self, _tablename, _asciifile, _headerfile, _autoheader, _autoshape, _sep, _commentmarker, _firstline, _lastline, _nomodify, _columnnames, _datatypes) -> bool
157 Summary:
158 Create a casa table from a file containing data in ASCII format
160 Description:
163 Create a table from an ASCII file. Columnar data as well as
164 table and column keywords may be specified.
165 Once the table is created from the ASCII data, it is opened in the
166 specified mode by the table tool.
168 The table columns are filled from a file containing the data values
169 separated by a separator (one line per table row). The default
170 separator is a blank. Blanks after the separator are ignored.
171 If a non-blank separator is used, values can be empty. Such values
172 default to 0, empty string, or F depending on the data type. E.g.
173 1,,2, has 4 values of which the 2nd and 4th are empty and default to 0.
174 Similarly if fewer values are given than needed, the missing values
175 get the default value.
177 Either the data format can be explicitly specified or it can be found
178 automatically. The former gives more control in ambiguous situations.
179 Both scalar and array columns can be generated from the ASCII input.
180 The format string determines the type and optional shape.
182 In automatic mode (texttt{autoheader=True}) the first line
183 of the ASCII data is analyzed
184 to deduce the data types. Only the types I, D, and A can be
185 recognized. A number without decimal point or exponent is I (integer),
186 otherwise it is D (double). Any other string is A (string).
187 Note that a number may contain a leading sign (+ or -).
188 The texttt{autoshape} argument can be used to specify if the input
189 should be stored as multiple scalars (the default) or as a single
190 array. In the latter case one axis in the shape can be defined as
191 variable length by giving it the value 0. It means that the actual
192 array shape in a row is determined by the number of values in the
193 corresponding input line.
194 Columns get the names texttt{Column1}, texttt{Column2}, etc..
195 For example:
196 begin{enumerate}
197 item
198 texttt{autoshape=[]} (which is the default) means that all values
199 are to be stored as scalar columns.
200 item
201 texttt{autoshape=0} means that all values in a row are to be stored as
202 a variable length vector.
203 item
204 texttt{autoshape=10} defines a fixed length vector. If an input
205 line contains less than 10 values, the vector is filled with default
206 values. If more than 10 values, the latter values are ignored.
207 item
208 texttt{autoshape=[5,0]} defines a 2-dim array of which the 2nd axis is
209 variable. Note that if an input line does not contain a multiple of 5
210 values, the array is filled with default values.
211 end{enumerate}
213 If the format of the table is explicitly specified, it has to be done
214 either in the first two lines of the data file (named by the
215 argument filename), or in a separate header file (named by the
216 argument headerfile). In both forms, table keywords may also be
217 specified before the column definitions.
218 The column names and types can be described by two lines:
220 begin{enumerate}
221 item The first line contains the names of the columns.
222 These names may be enclosed in quotes (either single or double).
223 item The second line contains the data type and optionally the shape
224 of each column. Valid types are:
225 begin{itemize}
226 item S for Short data
227 item I for Integer data
228 item R for Real data
229 item D for Double Precision data
230 item X for Complex data (Real followed by Imaginary)
231 item Z for Complex data (Amplitude then Phase)
232 item DX for Double Precision Complex data (Real followed by Imaginary)
233 item DZ for Double Precision Complex data (Amplitude then Phase)
234 item A for ASCII data (a value must be enclosed in single or double quotes
235 if it contains whitespace)
236 item B for Boolean data (False are empty string, 0, or any string
237 starting with F, f, N, or n).
238 end{itemize}
239 end{enumerate}
240 If a column is an array, the shape has to be given after the data type
241 without any whitespace. E.g. texttt{I10} defines an integer vector
242 of length 10. texttt{A2,5} defines a 2-dim string array with shape
243 [2,5]. Note that texttt{I} is not the same as texttt{I1} as the
244 first one defines a scalar and the other one a vector with length 1.
245 The last column can have one variable length axis denoted by the value
246 0. It 'consumes' the remainder of the input line.
248 If the argument headerfile is set then the header information is
249 read from that file instead of the first lines of the data file.
251 To give a simple example of the form where the header information
252 is located at the top of the data file:
254 begin{verbatim}
255 COLI COLF COLD COLX COLZ COLS
256 I R D X Z A
257 1 1.1 1.11 1.12 1.13 1.14 1.15 Str1
258 10 11 12 13 14 15 16 ''
259 end{verbatim}
260 Note that a complex number consists of 2 numbers.
261 Also note that an empty string can be given.
263 Let us now give an example of a separate header file that one might use to get
264 interferometer data into casa:
266 begin{verbatim}
267 U V W TIME ANT1 ANT2 DATA
268 R R R D I I X1,0
269 end{verbatim}
271 The data file would then look like:
273 begin{verbatim}
274 124.011 54560.0 3477.1 43456789.0990 1 2 4.327 -0.1132
275 34561.0 45629.3 3900.5 43456789.0990 1 3 5.398 0.4521
276 end{verbatim}
277 Note that the DATA column is defined as a 2-dim array of 1
278 correlation and a variable number of channels, so the actual number of
279 channels is determined by the input. In this example both rows will
280 have 1 channel (note that a complex value contains 2 values).
282 Tables may have keywords in addition to the columns. The keywords
283 are useful for holding information that is global to the entire
284 table (such as author, revision, history, {em etc,}).
285 The keywords in the header definitions must preceed the column descriptions.
286 They must be enclosed between a line that starts with '.key...' and
287 a line that starts with '.endkey...' (where ... can be anything).
288 Between these two lines each
289 line should contain the following as listed below.
290 A table keywordset and column keywordsets can be specified.
291 The latter can be specified by specifying the column name after the
292 .keywords string.
294 begin{itemize}
295 item The keyword name, e.g., ANYKEY
296 item The datatype and optional shape of the keyword
297 (cf. list of valid types above)
298 item The value or values for the keyword (the keyword may contain
299 a scalar or an array of values). e.g., 3.14159 21.78945
300 end{itemize}
302 Thus to continue the example above, one might wish to add keywords
303 as follows:
305 begin{verbatim}
306 .keywords
307 DATE A '97/1/16'
308 REVISION D 2.01
309 AUTHOR A 'Tim Cornwell'
310 INSTRUMENT A 'VLA'
311 .endkeywords
312 .keywords TIME
313 UNIT A 's'
314 .endkeywords
315 U V W TIME ANT1 ANT2 DATA
316 R R R D I I X1,0
317 end{verbatim}
318 Similarly to the column format string, the keyword formats can also
319 contain shape information. The only difference is that if no shape is
320 given, a keyword can have multiple values (making it a vector).
322 It is possible to ignore comment lines in the header and data file
323 by giving the texttt{commentmarker}. It indicates that lines
324 starting with the given marker are ignored. Note that the marker can
325 be a regular expression (e.g. texttt{' *//'} tells that lines starting
326 with // and optionally preceeded by blanks have to be ignored).
328 With the arguments texttt{firstline} and texttt{lastline} one can
329 specify which lines have to be taken from the input file. A negative value
330 means 1 for texttt{firstline} or end-of-file for texttt{lastline}.
331 Note that if the headers and data are combined in one file,
332 these line arguments apply to the whole file. If headers and data are in
333 separate files, these line arguments apply to the data file only.
335 Also note that ignored comment lines are counted, thus are used to
336 determine which lines are in the line range.
338 The number of rows is determined by the number of lines read from the data
339 file.
341 Input Parameters:
342 tablename Name of table to be created
343 asciifile Name of ASCII file to be read
344 headerfile Name of an optional file defining the format
345 autoheader Determine header information automatically
346 autoshape Shape to be used if autoheader=True
347 sep Value separator
348 commentmarker Regex indicating comment line
349 firstline First line to use
350 lastline Last line to use
351 nomodify Open Read-only?
352 columnnames Column Names
353 datatypes Data types
355 --------------------------------------------------------------------------------
357 """
358 return _table.table_fromascii(self, *args, **kwargs)
361 def open(self, *args, **kwargs):
362 """
363 open(self, _tablename, _lockoptions, _nomodify) -> bool
367 Summary:
368 open an existing table
370 Description:
373 Opens a disk file containing an existing casa Table.
375 Most of the time you just need to specify the tablename and perhaps
376 nomodify.
378 A table can be shared by multiple processes by using the appropriate
379 locking options. The possible options are:
380 - auto: let the system take care of locking. At regular time
381 intervals these autolocks are released to give other processes the
382 opportunity to access the table.
383 - autonoread: as auto, but no read locking is needed. This must be
384 used with care, because it means that reading can be done while
385 the table tool is not synchronized with the table file (as is
386 normally done when a lock is acquired). The function texttt{resync}
387 can be used to explicitly synchronize the table tool
388 - user: the user takes care by explicit calls to lock and unlock
389 - usernoread: as user and the no readlocking behaviour of autonoread.
390 - permanent: use a permanent lock; the constructor fails when the table is
391 already in use in another process
392 - permanentwait: as above, but wait until the other process
393 releases its lock
394 - default: this is the default option.
395 If the given table is already open, the locking option in use is not
396 changed. Otherwise it reverts to auto.
397 When auto locking is used, it is possible to give a record containing
398 the fields option, interval, and/or maxwait. In this way advanced
399 users have full control over the locking options. In practice this is
400 hardly ever needed.
402 Input Parameters:
403 tablename
404 lockoptions locking dictionary to be used : dict keys are 'option', 'interval', 'maxwait'
405 nomodify
407 Example:
409 # First let's make a table for testing
410 def maketesttable():
411 # Get path to CASA home directory by stipping name from '$CASAPATH'
412 pathname=os.environ.get('CASAPATH').split()[0]
413 # This is where the 3C273XC1.fits data should be
414 fitsdata=pathname+'/data/demo/3C273XC1.fits'
415 # Remove old table if present
416 !rm -rf 3C273XC1.MS
417 ms.fromfits('3C273XC1.MS',fitsdata)
418 ms.close()
420 maketesttable()
421 tb.open('3C273XC1.MS')
422 tb.browse()
423 tb.close()
426 The first line opens an existing table 3C273XC1.MS, the second browses
427 it using the browse function.
430 tb.open('3C273XC1.MS', nomodify=False, lockoptions={'option':'user'})
431 tb.lock();
432 tb.addrows();
433 tb.unlock();
436 In this example explicit user locking is used. The function lock
437 is needed to acquire a (write) lock before the addrows is done.
438 Thereafter the lock is released to give other processes the chance
439 to operate on the table.
440 Note that releasing a lock implies flushing the table, so doing
441 that very often can be quite expensive.
443 --------------------------------------------------------------------------------
445 """
446 return _table.table_open(self, *args, **kwargs)
449 def create(self, *args, **kwargs):
450 """
451 create(self, _tablename, _tabledesc, _lockoptions, _endianformat, _memtype, _nrow, _dminfo) -> bool
455 Summary:
456 create a new table
458 Description:
461 Create a new casa Table.
463 Most of the time you just need to specify the table's name and a description of
464 its format.
466 A table can be shared by multiple processes by using the appropriate
467 locking options. The possible options are:
468 - auto: let the system take care of locking. At regular time
469 intervals these autolocks are released to give other processes the
470 opportunity to access the table.
471 - autonoread: as auto, but no read locking is needed. This must be
472 used with care, because it means that reading can be done while
473 the table tool is not synchronized with the table file (as is
474 normally done when a lock is acquired). The function texttt{resync}
475 can be used to explicitly synchronize the table tool
476 - user: the user takes care by explicit calls to lock and unlock
477 - usernoread: as user and the no readlocking behaviour of autonoread.
478 - permanent: use a permanent lock; the constructor fails when the table is
479 already in use in another process
480 - permanentwait: as above, but wait until the other process
481 releases its lock
482 - default: this is the default option.
483 If the given table is already open, the locking option in use is not
484 changed. Otherwise it reverts to auto.
485 When auto locking is used, it is possible to give a record containing
486 the fields option, interval, and/or maxwait. In this way advanced
487 users have full control over the locking options. In practice this is
488 hardly ever needed.
490 Input Parameters:
491 tablename
492 tabledesc description of the table's format
493 lockoptions locking to be used
494 endianformat
495 memtype
496 nrow
497 dminfo Data Manager information
499 Example:
501 # First let's get sample descriptions of a table and its data managers.
502 import os, shutil
504 def get_tabledesc_and_dminfo(tabname='3C273XC1.MS'):
505 made_copy = False
507 # Fetch new table if tabname not present
508 if not os.path.isdir(tabname):
509 # Get path to CASA root directory by stripping name from '$CASAPATH'
510 pathname = os.environ.get('CASAPATH').split()[0]
512 # There should be some data here
513 fitsdata = pathname + '/data/demo/3C273XC1.fits'
514 tabname = '3C273XC1.MS'
516 ms.fromfits(tabname, fitsdata)
517 ms.close()
518 made_copy = True
520 tb.open(tabname)
521 tabdesc = tb.getdesc()
522 dminfo = tb.getdminfo()
523 print tabname, 'has', tb.nrows(), 'rows.'
524 tb.close()
526 # Clean up
527 if made_copy:
528 shutil.rmtree(tabname)
530 return tabdesc, dminfo
532 tabdesc, dmi = get_tabledesc_and_dminfo()
533 tabdesc # prints tabdesc
534 dmi # prints dmi
536 # You could alter tabdesc and/or dmi at this point.
538 # Unnecessary, but just to show there is nothing up my sleeve...
539 tb.close()
541 tb.create('myempty.ms', tabdesc, dminfo=dmi)
542 tb.nrows() # 0L
543 tb.addrows(5) # Add the rows _before_ filling the columns.
544 tb.putcol('ARRAY_ID', numpy.array([0 for i in range(5)]))
545 tb.putcol('ANTENNA1', numpy.array(range(5)))
546 tb.putcol('ANTENNA2', numpy.array(range(1,6)))
547 tb.browse() # Still mostly, but not completely, empty.
548 tb.close()
551 This creates a CASA table using a description of a table and its data managers from an existing MS.
553 --------------------------------------------------------------------------------
555 """
556 return _table.table_create(self, *args, **kwargs)
559 def flush(self):
560 """
561 flush(self) -> bool
565 Summary:
566 flush the current contents to disk
568 Description:
571 Until a flush is performed, the results of all operations
572 are not reflected in any change to the
573 disk file. Hence you {em must} do a flush to write the changes
574 to disk.
576 --------------------------------------------------------------------------------
578 """
579 return _table.table_flush(self)
582 def fromASDM(self, *args, **kwargs):
583 """
584 fromASDM(self, _tablename, _xmlfile) -> bool
588 Summary:
589 Create an CASA table from an ASDM table
591 Description:
594 .keywords
595 DATE A '07/7/23'
596 REVISION D 0
597 AUTHOR A 'Paulo C. Cortes'
598 INSTRUMENT A 'ALMA'
599 .endkeywords
601 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
602 implement the task. The asdmCasaSaxHandler encapsulate all the operations
603 returning a reference to a CASA::Table. The class uses xerces-c to parse the
604 XML table and creates the CASA::Table. The implementation assumes the integrity
605 of the XML data, it not attempting to check whether the XML data meets a
606 column format or not. In detail, an ArrayString column should agree with
607 the following format: nd nx ... data, where nd is the number of dimensions,
608 nx is the size of the first dimension (implemented upto a cube, i.e. nx,ny,nz),
609 and data is the array itself which should have the appropiate number of
610 elements. For example, a VectorString column could be: 1 2 'I' 'Q' or
611 dimension 1, size 2, and two string elements. Due to the lack of data type
612 spefication in the XML tables, the column names are hardcoded into the
613 asdmCasaSaxHandler based on the ASDM specification (see
614 http://aramis.obspm.fr/~alma/ASDM/ASDMEntities/index.html).
615 While missing data from a table column will be accepted by the task,
616 any new column beyond the specification has to be added into the class, also,
617 any change in data types form the specificatin will produce a crash, CASA
618 is picky with data types integrity. So far, the list of tables included in
619 the class is:
621 AlmaCorrelatorMode.xml,
622 Antenna.xml
623 ConfigDescription.xml,
624 DataDescription.xml,
625 ExecBlock.xml,
626 Feed.xml,
627 Field.xml,
628 Main.xml,
629 Polarization.xml,
630 Processor.xml,
631 Receiver.xml,
632 SBSummary.xml,
633 Scan.xml,
634 Source.xml,
635 SpectralWindow.xml,
636 State.xml,
637 Station.xml,
638 Subscan.xml,
639 SwitchCycle.xml,
640 CalCurve.xml,
641 CalData.xml,
642 CalPhase.xml
644 more tables will follow. The usage of fromASDM is simple, it gets two
645 string, tablename and xmlfile, where tablename is the CASA::Table to be
646 written and xmlfile represents the ASDM XML table. To call it do:
647 tb.fromasdm(tablename,xmlfile)
649 Input Parameters:
650 tablename Name of table to be created
651 xmlfile Name of the XML file to be read
653 --------------------------------------------------------------------------------
655 """
656 return _table.table_fromASDM(self, *args, **kwargs)
659 def resync(self):
660 """
661 resync(self) -> bool
665 Summary:
666 resync the table tool with table file
668 Description:
671 Acquiring a read or write lock automatically synchronizes the internals
672 of the table tool with the actual contents of the table files.
673 In this way different processes accessing the same table always
674 use the same table data.
675 However, a table can be used without read locking. In that case
676 the table tool internals are not synchronized automatically.
677 The resync function offers a way to do explicit synchronization.
678 It is only useful if the table is opened with locking mode
679 texttt{autonoread} or texttt{usernoread}.
681 --------------------------------------------------------------------------------
683 """
684 return _table.table_resync(self)
687 def close(self):
688 """
689 close(self) -> bool
693 Summary:
694 close the table tool
696 Description:
699 First a flush is done, then the table is closed inside casapy and
700 is no longer available for use.
702 --------------------------------------------------------------------------------
704 """
705 return _table.table_close(self)
708 def copy(self, *args, **kwargs):
709 """
710 copy(self, _newtablename, _deep, _valuecopy, _dminfo, _endian, _memorytable, _returnobject, _norows) -> table
714 Summary:
715 copy a table
717 Description:
720 Copy the table. All subtables are also copied.
721 References to another table are preserved.
723 The argument texttt{deep} determines how a reference table (i.e. the
724 result of a query) is copied. By default
725 a file copy is made, thus the resulting table still contains
726 references and no actual data. If, however, texttt{deep=True} is given,
727 a deep copy is made which means that the actual data are copied. Also
728 all subtables are copied.
729 Normally a plain table is copied by copying the files. However,
730 if texttt{deep=True} and texttt{valuecopy=True} are given, a plain table is
731 copied by copying all its values and subtables. This is useful to
732 reorganize the tables, i.e. to regain file space that is wasted by
733 frequent updates to a table.
734 The argument texttt{dminfo} can be used to specify explicit data
735 manager info for the columns in the new plain table. It can be used to
736 change, for example, a storage manager from IncrStMan to StandardStMan.
737 The texttt{dminfo} is a record as returned by the
738 getdminfo
739 If texttt{dminfo} is a non-empty record, it forces texttt{valuecopy=True}.
741 The standard operation is make the copy to a plain table. It is,
742 however, possible to copy to a memory table by giving texttt{memorytable=True}.
744 The endian format for the newly created table can be specified. This
745 is only meaningful if a deep copy is made to a plain table.
746 The possible values are:
747 - big: big endian format (as used on e.g. SUN)
748 - little: little endian format (as used on e.g. PC)
749 - local: use the endian format of the machine being used
750 - aipsrc: use the endian format specified in aipsrc variable
751 table.endianformat (which defaults to big).
752 The default is aipsrc.
754 Normally the texttt{copy} function only copies the table and does not
755 create a new table tool object. The user can do that by opening the newly
756 created table in the standard way. However, it is possible to get an
757 object back by using texttt{returnobject=True}. An object is always
758 returned if the copy is made to a memory table.
760 Input Parameters:
761 newtablename Name of newtable on disk
762 deep Make a deep copy of a reference table?
763 valuecopy Make a deep copy of any table?
764 dminfo Data manager info for new table
765 endian Endian format of new table
766 memorytable Hold new table in memory?
767 returnobject Return a tool object for the new table
768 norows Don't copy any rows (useful for copying only the table structure)
770 --------------------------------------------------------------------------------
772 """
773 return _table.table_copy(self, *args, **kwargs)
776 def copyrows(self, *args, **kwargs):
777 """
778 copyrows(self, _outtable, _startrowin, _startrowout, _nrow) -> bool
782 Summary:
783 copy rows from this table to another
785 Description:
788 Copy rows from this table to another. By default all rows of this
789 table are appended to the output table. It is possible though to
790 control which rows are copied.
791 Rows are added to the output table as needed.
792 Because no rows can be added to a reference table, it is only possible
793 to overwrite existing rows in such tables.
795 Only the data of columns existing in both tables will be copied.
796 Thus by making a reference table consisting of a few columns, it
797 is possible to copy those columns only.
799 Input Parameters:
800 outtable table object of output table
801 startrowin First row to take from input table
802 startrowout First row to write in output table, -1 (=end)
803 nrow Nr of rows to copy, -1 (=all)
805 Example:
807 This example appends rows to the table itself, thus doubles the number
808 of rows.
810 tb.open('3C273XC1.MS',nomodify=False)
811 tb.copyrows('3C273XC1.MS')
812 tb.close()
814 This example copies 10 rows of the selected subset of the MS to the
815 beginning of the output MS.
817 !rm -rf in.MS out.MS
818 ms.fromfits('in.MS','3C273XC1.fits') #Make two MSs
819 ms.fromfits('out.MS','3C273XC1.fits') #for example
820 ms.close()
821 tb.open('in.MS')
822 t1 = tb.query('ANTENNA1==0')
823 tb.close()
824 t1.copyrows('out.MS',nrow=10,startrowout=0)
825 t1.close()
827 --------------------------------------------------------------------------------
829 """
830 return _table.table_copyrows(self, *args, **kwargs)
833 def done(self):
834 """
835 done(self) -> bool
839 Summary:
840 end the table tool
842 Description:
845 Effectively a synonym for function close.
847 --------------------------------------------------------------------------------
849 """
850 return _table.table_done(self)
853 def iswritable(self):
854 """
855 iswritable(self) -> bool
859 Summary:
860 is the table writable?
862 Description:
865 Test if the table is opened for write.
867 --------------------------------------------------------------------------------
869 """
870 return _table.table_iswritable(self)
873 def isopened(self, *args, **kwargs):
874 """
875 isopened(self, _tablename) -> bool
879 Summary:
880 Is the table name open in this process
882 Description:
885 Test if the table is opened in the process this function is invoked
887 Input Parameters:
888 tablename table name to see if it is opened
890 --------------------------------------------------------------------------------
892 """
893 return _table.table_isopened(self, *args, **kwargs)
896 def endianformat(self):
897 """
898 endianformat(self) -> string
902 Summary:
903 get the endian format used for this table
905 Description:
908 Get the endian format used for this table.
909 It returns a string with value 'big' or 'little'.
911 --------------------------------------------------------------------------------
913 """
914 return _table.table_endianformat(self)
917 def lock(self, *args, **kwargs):
918 """
919 lock(self, _write, _nattempts) -> bool
923 Summary:
924 acquire a lock on the table
926 Description:
929 Try to acquire a read or write lock on the table. Nothing will be
930 done if the table is already correctly locked by this process.
931 It is only needed when user locking is used.
932 When the lock is acquired, the internal caches will be synchronized
933 with the (possibly changed) contents of the table.
934 It is possible to specify the number of attempts to do (1 per
935 second) in case the table is locked by another process. The default 0
936 is trying indefinitely.
938 Input Parameters:
939 write Write lock? (F=read lock)
940 nattempts Nr of attempts
942 --------------------------------------------------------------------------------
944 """
945 return _table.table_lock(self, *args, **kwargs)
948 def unlock(self):
949 """
950 unlock(self) -> bool
954 Summary:
955 unlock and flush the table
957 Description:
960 The table is flushed and the lock on the table is released.
961 This function is only needed when user locking is used.
962 However, it is also possible to use it with auto locking. In that case
963 the lock will automatically be re-acquired before the next table operation.
965 --------------------------------------------------------------------------------
967 """
968 return _table.table_unlock(self)
971 def datachanged(self):
972 """
973 datachanged(self) -> bool
977 Summary:
978 has data changed in table?
980 Description:
983 This function tests if data in the table have changed (by another
984 process) since the last call to this function.
986 --------------------------------------------------------------------------------
988 """
989 return _table.table_datachanged(self)
992 def haslock(self, *args, **kwargs):
993 """
994 haslock(self, _write) -> bool
998 Summary:
999 has this process a lock on the table?
1001 Description:
1004 Has this process a read or write lock on the table?
1006 Input Parameters:
1007 write Has it a write lock? (F=read lock)
1009 --------------------------------------------------------------------------------
1011 """
1012 return _table.table_haslock(self, *args, **kwargs)
1015 def lockoptions(self):
1016 """
1017 lockoptions(self) -> record *
1021 Summary:
1022 get the lock options used for this table
1024 Description:
1027 Get the lock options used for this table.
1028 It returns a record with the fields: option, interval and maxwait.
1029 The record can be used as the lockoptions argument when opening a table.
1031 --------------------------------------------------------------------------------
1033 """
1034 return _table.table_lockoptions(self)
1037 def ismultiused(self, *args, **kwargs):
1038 """
1039 ismultiused(self, _checksubtables) -> bool
1043 Summary:
1044 is the table in use in another process?
1046 Description:
1049 Is the table still in use in another process?
1050 If so, the table cannot be deleted.
1052 Input Parameters:
1053 checksubtables check if subtables are multiused?)
1055 --------------------------------------------------------------------------------
1057 """
1058 return _table.table_ismultiused(self, *args, **kwargs)
1061 def browse(self):
1062 """
1063 browse(self) -> bool
1067 Summary:
1068 browse a table using a graphical browser
1070 Description:
1073 To start the browser, the environment variable
1074 DISPLAY must be set.
1076 --------------------------------------------------------------------------------
1078 """
1079 return _table.table_browse(self)
1082 def name(self):
1083 """
1084 name(self) -> string
1088 Summary:
1089 return name of table on disk
1091 Description:
1094 Gives the name of the casa table on disk that the
1095 table tool has open.
1097 Example:
1099 tb.open('3C273XC1.MS')
1100 tb.name()
1101 # 3C273XC1.MS
1103 --------------------------------------------------------------------------------
1105 """
1106 return _table.table_name(self)
1109 def createmultitable(self, *args, **kwargs):
1110 """
1111 createmultitable(self, _outputTableName, _tables, _subdirname) -> bool
1115 Summary:
1116 Create a virtually concatenated table
1118 Description:
1123 Input Parameters:
1124 outputTableName name of the concatenated table
1125 tables list of the names of the tables to be concatenated
1126 subdirname optional name of the subdirectory into which the input tables are moved
1128 --------------------------------------------------------------------------------
1130 """
1131 return _table.table_createmultitable(self, *args, **kwargs)
1134 def toasciifmt(self, *args, **kwargs):
1135 """
1136 toasciifmt(self, _asciifile, _headerfile, _columns, _sep) -> bool
1140 Summary:
1141 Write casa table into an ASCII format
1143 Description:
1146 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.
1147 The separator between values can be specified and defaults to a blank. Note that columns containing
1148 invalid data or record type data are ignored and a warning is issued.
1150 If the argument headerfile is set then the header information is
1151 written to that file instead of the first two lines of the data file.
1153 Input Parameters:
1154 asciifile Name of ASCII file to be written
1155 headerfile Name of an optional file defining the format
1156 columns Names of columns to be written, default is all
1157 sep Value separator, default is one blank
1159 Example:
1161 tb.toasciifmt(asciifile='myfile3.dat', headerfile='myfile3.head', columns=['SOURCE_ID', 'NAME', 'PROPER_MOTION'], sep=', ')
1164 will produce a comma separated ASCII output of the three columns 'SOURCE_ID', 'NAME', and 'PROPER_MOTION' in file 'myfile3.dat'
1165 and a format description in 'myfile3.head'.
1168 tb.toasciifmt(asciifile='myfile.dat')
1171 will produce a space separated ASCII output of all table columns into file 'myfile.dat'
1172 with the first two lines containing a format description.
1174 --------------------------------------------------------------------------------
1176 """
1177 return _table.table_toasciifmt(self, *args, **kwargs)
1180 def taql(self, *args, **kwargs):
1181 """
1182 taql(self, _taqlcommand) -> table
1186 Summary:
1187 Make a table from a TaQL command.
1189 Description:
1191 This method Expose TaQL to the user.
1192 Details on TaQL maybe found at https://casacore.github.io/casacore-notes/199.html
1194 Input Parameters:
1195 taqlcommand TaQL expression
1197 Example:
1199 For more information on TaQL see https://casacore.github.io/casacore-notes/199.html
1201 --------------------------------------------------------------------------------
1203 """
1204 return _table.table_taql(self, *args, **kwargs)
1207 def query(self, *args, **kwargs):
1208 """
1209 query(self, _query, _name, _sortlist, _columns, _style) -> table
1213 Summary:
1214 Make a table from a query
1216 Description:
1219 Make a table from a query applied to the current table. It is possible to
1220 specify column(s) and/or expressions to sort on and to specify the
1221 columns to be contained in the output table. See the example below.
1222 A new 'on-the-fly' table tool is returned. The new (reference) table
1223 can be given a name and will then be written to disk. Note that the
1224 resulting table is just a reference to the original table. One can
1225 make a deep copy of the query result using the copy function (see example).
1227 Input Parameters:
1228 query Query string
1229 name Name of resulting reference table
1230 sortlist Sort string (one or more expressions separated by commas)
1231 columns List of column names separated by commas
1232 style How to handle numeric ranges and order axes
1234 Example:
1236 tb.open('3C273XC1.MS')
1237 subt=tb.query('OBSERVATION_ID==0',
1238 sortlist='ARRAY_ID', columns='TIME, DATA, UVW')
1239 print subt.ncols()
1240 # 23
1241 tb.close()
1242 copyt = subt.copy ('3C273XC1_spw1.MS', True)
1243 subt.close()
1244 copyt.close()
1246 From the original table corresponding to the disk file 3C273XC1.MS, only rows
1247 with OBSERVATION_ID equal to 0 are selected and sorted by ARRAY_ID. Only the
1248 columns TIME DATA UVW are written. Thereafter a deep copy of the result is
1249 made. This table query command is equivalent to the Table Query Language
1250 (TaQL) command
1252 SELECT TIME, DATA, UVW
1253 FROM 3C273XC1.MS
1254 WHERE OBSERVATION_ID==0
1255 ORDERBY ARRAY_ID
1257 See https://casacore.github.io/casacore-notes/199.html for an explanation of TaQL.
1259 If 'style' is not blank, 'using style <style> ' is prepended to the
1260 query. See
1261 https://casacore.github.io/casacore-notes/199.html#x1-70002.2 for
1262 an explanation and list of choices for style. The default (glish) style is
1263 1-based, inclusive end, and Fortran ordering. You may prefer python (0-based,
1264 exclusive end, and C order) style.
1266 tb.open('any_data')
1267 tsel = tb.selectrows([0])
1268 print tsel.nrows() # returns 1
1269 tsel = tb.query('ROWNUMBER()==0')
1270 print tsel.nrows() # returns 0
1271 tsel = tb.query('ROWNUMBER()==0', style='python')
1272 print tsel.nrows() # returns 1
1273 tb.close()
1275 Note that style had no effect on the 'OBSERVATION_ID==0' query above.
1278 The sortlist argument can be used to sort in ascending or descending
1279 order (or a mix of them) on one or more columns. Default is ascending.
1280 It is also possible to remove duplicate values using the word
1281 NODUPLICATES at the beginning.
1283 E.g.:
1286 sortlist='TIME desc'
1287 sortlist='noduplicates ANTENNA1,ANTENNA2'
1288 sortlist='ANTENNA1 desc, ANTENNA2 asc'
1289 sortlist='desc ANTENNA1, ANTENNA2, TIME'
1291 --------------------------------------------------------------------------------
1293 """
1294 return _table.table_query(self, *args, **kwargs)
1297 def calc(self, *args, **kwargs):
1298 """
1299 calc(self, _expr, _prefix, _showtaql) -> variant *
1303 Summary:
1304 TaQL expression with calc to calculate an expression on a table
1306 Description:
1311 Get the result from the calculation of an expression on a table
1313 The expression can be any expression that can be given in the WHERE
1314 clause of a SELECT expression (thus including subqueries).
1315 The given expression determines if the result is a scalar, a vector,
1316 or a record containing arrays. See the examples below.
1318 Input Parameters:
1319 expr Expression string
1320 prefix TaQL prefix for style and ordering etc ...check TaQL note 199 for usage
1321 showtaql Show the full taql command used
1323 Example:
1325 tb.calc('[select from ngc5921.ms giving [mean(abs(DATA))]]')
1327 find the mean of the abs of each row of the DATA column of the MeasurementSet ngc5921.ms
1329 returns a (potentially enormous) record where a field contains the
1330 value of the expression for the row with that number. Note that it
1331 returns a record because for each row the expression results in an array.
1332 It should be clear that this example is useless. However, something
1333 like this could be useful for a column with (very) small arrays.
1335 tb.calc('[select from ngc5921.ms.contsub giving [ntrue(FLAG)]]')
1338 returns for each row the number of flags set. The result is a vector,
1339 because for each row the expression results in a scalar.
1342 tb.calc('sum([select from ngc5921.ms.contsub giving [ntrue(FLAG)]])')
1344 returns the total number of flags set in the table (in a single
1345 scalar).
1347 using subrow array
1348 tb.calc('median([select from ngc5921.ms where ANTENNA1==3 && ANTENNA2==5 giving [abs(DATA[0,31])]])')
1350 The above will find the median channel 31 and 0th pol of the requested baseline formed with antennas 3 and 5.
1351 Note that the that the default casa order of arrays is fortran order ...pol axis is before channel axis
1353 tb.calc('median([select from ngc5921.ms where ANTENNA1==3 && ANTENNA2==5 giving [abs(DATA[31, 0])]])', prefix='using style python')
1355 Now the same is as the above but using the python style of axis ordering access
1357 --------------------------------------------------------------------------------
1359 """
1360 return _table.table_calc(self, *args, **kwargs)
1363 def selectrows(self, *args, **kwargs):
1364 """
1365 selectrows(self, _rownrs, _name) -> table
1369 Summary:
1370 Make a table from a selection of rows
1372 Description:
1375 Create a (reference) table containing a given subset of rows.
1376 It is, for instance, useful when a selection is done
1377 on another table containing the row numbers in the main table.
1378 It can be useful to apply the casapy function unique to those
1379 row numbers, otherwise the same row might be included multiple
1380 times (see example).
1384 It is possible to give a name to the resulting table. If given,
1385 the resulting table is made persistent with that table name.
1386 Otherwise the table is transient and disappears when closed or when
1387 casapy exits.
1389 The rownumbers function returns a
1390 vector containing the row number in the main table for each row in the
1391 selection table.
1392 Thus given a row number vector texttt{rownrs}, the following is
1393 always true.
1394 begin{verbatim}
1395 rownrs == tb.selectrows(rownrs).rownumbers()
1396 end{verbatim}
1397 However, it is not true when selectrows is used on a selection table.
1398 because texttt{rownumbers} does not return the row number in that
1399 selection table but in the main table.
1400 It means that one has to take great care when using
1401 texttt{selectrows} on a selection table.
1403 Input Parameters:
1404 rownrs 0-based Row Numbers
1405 name Name of resulting table
1407 Example:
1409 # EXAMPLE NOT VERIFIED SINCE query IS BROKEN
1410 # Do the query on the main table.
1411 tb.open('SOMENAME')
1412 scantable = tb.query(command)
1413 # Get the column containing the 0-based row numbers in the BACKEND table.
1414 # Make the row numbers unique. NEED TO REPLACE GLISH unique FUNCTION HERE!
1415 backrows = unique(scantable.getcol('NS_GBT_BACKEND_ID'))
1416 # Form the table subset of the BACKEND table containing those rows.
1417 tb.close()
1418 tb.open('SOMENAME/GBT_BACKEND')
1419 scanback = tb.selectrows(backrows);
1420 # Do something with that table.
1421 print scanback.nrows();
1423 --------------------------------------------------------------------------------
1425 """
1426 return _table.table_selectrows(self, *args, **kwargs)
1429 def info(self):
1430 """
1431 info(self) -> record *
1435 Summary:
1436 get the info record
1438 Description:
1441 The info record contains information on the table.
1443 --------------------------------------------------------------------------------
1445 """
1446 return _table.table_info(self)
1449 def putinfo(self, *args, **kwargs):
1450 """
1451 putinfo(self, _value) -> bool
1455 Summary:
1456 set the info record
1458 Description:
1461 The info record contains information on the table. It is
1462 written by applications, and used to determine what type of
1463 information is stored in a table.
1465 Input Parameters:
1466 value Info record
1468 --------------------------------------------------------------------------------
1470 """
1471 return _table.table_putinfo(self, *args, **kwargs)
1474 def addreadmeline(self, *args, **kwargs):
1475 """
1476 addreadmeline(self, _value) -> bool
1480 Summary:
1481 add a readme line to the info record
1483 Description:
1486 A readme line is part of the info record associated with a table.
1487 It is to inform the user, and is not used by any application directly.
1489 Input Parameters:
1490 value readme line
1492 --------------------------------------------------------------------------------
1494 """
1495 return _table.table_addreadmeline(self, *args, **kwargs)
1498 def summary(self, *args, **kwargs):
1499 """
1500 summary(self, _recurse) -> bool
1504 Summary:
1505 summarize the contents of the table
1507 Description:
1510 A (terse) summary of the table contents is sent to the defaultlogger.
1512 Input Parameters:
1513 recurse Summarize subtables recursively
1515 Example:
1517 tb.open('tcal')
1518 tb.summary()
1519 # successful nomodify open of table tcal : 9 columns, 11 rows
1520 # Table summary: tcal
1521 # Shape: 9 columns by 11 rows
1522 # Info: [type=Calibration, subType=T Jones, readme=]
1523 # Table keywords: [Type=T Jones, Interval=30, DeltaT=1]
1524 # Columns: StartTime StopTime Gain SolutionOK Fit FitWeight
1525 # iSolutionOK iFit iFitWeight
1527 --------------------------------------------------------------------------------
1529 """
1530 return _table.table_summary(self, *args, **kwargs)
1533 def colnames(self):
1534 """
1535 colnames(self) -> std::vector< std::string >
1539 Summary:
1540 return the names of the columns
1542 Description:
1545 The names of the columns in the table are returned as a vector
1546 of Strings.
1548 Example:
1550 tb.open('tcal')
1551 tb.colnames()
1552 # StartTime StopTime Gain SolutionOK Fit FitWeight iSolutionOK iFit iFitWeight
1554 --------------------------------------------------------------------------------
1556 """
1557 return _table.table_colnames(self)
1560 def rownumbers(self, *args, **kwargs):
1561 """
1562 rownumbers(self, _tab, _nbytes) -> std::vector< long >
1566 Summary:
1567 !!!INPUT PARAMETERS IGNORED!!! return the row numbers in the (reference) table
1569 Description:
1573 !!!NOTE INPUT PARAMETERS IGNORED!!!
1575 This function can be useful after a selection or a sort.
1576 It returns the row numbers of the rows in this table with respect
1577 to the given table. If no table is given, the original table is used.
1578 For example:
1579 begin {verbatim}
1580 !!!NOTE INPUT PARAMETERS IGNORED!!!
1582 tb.open('3C273XC1.MS')
1583 t1=tb.selectrows([1,3,5,7,9])
1584 t1.rownumbers()
1585 # [1L, 3L, 5L, 7L, 9L]
1586 t2=t1.selectrows([2,4])
1587 t2.rownumbers(t1)
1588 # [2L, 4L]
1589 t2.rownumbers(tb.name())
1590 # [5L, 9L]
1591 t2.rownumbers()
1592 # [5L, 9L]
1593 end{verbatim}
1594 The last statements show that the function returns the row numbers
1595 referring to the given table. Table t2 contains rows 2 and 4 in table t1,
1596 which are rows 5 and 9 in table '3C273XC1.MS'.
1598 Note that when a table is opened using its name, that table can
1599 be a reference table. Thus in the example above
1600 the last 2 statements may give different results depending on the fact
1601 if 3C273XC1.MS is a reference table or not.
1602 The function should always be called with a table argument.
1603 The ability of omitting the argument is only present for backward
1604 compatibility.
1606 The function can be useful to get the correct values from the result of a
1607 getcol or getcolslice on the original table.
1609 !!!NOTE INPUT PARAMETERS IGNORED!!!
1611 Input Parameters:
1612 tab Table to which the row numbers refer
1613 nbytes Maximum cache size in bytes
1615 Example:
1617 !!!NOTE INPUT PARAMETERS IGNORED!!!
1618 tb.open('3C273XC1.MS')
1619 tb.nrows()
1620 #7669L
1621 data=tb.getcolslice('DATA', [0,0], [0,0])
1622 data.shape
1623 #(1, 1, 7669)
1624 selt=tb.query('ANTENNA1==1')
1625 selt.nrows()
1626 #544L
1627 print len(selt.rownumbers())
1628 #544L
1630 --------------------------------------------------------------------------------
1632 """
1633 return _table.table_rownumbers(self, *args, **kwargs)
1636 def setmaxcachesize(self, *args, **kwargs):
1637 """
1638 setmaxcachesize(self, _columnname, _nbytes) -> bool
1642 Summary:
1643 set maximum cache size for column in the table
1645 Description:
1648 It can sometimes be useful to limit the size of the cache used by
1649 a column stored with the tiled storage manager.
1650 This function requires some more knowledge about the table system
1651 and is not meant for the casual user.
1653 Input Parameters:
1654 columnname Name of column
1655 nbytes Maximum cache size in bytes
1657 Example:
1659 tb.open('3C273XC1.MS')
1660 tb.nrows()
1661 # 7669L
1662 tb.setmaxcachesize ('DATA', 4*1024*1024);
1663 # True
1665 --------------------------------------------------------------------------------
1667 """
1668 return _table.table_setmaxcachesize(self, *args, **kwargs)
1671 def isscalarcol(self, *args, **kwargs):
1672 """
1673 isscalarcol(self, _columnname) -> bool
1677 Summary:
1678 is the specified column scalar?
1680 Description:
1683 A column may contain either scalars or arrays in each cell.
1684 This tool function tests if the specified column has scalar contents.
1686 Input Parameters:
1687 columnname Name of column
1689 Example:
1691 tb.open('tcal')
1692 tb.isscalarcol('StartTime')
1693 # True
1694 tb.open('tcal')
1695 tb.isscalarcol('Gain')
1696 # False
1698 --------------------------------------------------------------------------------
1700 """
1701 return _table.table_isscalarcol(self, *args, **kwargs)
1704 def isvarcol(self, *args, **kwargs):
1705 """
1706 isvarcol(self, _columnname) -> bool
1710 Summary:
1711 tell if column contains variable shaped arrays
1713 Description:
1716 This functions tells if the column contains variable shaped arrays.
1717 If so, the function texttt{getvarcol} should be used to get the
1718 entire column. Otherwise texttt{getcol} can be used.
1720 Input Parameters:
1721 columnname Name of column
1723 --------------------------------------------------------------------------------
1725 """
1726 return _table.table_isvarcol(self, *args, **kwargs)
1729 def coldatatype(self, *args, **kwargs):
1730 """
1731 coldatatype(self, _columnname) -> string
1735 Summary:
1736 return the column data type
1738 Description:
1741 A column may contain various data types. This tool function returns the
1742 type of the column as a string.
1744 Input Parameters:
1745 columnname Name of column
1747 Example:
1749 tb.open('tcal')
1750 tb.coldatatype('StartTime')
1751 # double
1752 tb.open('tcal')
1753 tb.coldatatype('Gain')
1754 # complex
1756 --------------------------------------------------------------------------------
1758 """
1759 return _table.table_coldatatype(self, *args, **kwargs)
1762 def colarraytype(self, *args, **kwargs):
1763 """
1764 colarraytype(self, _columnname) -> string
1768 Summary:
1769 return the column array type
1771 Description:
1774 The possible column array types are defined as:
1775 begin{description}
1776 item[FixedShape] FixedShape means that the shape of the array must be the
1777 same in each cell of the column. If not given, the array
1778 shape may vary. Option Direct forces FixedShape.
1779 item[Direct] Direct means that the data is directly stored in the
1780 table. Direct forces option FixedShape. If not given, the array is
1781 indirect, which implies that the data will be stored in a
1782 separate file.
1783 end{description}
1785 Input Parameters:
1786 columnname Name of column
1788 Example:
1790 tb.open('tcal')
1791 tb.colarraytype('Gain')
1792 # Direct,FixedShape
1794 --------------------------------------------------------------------------------
1796 """
1797 return _table.table_colarraytype(self, *args, **kwargs)
1800 def ncols(self):
1801 """
1802 ncols(self) -> long
1806 Summary:
1807 return number of columns
1809 Example:
1811 tb.open('3C273XC1.MS')
1812 tb.ncols()
1813 # 23L
1815 --------------------------------------------------------------------------------
1817 """
1818 return _table.table_ncols(self)
1821 def nrows(self):
1822 """
1823 nrows(self) -> long
1827 Summary:
1828 return number of rows
1830 Description:
1833 Note that rows are numbered starting at 0.
1835 Example:
1837 tb.open('3C273XC1.MS')
1838 tb.nrows()
1839 # 7669L
1841 --------------------------------------------------------------------------------
1843 """
1844 return _table.table_nrows(self)
1847 def addrows(self, *args, **kwargs):
1848 """
1849 addrows(self, _nrow) -> bool
1853 Summary:
1854 add a specified number of rows
1856 Description:
1859 Rows can be added to the end of a table that was opened nomodify=False.
1860 The new rows are empty.
1862 Input Parameters:
1863 nrow Number of rows to add
1865 --------------------------------------------------------------------------------
1867 """
1868 return _table.table_addrows(self, *args, **kwargs)
1871 def removerows(self, *args, **kwargs):
1872 """
1873 removerows(self, _rownrs) -> bool
1877 Summary:
1878 remove the specified rows
1880 Description:
1883 Remove the row numbers specified in the vector from the table.
1884 It fails when the table does not support row removal.
1886 Input Parameters:
1887 rownrs Row numbers to remove
1889 --------------------------------------------------------------------------------
1891 """
1892 return _table.table_removerows(self, *args, **kwargs)
1895 def addcols(self, *args, **kwargs):
1896 """
1897 addcols(self, _desc, _dminfo) -> bool
1901 Summary:
1902 !!!REQUIRES COLUMN DESCRIPTION FUNCTIONS THAT HAVE NOT BEEN IMPLEMENTED!!! add one or more columns
1904 Description:
1907 Columns can be added to a table that was opened nomodify=False.
1908 The new columns will be filled with a default value (0 or blank).
1911 !!!THESE COLUMN DESCRIPTION FUNCTIONS HAVE NOT BEEN IMPLEMENTED!!!
1912 For each column to be added a column description has to be setup
1913 using function
1914 tablecreatescalarcoldesc or
1915 tablecreatearraycoldesc.
1916 When multiple columns are used, they have to be combined in a single
1917 record using
1918 tablecreatedesc.
1919 It is possible to specify data manager info in order to define a
1920 data manager (storage manager or virtual column engine) for the
1921 columns to be added.
1923 Input Parameters:
1924 desc Description of one or more columns
1925 dminfo Optional description data manager to use
1927 Example:
1929 !!!REQUIRES COLUMN DESCRIPTION FUNCTIONS THAT HAVE NOT BEEN IMPLEMENTED!!!
1930 tb.open('mytable', nomodify=False)
1931 dc3=tablecreatescalarcoldesc('C3', 'a')
1932 dc4=tablecreatescalarcoldesc('C4', as_float(0))
1933 dc5=tablecreatearraycoldesc('C5', as_double(0), 2, [10,20])
1934 tb.addcols(dc3)
1935 # True
1936 tb.addcols(tablecreatedesc(dc4, dc5))
1937 # True
1939 A single column can be added as such, but multiple columns have
1940 to be combined.
1942 --------------------------------------------------------------------------------
1944 """
1945 return _table.table_addcols(self, *args, **kwargs)
1948 def renamecol(self, *args, **kwargs):
1949 """
1950 renamecol(self, _oldname, _newname) -> bool
1954 Summary:
1955 rename a column
1957 Description:
1960 A column can be renamed in a table that was opened nomodify=False.
1961 However, renaming is not possible in a (reference) table resulting
1962 from a select or sort operation.
1964 Input Parameters:
1965 oldname name of column to be renamed
1966 newname new name of column
1968 Example:
1970 tb.open('3C273XC1.MS', nomodify=False)
1971 tb.renamecol ('DATA', 'DATA2')
1972 # T
1973 print tb.colnames()
1974 tb.renamecol ('DATA2', 'DATA')
1975 # T
1976 print tb.colnames()
1978 Column texttt{DATA} is renamed to texttt{DATA2} and then back to
1979 texttt{DATA} again..
1981 --------------------------------------------------------------------------------
1983 """
1984 return _table.table_renamecol(self, *args, **kwargs)
1987 def removecols(self, *args, **kwargs):
1988 """
1989 removecols(self, _columnames) -> bool
1993 Summary:
1994 remove one or more columns
1996 Description:
1999 Columns can be removed from a table that was opened nomodify=False.
2000 It may not always be possible to remove a column, because some data
2001 managers do not support column removal. However, if all columns of
2002 a data manager are removed, it will always succeed. It results in the
2003 removal of the entire data manager (and its possible files).
2004 Note that function getdminfo
2005 can be used to find which columns are served by which data manager.
2007 Input Parameters:
2008 columnames names of columns to be removed
2010 Example:
2012 tb.open('mytable', nomodify=False)
2013 tb.removecols ('col1 col2')
2014 # T
2015 print tb.colnames()
2017 Two columns are removed.
2019 --------------------------------------------------------------------------------
2021 """
2022 return _table.table_removecols(self, *args, **kwargs)
2025 def iscelldefined(self, *args, **kwargs):
2026 """
2027 iscelldefined(self, _columnname, _rownr) -> bool
2031 Summary:
2032 test if a specific cell contains a value
2034 Description:
2037 A column containing variable shaped arrays can have an empty cell
2038 (if no array has been put into it). This function tests if a cell
2039 is defined (thus is not empty).
2040 Note that a scalar column and a fixed shape array column cannot have
2041 empty cells.
2043 Input Parameters:
2044 columnname Name of column
2045 rownr Row number, starting at 0
2047 --------------------------------------------------------------------------------
2049 """
2050 return _table.table_iscelldefined(self, *args, **kwargs)
2053 def getcell(self, *args, **kwargs):
2054 """
2055 getcell(self, _columnname, _rownr) -> variant *
2059 Summary:
2060 get a specific cell
2062 Description:
2065 A cell is the value at one row in one column. It may be a scalar
2066 or an array.
2068 Input Parameters:
2069 columnname Name of column
2070 rownr Row number, starting at 0
2072 --------------------------------------------------------------------------------
2074 """
2075 return _table.table_getcell(self, *args, **kwargs)
2078 def getcellslice(self, *args, **kwargs):
2079 """
2080 getcellslice(self, _columnname, _rownr, _blc, _trc, _incr) -> variant *
2084 Summary:
2085 get a slice from a specific cell
2087 Description:
2090 A cell is the value at one row in one column. It must be an array.
2091 The slice must be specified as blc, trc with an optional stride.
2092 In blc and trc -1 can be used to indicate all values for a dimension
2093 (-1 in blc is equivalent to 0, so -1 is especially useful for trc).
2095 Input Parameters:
2096 columnname Name of column
2097 rownr Row number, starting at 0
2098 blc Bottom left corner (e.g. [0,0,0] is start of 3D array)
2099 trc Top right corner
2100 incr Stride (defaults to 1 for all axes)
2102 Example:
2104 tb.open('3C273XC1.MS')
2105 data=tb.getcellslice('DATA', 0, [0,0], [1,0])
2106 print data.shape
2107 # [2 1]
2109 --------------------------------------------------------------------------------
2111 """
2112 return _table.table_getcellslice(self, *args, **kwargs)
2115 def getcol(self, *args, **kwargs):
2116 """
2117 getcol(self, _columnname, _startrow, _nrow, _rowincr) -> variant *
2121 Summary:
2122 get a specific column
2124 Description:
2127 The entire column (or part of it) is returned. Warning: it might be big!
2128 The functions can only be used if all arrays in the column have the
2129 same shape. That is guaranteed for columns containing scalars or fixed
2130 shaped arrays. For columns containing variable shaped arrays it only
2131 succeeds if all those arrays happen to have the same shape.
2132 Note that function texttt{getvarcol} can be used to get a column of
2133 arbitrary shaped arrays, which also handles empty cells correctly.
2134 Function texttt{isvarcol} tells if a column contains variable shaped arrays.
2135 shaped
2137 Input Parameters:
2138 columnname Name of column
2139 startrow First row to read (default 0)
2140 nrow Number of rows to read (default -1 means till the end)
2141 rowincr Increment in rows to read (default 1)
2143 Example:
2145 tb.open('3C273XC1.MS')
2146 # True
2147 gain=tb.getcol('DATA')
2148 print gain.shape
2149 # (4, 1, 7669)
2151 --------------------------------------------------------------------------------
2153 """
2154 return _table.table_getcol(self, *args, **kwargs)
2157 def getvarcol(self, *args, **kwargs):
2158 """
2159 getvarcol(self, _columnname, _startrow, _nrow, _rowincr) -> record *
2163 Summary:
2164 get a specific column (for variable arrays)
2166 Description:
2169 Function texttt{getcol} can only used if values in the column cells to get
2170 have the same shape. Function texttt{getvarcol} addresses this limitation by
2171 returning the values as a record instead of an array. Each field in
2172 the record contains the value for a column cell. If the value is
2173 undefined (i.e. the cell does not contain a value), the unset value is
2174 put in the record. Each field name is the letter r followed by the
2175 row number. The length of the record is the number of rows to get.
2176 Note that the function texttt{isvarcol} tells if a column contains
2177 variable shaped arrays.
2179 Input Parameters:
2180 columnname Name of column
2181 startrow First row to read (default 0)
2182 nrow Number of rows to read (default -1 means till the end)
2183 rowincr Increment in rows to read (default 1)
2185 Example:
2187 tb.open('3C273XC1.MS')
2188 gain=tb.getvarcol('DATA')
2189 print len(gain)
2190 # 7669
2192 --------------------------------------------------------------------------------
2194 """
2195 return _table.table_getvarcol(self, *args, **kwargs)
2198 def getcolslice(self, *args, **kwargs):
2199 """
2200 getcolslice(self, _columnname, _blc, _trc, _incr, _startrow, _nrow, _rowincr) -> variant *
2204 Summary:
2205 get a slice from a specific columnarray
2207 Description:
2210 A slice from the entire column (or part of it) is returned.
2211 Warning: it might be big!
2212 In blc and trc -1 can be used to indicate all values for a dimension
2213 (-1 in blc is equivalent to 1, so -1 is especially useful for trc).
2214 Note that blc and trc should not contain the row number, only the
2215 blc and trc of the arrays in the column.
2217 Input Parameters:
2218 columnname Name of column
2219 blc Bottom left corner (e.g. [0,0,0] is start of 3D array)
2220 trc Top right corner
2221 incr Stride (defaults to 1 for all axes)
2222 startrow First row to read (default 0)
2223 nrow Number of rows to read (default -1 means till the end)
2224 rowincr Increment in rows to read (default 1)
2226 Example:
2228 tb.open('3C273XC1.MS')
2229 data=tb.getcolslice('DATA', [0,0], [1,0])
2230 data.shape
2231 # (2 1 7669)
2233 --------------------------------------------------------------------------------
2235 """
2236 return _table.table_getcolslice(self, *args, **kwargs)
2239 def getcoliter(self, *args, **kwargs):
2240 """
2241 getcoliter(self, _columnname, _startrow, _nrow, _rowincr, _torecord) -> PyObj *
2245 Summary:
2246 get an iterator for a specific column
2248 Description:
2251 This function returns an iterator that will allow for retrieval of the elements
2252 of one or more table columns (or a subset of the columns).
2254 Input Parameters:
2255 columnname Name of column
2256 startrow First row to read (default 0)
2257 nrow Total number of rows to return (default -1 means till the end)
2258 rowincr Increment in rows to read (default 1)
2259 torecord when more than one column is retrieved use a dictionary to return the value (default False)
2261 Example:
2263 This example creates an iterator which returns tuples made up of the
2264 values from the TIME column and the EXPOSURE column. It will return
2265 these tuples one at a time, but it will stop after returning five
2266 tuples. It starts at row zero and skips 999 rows to get to the row
2267 used to return the next tuple.
2269 for i in tb.getcoliter(['TIME','EXPOSURE'],startrow=0,nrow=5,rowincr=1000):
2270 print(i)
2273 This example has the same iteration behavior but instead of returning
2274 tuples it returns records containing two key/value pairs, TIME and
2275 EXPOSURE.
2277 for i in tb.getcoliter(['TIME','EXPOSURE'],startrow=0,nrow=5,rowincr=1000,torecord=True):
2278 print(i)
2281 This example shows how getcoliter can be used to load table columns
2282 into a Pandas dataframe.
2284 pd = pandas.DataFrame.from_records(tb.getcoliter(['TIME','DATA'],torecord=True))
2287 This example shows how to use getcoliter to load table columns into
2288 a Dask dataframe by concatenating Pandas dataframes. This creates
2289 chunking based upon the number of rows returned by getcoliter.
2291 import math
2292 import pandas as pd
2293 from dask import delayed, compute
2294 import dask.dataframe as dd
2295 from functools import reduce
2296 from casatools import table
2298 tbx = table(expanduser('2018.1.00879.S_tclean.ms'))
2299 part_start = range( 0, tbx.nrows( ), math.ceil(tbx.nrows( ) / 500) )
2300 part = reduce( lambda acc, x: acc+[(x, math.ceil(tbx.nrows( ) / 500) if x + math.ceil(tbx.nrows( ) / 500) < tbx.nrows() else tbx.nrows()-x)],
2301 part_start, [] )
2302 lst = [delayed(lambda x: pd.DataFrame(table('2018.1.00879.S_tclean.ms').getcoliter(['TIME','DATA'],*x,torecord=True)))(l) for l in part]
2303 df = dd.concat(compute(lst)[0]
2305 If you looked at the elements part and lst you would find:
2307 In [5]: part[:5]
2308 Out[5]: [(0, 632), (632, 632), (1264, 632), (1896, 632), (2528, 632)]
2310 In [6]: lst[:5]
2311 Out[6]:
2312 [Delayed('lambda-af8d8b10-9526-4988-ac7c-8e8e5cd99934'),
2313 Delayed('lambda-b9035365-a074-42ce-b04e-2881179f573a'),
2314 Delayed('lambda-d44d97d8-b6ce-4d6e-a6e0-4326bdfabf01'),
2315 Delayed('lambda-c84f7ed8-af6c-4efc-a225-437353fc1393'),
2316 Delayed('lambda-8fa0e6cb-01c3-4433-acf0-e3e9b8d26a35')]
2318 The Dask dataframe is df, but it is not completely evaluated:
2320 In [7]: df
2321 Out[7]:
2322 Dask DataFrame Structure:
2323 TIME DATA
2324 npartitions=500
2325 object object
2326 ... ...
2327 ... ... ...
2328 ... ...
2329 ... ...
2330 Dask Name: concat, 501 graph layers
2332 Evaluating again resolves the contents of the dataframe:
2334 In [8]: df = df.compute()
2336 In [9]: df
2337 Out[9]:
2338 TIME DATA
2339 0 [5053663310.208] [[[(19.649103+0j)], [(19.62976+0j)], [(19.6710...
2340 1 [5053663310.208] [[[(16.316814+0j)], [(16.301018+0j)], [(16.321...
2341 2 [5053663310.208] [[[(15.963612+0j)], [(15.9756+0j)], [(15.98898...
2342 3 [5053663310.208] [[[(17.416065+0j)], [(17.409616+0j)], [(17.393...
2343 4 [5053663310.208] [[[(20.466146+0j)], [(20.48779+0j)], [(20.5097...
2344 .. ... ...
2345 467 [5053664322.4800005] [[[(-0.8585681-0.7359103j)], [(0.8410164+1.934...
2346 468 [5053664322.4800005] [[[(-29.532145-12.631435j)], [(-27.726702-11.6...
2347 469 [5053664322.4800005] [[[(-1.8737663-0.93042445j)], [(-0.79967415-1....
2348 470 [5053664322.4800005] [[[(-1.6989801-1.1293286j)], [(-2.898021-1.001...
2349 471 [5053664322.4800005] [[[(0.22554477+3.4367344j)], [(-2.8623238+1.58...
2351 [315840 rows x 2 columns]
2353 --------------------------------------------------------------------------------
2355 """
2356 return _table.table_getcoliter(self, *args, **kwargs)
2359 def putcell(self, *args, **kwargs):
2360 """
2361 putcell(self, _columnname, _rownr, _thevalue) -> bool
2365 Summary:
2366 put a specific cell
2368 Description:
2371 A cell is the the value at one row in one column. It
2372 may be a scalar or an array.
2374 Input Parameters:
2375 columnname Name of column
2376 rownr Row number(s) (0-relative)
2377 thevalue Value
2379 --------------------------------------------------------------------------------
2381 """
2382 return _table.table_putcell(self, *args, **kwargs)
2385 def putcellslice(self, *args, **kwargs):
2386 """
2387 putcellslice(self, _columnname, _rownr, _value, _blc, _trc, _incr) -> bool
2391 Summary:
2392 put a slice into a specific cell
2394 Description:
2397 A cell is the value at one row in one column. It must be an array.
2398 The slice must be specified as blc, trc with an optional stride.
2399 In blc and trc -1 can be used to indicate all values for a dimension
2400 (-1 in blc is equivalent to 0, so -1 is especially useful for trc).
2402 Input Parameters:
2403 columnname Name of column
2404 rownr Row number, starting at 0
2405 value Value
2406 blc Bottom left corner (e.g. [0,0,0] is start of 3D array)
2407 trc Top right corner
2408 incr Stride (defaults to 1 for all axes)
2410 --------------------------------------------------------------------------------
2412 """
2413 return _table.table_putcellslice(self, *args, **kwargs)
2416 def putcol(self, *args, **kwargs):
2417 """
2418 putcol(self, _columnname, _value, _startrow, _nrow, _rowincr) -> bool
2422 Summary:
2423 put a specific column
2425 Input Parameters:
2426 columnname Name of column
2427 value Array
2428 startrow First row to put (default 0)
2429 nrow Number of rows to put (default -1 means till the end)
2430 rowincr Increment in rows to put (default 1)
2432 Example:
2434 tb.open('3C273XC1.MS',nomodify=False)
2435 data=tb.getcol('DATA')
2436 # [could modify data here]
2437 tb.putcol('DATA', data)
2438 tb.flush()
2440 --------------------------------------------------------------------------------
2442 """
2443 return _table.table_putcol(self, *args, **kwargs)
2446 def putvarcol(self, *args, **kwargs):
2447 """
2448 putvarcol(self, _columnname, _value, _startrow, _nrow, _rowincr) -> bool
2452 Summary:
2453 put a specific column (for variable arrays)
2455 Description:
2458 texttt{putcol} can only used if values in the column cells to put
2459 have the same shape. texttt{putvarcol} addresses this limitation by
2460 passing the values as a record instead of an array. Each field in
2461 the record contains the value for a column cell. So the length of the
2462 record has to match the number of rows to put. If a value is the unset
2463 value, no put is done for that row.
2465 Input Parameters:
2466 columnname Name of column
2467 value Record with values
2468 startrow First row to put (default 0)
2469 nrow Number of rows to put (default -1 means till the end)
2470 rowincr Increment in rows to put (default 1)
2472 Example:
2474 tb.open('3C273XC1.MS',nomodify=False)
2475 gain=tb.getvarcol('DATA', 0, 10)
2476 tb.putvarcol('Gain', gain, 10, 10)
2477 tb.flush()
2479 This example copies the values from row 0-9 to row 10-19.
2481 --------------------------------------------------------------------------------
2483 """
2484 return _table.table_putvarcol(self, *args, **kwargs)
2487 def putcolslice(self, *args, **kwargs):
2488 """
2489 putcolslice(self, _columnname, _value, _blc, _trc, _incr, _startrow, _nrow, _rowincr) -> bool
2493 Summary:
2494 put a slice into a specific column
2496 Description:
2499 In blc and trc, -1 can be used to indicate all values for a dimension
2500 (-1 in blc is equivalent to 0, so -1 is especially useful for trc).
2501 Note that blc and trc should not contain the row number, only the
2502 blc and trc of the arrays in the column.
2504 Input Parameters:
2505 columnname Name of column
2506 value Array
2507 blc Bottom left corner (e.g. [0,0,0] is start of 3D array)
2508 trc Top right corner
2509 incr Stride (defaults to 1 for all axes)
2510 startrow First row to put (default 0)
2511 nrow Number of rows to put (default -1 means till the end)
2512 rowincr Increment in rows to put (default 1)
2514 Example:
2516 tb.open('3C273XC1.MS',nomodify=False)
2517 data_all=tb.getcolslice('DATA', [-1,-1], [-1,=1])
2518 print data_all.shape
2519 # (4, 1, 7669)
2520 data=tb.getcolslice('DATA', [0,0],[3,0])
2521 # can modify data here
2522 tb.putcolslice('DATA', data, [0,0],[3,0])
2523 tb.flush()
2525 --------------------------------------------------------------------------------
2527 """
2528 return _table.table_putcolslice(self, *args, **kwargs)
2531 def getcolshapestring(self, *args, **kwargs):
2532 """
2533 getcolshapestring(self, _columnname, _startrow, _nrow, _rowincr) -> std::vector< std::string >
2537 Summary:
2538 get shape of arrays in a specific column
2540 Description:
2543 The shapes of the arrays in the entire column (or part of it) are
2544 returned as strings like [20,3]. When the column contains fixed shaped
2545 arrays, a single string is returned. Otherwise a vector of strings is
2546 returned.
2548 Input Parameters:
2549 columnname Name of column
2550 startrow First row to read (default 0)
2551 nrow Number of rows to read (default -1 means till the end)
2552 rowincr Increment in rows to read (default 1)
2554 Example:
2556 tb.open('3C273XC1.MS')
2557 shapes=tb.getcolshapestring('DATA'))
2558 print len(shapes)
2560 --------------------------------------------------------------------------------
2562 """
2563 return _table.table_getcolshapestring(self, *args, **kwargs)
2566 def getkeyword(self, *args, **kwargs):
2567 """
2568 getkeyword(self, _keyword) -> variant *
2572 Summary:
2573 get value of specific table keyword
2575 Description:
2578 The value of the given table keyword is returned. The value can be of any
2579 type, including a record and a table.
2580 If a keyword is a table, its value is returned as a string containing
2581 the table name prefixed by 'Table: '.
2582 It is possible that the value of a keyword is a record itself
2583 (arbitrarily deeply nested). A field in such a subrecord can be
2584 read by separating the name with dots.
2586 Input Parameters:
2587 keyword Name or seqnr of keyword: string or int
2589 Example:
2591 tb.open('3C273XC1.MS')
2592 tb.getkeywords()
2593 tb.getkeyword('MS_VERSION')
2594 # 2.0
2595 tb.close()
2596 tb.open('tcal')
2597 tb.getkeyword('rec.fld') # get field from a record
2598 # 3.14
2600 --------------------------------------------------------------------------------
2602 """
2603 return _table.table_getkeyword(self, *args, **kwargs)
2606 def getkeywords(self):
2607 """
2608 getkeywords(self) -> record *
2612 Summary:
2613 get values of all table keywords
2615 Description:
2618 The values of all table keywords are returned. The values can be of any
2619 type, including a record and a table.
2620 If a keyword is a table, its value is returned as a string containing
2621 the table name prefixed by 'Table: '.
2623 Example:
2625 tb.open('3C273XC1.MS')
2626 tb.getkeywords()
2627 #{'ANTENNA': 'Table: /home/aips2mgr/testing/3C273XC1.MS/ANTENNA',
2628 # 'DATA_DESCRIPTION': 'Table: /home/aips2mgr/testing/3C273XC1.MS/DATA_DESCRIPTION',
2629 # 'FEED': 'Table: /home/aips2mgr/testing/3C273XC1.MS/FEED',
2630 # 'FIELD': 'Table: /home/aips2mgr/testing/3C273XC1.MS/FIELD',
2631 # 'FLAG_CMD': 'Table: /home/aips2mgr/testing/3C273XC1.MS/FLAG_CMD',
2632 # 'HISTORY': 'Table: /home/aips2mgr/testing/3C273XC1.MS/HISTORY',
2633 # 'MS_VERSION': 2.0,
2634 # 'OBSERVATION': 'Table: /home/aips2mgr/testing/3C273XC1.MS/OBSERVATION',
2635 # 'POINTING': 'Table: /home/aips2mgr/testing/3C273XC1.MS/POINTING',
2636 # 'POLARIZATION': 'Table: /home/aips2mgr/testing/3C273XC1.MS/POLARIZATION',
2637 # 'PROCESSOR': 'Table: /home/aips2mgr/testing/3C273XC1.MS/PROCESSOR',
2638 # 'SOURCE': 'Table: /home/aips2mgr/testing/3C273XC1.MS/SOURCE',
2639 # 'SPECTRAL_WINDOW': 'Table: /home/aips2mgr/testing/3C273XC1.MS/SPECTRAL_WINDOW',
2640 # 'STATE': 'Table: /home/aips2mgr/testing/3C273XC1.MS/STATE'}
2642 --------------------------------------------------------------------------------
2644 """
2645 return _table.table_getkeywords(self)
2648 def getcolkeyword(self, *args, **kwargs):
2649 """
2650 getcolkeyword(self, _columnname, _keyword) -> variant *
2654 Summary:
2655 get value of specific column keyword
2657 Description:
2660 The value of the given column keyword is returned. The value can be of any
2661 type, including a record and a table.
2662 If a keyword is a table, its value is returned as a string containing
2663 the table name prefixed by 'Table: '.
2664 It is possible that the value of a keyword is a record itself
2665 (arbitrarily deeply nested). A field in such a subrecord can be
2666 read by separating the name with dots.
2668 Input Parameters:
2669 columnname Name of column
2670 keyword Name or seqnr of keyword: string or int
2672 Example:
2674 tb.open('3C273XC1.MS')
2675 tb.getcolkeyword('UVW', 'QuantumUnits')
2676 #array(['m', 'm', 'm'],
2677 # dtype='|S2')
2679 --------------------------------------------------------------------------------
2681 """
2682 return _table.table_getcolkeyword(self, *args, **kwargs)
2685 def getcolkeywords(self, *args, **kwargs):
2686 """
2687 getcolkeywords(self, _columnname) -> variant *
2691 Summary:
2692 get values of all keywords for a column
2694 Description:
2697 The values of all keywords for the given column are returned.
2698 The values can be of any type, including a record and a table.
2699 If a keyword is a table, its value is returned as a string containing
2700 the table name prefixed by 'Table: '.
2702 Input Parameters:
2703 columnname Name of column
2705 Example:
2707 tb.open('3C273XC1.MS')
2708 tb.getcolkeywords('UVW')
2709 #{'MEASINFO': {'Ref': 'ITRF', 'type': 'uvw'},
2710 # 'QuantumUnits': array(['m', 'm', 'm'],
2711 # dtype='|S2')}
2713 --------------------------------------------------------------------------------
2715 """
2716 return _table.table_getcolkeywords(self, *args, **kwargs)
2719 def putkeyword(self, *args, **kwargs):
2720 """
2721 putkeyword(self, _keyword, _value, _makesubrecord) -> bool
2725 Summary:
2726 put a specific table keyword
2728 Description:
2731 Put a table keyword. The value of the keyword can be a scalar or
2732 an array of any type or it can be a record.
2733 It is possible to define a keyword holding a subtable. In that
2734 case a special string containing the name of the subtable will be
2735 passed to the table client.
2736 It is possible that the value of a keyword is a record itself
2737 (arbitrarily deeply nested). A field in such a subrecord can be
2738 written by separating the name with dots. If a subrecord does not
2739 exist, an error is returned unless texttt{makesubrecord=True} is given.
2740 In such a case intermediate records are created when needed.
2742 Input Parameters:
2743 keyword Name or seqnr of keyword: string or int
2744 value Value of keyword
2745 makesubrecord Create intermediate records
2747 Example:
2749 tb.open('3C273XC1.MS', nomodify=False)
2750 tb.putkeyword('VERSION', '1.66')
2751 # True
2752 # define ANTENNA subtable
2753 tb.putkeyword('ANTENNA', 'Table: 3C273XC1.MS/ANTENNA')
2754 tb.flush()
2755 # True
2756 # write a field in a record and create subrecords when needed
2757 tb.putkeyword('REC.SUB.FLD', 'val', True)
2758 # True
2759 # write a keyword with a record value
2760 tb.putkeyword('REC', {'SUB': {'FLD': 'val'}})
2761 # True
2763 Note that the last example does the same as the previous one (assuming
2764 that texttt{REC} does not exist yet with other fields).
2766 --------------------------------------------------------------------------------
2768 """
2769 return _table.table_putkeyword(self, *args, **kwargs)
2772 def putkeywords(self, *args, **kwargs):
2773 """
2774 putkeywords(self, _value) -> bool
2778 Summary:
2779 !!!BROKEN!!! put multiple table keywords
2781 Description:
2784 Put multiple table keywords. All fields in the given record are put
2785 as table keywords. The value of each field can be a scalar or
2786 an array of any type or it can be a record.
2787 It is also possible to define a keyword holding a subtable.
2788 This can be done by giving the keyword a string value consisting of
2789 the subtable name prefixed by 'Table: '.
2791 Input Parameters:
2792 value Record of keyword=value pairs
2794 Example:
2796 tb.open('3C273XC1.MS', nomodify=False)
2797 kw=tb.getkeywords()
2798 print kw['MS_VERSION']
2799 # 2.0
2800 kw['MS_VERSION']=2.1
2801 tb.putkeywords(kw)
2802 # !!!BROKEN. Keywords containing float are not handled properly!!!
2803 tb.flush()
2804 # True
2806 --------------------------------------------------------------------------------
2808 """
2809 return _table.table_putkeywords(self, *args, **kwargs)
2812 def putcolkeyword(self, *args, **kwargs):
2813 """
2814 putcolkeyword(self, _columnname, _keyword, _value) -> bool
2818 Summary:
2819 put a specific keyword for a column
2821 Description:
2824 Put a keyword in the given column.
2825 The value of the keyword can be a scalar or
2826 an array of any type or it can be a record.
2827 It is possible to define a keyword holding a subtable. In that
2828 case a special string containing the name of the subtable will be
2829 passed to the table client.
2830 It is possible that the value of a keyword is a record itself
2831 (arbitrarily deeply nested). A field in such a subrecord can be
2832 written by separating the name with dots. If a subrecord does not
2833 exist, an error is returned unless texttt{makesubrecord=True} is given.
2834 In such a case intermediate records are created when needed.
2836 Input Parameters:
2837 columnname Name of column
2838 keyword Name or seqnr of keyword,string or int
2839 value Value of keyword
2841 Example:
2843 tb.open('3C273XC1.MS', nomodify=False)
2844 ckw=tb.getcolkeyword('UVW','QuantumUnits')
2845 print ckw
2846 # modify ckw as desired
2847 tb.putcolkeyword('UVW','QuantumUnits',ckw)
2848 # True
2849 tb.flush()
2850 # True
2852 --------------------------------------------------------------------------------
2854 """
2855 return _table.table_putcolkeyword(self, *args, **kwargs)
2858 def putcolkeywords(self, *args, **kwargs):
2859 """
2860 putcolkeywords(self, _columnname, _value) -> bool
2864 Summary:
2865 put multiple keywords for a column
2867 Description:
2870 Put multiple keywords in the given column.
2871 All fields in the given record are put
2872 as column keywords. The value of each field can be a scalar or
2873 an array of any type or it can be a record.
2874 It is also possible to define a keyword holding a subtable.
2875 This can be done by giving the keyword a string value consisting of
2876 the subtable name prefixed by 'Table: '.
2878 Input Parameters:
2879 columnname Name of column
2880 value Record of keyword=value pairs
2882 Example:
2884 tb.open('3C273XC1.MS', nomodify=False)
2885 kws = tb.getcolkeywords('UVW')
2886 kws
2887 #{'MEASINFO': {'Ref': 'ITRF', 'type': 'uvw'},
2888 # 'QuantumUnits': array(['m', 'm', 'm'],
2889 # dtype='|S2')}
2890 kws['MEASINFO']['Ref']='B1950'
2891 tb.putcolkeywords(kws)
2892 # True
2894 --------------------------------------------------------------------------------
2896 """
2897 return _table.table_putcolkeywords(self, *args, **kwargs)
2900 def removekeyword(self, *args, **kwargs):
2901 """
2902 removekeyword(self, _keyword) -> bool
2906 Summary:
2907 remove a specific table keyword
2909 Input Parameters:
2910 keyword Name or seqnr of keyword: string or int
2912 Example:
2914 tb.open('3C273XC1.MS', nomodify=False)
2915 tb.removekeyword('MS_VERSION')
2916 # True
2917 tb.flush()
2918 # True
2920 --------------------------------------------------------------------------------
2922 """
2923 return _table.table_removekeyword(self, *args, **kwargs)
2926 def removecolkeyword(self, *args, **kwargs):
2927 """
2928 removecolkeyword(self, _columnname, _keyword) -> bool
2932 Summary:
2933 remove a specific keyword for a column
2935 Input Parameters:
2936 columnname Name of column
2937 keyword Name or seqnr of keyword: string or int
2939 Example:
2941 tb.open('3C273XC1.MS', nomodify=False)
2942 tb.removecolkeyword('UVW', 'QuantumUnits')
2943 # True
2944 tb.flush()
2945 # True
2947 --------------------------------------------------------------------------------
2949 """
2950 return _table.table_removecolkeyword(self, *args, **kwargs)
2953 def getdminfo(self):
2954 """
2955 getdminfo(self) -> record *
2959 Summary:
2960 get the info about data managers
2962 Description:
2965 This function returns the types and names of the data managers used.
2966 For each data manager it also returns the names of the columns served by it.
2967 The information is returned as a record containing a subrecord for
2968 each data manager. Each subrecord contains the fields TYPE, NAME and
2969 COLUMNS.
2971 Example:
2973 tb.open('3C273XC1.MS')
2974 rec = tb.getdminfo()
2976 Print the output record shows that the table uses 9 storage managers.
2978 --------------------------------------------------------------------------------
2980 """
2981 return _table.table_getdminfo(self)
2984 def keywordnames(self):
2985 """
2986 keywordnames(self) -> std::vector< std::string >
2990 Summary:
2991 get the names of all table keywords
2993 Description:
2996 This function returns a vector of strings containing the names
2997 of all table keywords.
2999 --------------------------------------------------------------------------------
3001 """
3002 return _table.table_keywordnames(self)
3005 def fieldnames(self, *args, **kwargs):
3006 """
3007 fieldnames(self, _keyword) -> std::vector< std::string >
3011 Summary:
3012 get the names of fields in a table keyword
3014 Description:
3017 This function returns a vector of strings containing the names
3018 of all fields in the given table keyword.
3019 It is only valid if the keyword value is a record.
3020 If no keyword name is given, the names of all table keywords are returned.
3022 Input Parameters:
3023 keyword keyword name
3025 --------------------------------------------------------------------------------
3027 """
3028 return _table.table_fieldnames(self, *args, **kwargs)
3031 def colkeywordnames(self, *args, **kwargs):
3032 """
3033 colkeywordnames(self, _columnname) -> std::vector< std::string >
3037 Summary:
3038 get the names of all keywords in a column
3040 Description:
3043 This function returns a vector of strings containing the names
3044 of all keywords in the column with the given name..
3046 Input Parameters:
3047 columnname column name
3049 Example:
3051 tb.open('3C273XC1.MS')
3052 tb.colkeywordnames('UVW')
3054 --------------------------------------------------------------------------------
3056 """
3057 return _table.table_colkeywordnames(self, *args, **kwargs)
3060 def colfieldnames(self, *args, **kwargs):
3061 """
3062 colfieldnames(self, _columnname, _keyword) -> std::vector< std::string >
3066 Summary:
3067 get the names of fields in a keyword in a column
3069 Description:
3072 This function returns a vector of strings containing the names
3073 of all fields in the given keyword in the given column.
3074 It is only valid if the keyword value is a record.
3075 If no keyword name is given, the names of all keywords in the column
3076 are returned.
3078 Input Parameters:
3079 columnname column name
3080 keyword keyword name
3082 --------------------------------------------------------------------------------
3084 """
3085 return _table.table_colfieldnames(self, *args, **kwargs)
3088 def getdesc(self, *args, **kwargs):
3089 """
3090 getdesc(self, _actual) -> record *
3094 Summary:
3095 get the table description
3097 Description:
3100 The table description is a casapy record that contains a complete
3101 description of the layout
3102 of the table (except for the number of rows).
3104 By default the actual table description is returned (thus telling the
3105 actual shapes and data managers used). It is also possible to get
3106 the table description used when creating the table.
3108 Input Parameters:
3109 actual actual table description?
3111 Example:
3113 tb.open('3C273XC1.MS')
3114 tb.getdesc()
3116 --------------------------------------------------------------------------------
3118 """
3119 return _table.table_getdesc(self, *args, **kwargs)
3122 def getcoldesc(self, *args, **kwargs):
3123 """
3124 getcoldesc(self, _columnname) -> record *
3128 Summary:
3129 get the description of a specific column
3131 Description:
3134 The column description is a casapy record that contains a complete
3135 description of the layout
3136 of a specified column (except for the number of rows). It can be used
3137 to construct a table description.
3139 Input Parameters:
3140 columnname Name of column
3142 Example:
3144 tb.open('3C273XC1.MS')
3145 tb.getcoldesc('DATA')
3146 #{'comment': 'The data column',
3147 # 'dataManagerGroup': 'TiledData',
3148 # 'dataManagerType': 'TiledShapeStMan',
3149 # 'maxlen': 0,
3150 # 'ndim': 2,
3151 # 'option': 0,
3152 # 'valueType': 'complex'}
3154 --------------------------------------------------------------------------------
3156 """
3157 return _table.table_getcoldesc(self, *args, **kwargs)
3160 def ok(self):
3161 """
3162 ok(self) -> bool
3166 Summary:
3167 Is the table tool ok?
3169 Description:
3172 Perform a number of sanity checks and return T if ok.
3173 Failure (returning F) is a sign of a bug.
3175 --------------------------------------------------------------------------------
3177 """
3178 return _table.table_ok(self)
3181 def clearlocks(self):
3182 """
3183 clearlocks(self) -> bool
3187 Summary:
3188 Clears any table lock associated with the current process
3190 Description:
3193 Occasionally a table will be inretrievably locked to another process no matter how much closing is done.
3194 So clearLocks will unlock all the files in the table cache that use AutoLocking.
3196 --------------------------------------------------------------------------------
3198 """
3199 return _table.table_clearlocks(self)
3202 def listlocks(self):
3203 """
3204 listlocks(self) -> bool
3208 Summary:
3209 Lists any table lock associated with the current process
3211 Description:
3214 Occasionally a table will be inretrievably locked to another process no matter how much closing is done.
3215 So listLocks will list the offending tables (and unoffending ones, too), so we can figure out where the problem might be.
3217 --------------------------------------------------------------------------------
3219 """
3220 return _table.table_listlocks(self)
3223 def statistics(self, *args, **kwargs):
3224 """
3225 statistics(self, _column, _complex_value) -> record *
3229 Summary:
3230 Get statistics on the selected table column
3232 Description:
3235 This function computes descriptive statistics on the table column.
3236 It returns the statistical values as a dictionary. The given
3237 column name must be a numerical column.
3238 If it is a complex valued column, the parameter complex_value defines
3239 which derived real value is used for the statistics computation.
3240 This method does not honor any flags in the input table.
3243 Input Parameters:
3244 column Column name
3245 complex_value Which derived value to use for complex columns (amp, amplitude, phase, imag, real, imaginary)
3247 Example:
3249 tb.open('ggtau.1mm.amp.gcal')
3250 s = tb.statistics(column='GAIN', complex_value='phase')
3252 --------------------------------------------------------------------------------
3254 """
3255 return _table.table_statistics(self, *args, **kwargs)
3258 def showcache(self, *args, **kwargs):
3259 """
3260 showcache(self, _verbose) -> std::vector< std::string >
3264 Summary:
3265 show the contents of the table cache
3267 Description:
3270 Show the contents of the table cache.
3272 Input Parameters:
3273 verbose
3275 Example:
3277 tb.showcache()
3279 --------------------------------------------------------------------------------
3281 """
3282 return _table.table_showcache(self, *args, **kwargs)
3285 def testincrstman(self, *args, **kwargs):
3286 """
3287 testincrstman(self, _column) -> bool
3291 Summary:
3292 Checks consistency of an Incremental Store Manager bucket layout
3294 Description:
3298 Checks consistency of an Incremental Store Manager bucket layout
3300 In case of corruption it returns False and a SEVERE msg is posted containing information about the location of the corrupted bucket
3304 Input Parameters:
3305 column Column name
3307 Example:
3309 mytb = tbtool()
3310 mytb.open('uid___A002_X841035_X203.ms.split')
3311 mytb.testincrstman('FLAG_ROW')
3313 --------------------------------------------------------------------------------
3315 """
3316 return _table.table_testincrstman(self, *args, **kwargs)
3319 def row(self, *args, **kwargs):
3320 """
3321 row(self, _columnnames, _exclude) -> casac::tablerow *
3325 Summary:
3326 Get a row accessor for this table
3328 Description:
3331 Return a table accessor object which allows for accessing one or more rows from the table. A single
3332 row is returned as a dictionary and multiple rows are returned as a list of dictionaries. The contents
3333 of the dictionary by default includes all table columns, but it can be limited by using ``columnnames``
3334 parameter. The ``exclude`` parameter, which is ``False`` by default, indicates whether ``columnnames``
3335 lists the columns to *exclude* (``exclude=True``) or the columns to include (``exclude=False``).
3337 The returned table accessor object can also be used to store changes to a single row using the ``put``
3338 method. This accessor object remains connected to the table object that created it. Closing or deleting
3339 a table object invalidates any accessor objects that it created.
3342 Input Parameters:
3343 columnnames Column names to be included in (or optionally excluded from) the the returned result.
3344 exclude If set to true, then columnnames describes the coluns to excluded rather than included.
3346 Example:
3348 ### open table
3349 tb = table( )
3350 tb.open( 'ngc5921_ut.ms', nomodify=False )
3352 ### read a single row
3353 print(f'row 3 is {tb.row( )[3]}')
3355 ### contents of the DATA column from the first 5 rows
3356 first_five_data = tb.row(columnnames=['DATA'])[:5]
3358 ### ENTIRE contents of the table
3359 whole_table = tb.row( )[:]
3361 ### store a single row
3362 rows = tb.row( )
3363 row = rows.get(22)
3364 row['DATA'].fill( 1.0/row['DATA'].size )
3365 rows.put( 22, { 'DATA': row['DATA'] } )
3367 --------------------------------------------------------------------------------
3369 """
3370 return _table.table_row(self, *args, **kwargs)
3372 __swig_destroy__ = _table.delete_table
3373 __del__ = lambda self: None
3374table_swigregister = _table.table_swigregister
3375table_swigregister(table)
3377# This file is compatible with both classic and new-style classes.