Module `tables`¶

Python interface to the Casacore tables module.

A casacore table is similar to a relational data base table with the extension that table cells can contain n-dimensional arrays. It has a rich SQL-like query language (TaQL).

A table consists of numbered rows and named columns. A column can hold scalar values or arrays of any dimensionality and shape. Furthermore the table and each column can hold a set of keywords (e.g. to define the units). It is nestable, thus the value of a keyword can be a keyword set in itself.

The tables module consists of a few classes:

table: main module to open, create, access, and query tables
tablecolumn: access the contents of a column in an easier way
tablerow: access the contents of table rows or parts of it
tableiter: iterate through a table based on the contents of one or more columns
tableindex: build and use an index on one or more table columns
submodule tableutil: table utility functions (e.g. to create a table description)
submodule msutil: MeasuementSet utility functions (e.g. to concat MSs)

Table utility functions¶

taql() or tablecommand(): Execute TaQL query command
tablefromascii(): Create table from ASCII file
maketabdesc() or tablecreatedesc: Create table description
makescacoldesc() or tablecreatescalarcoldesc: Create description of column holding scalars
makearrcoldesc() or tablecreatearraycoldesc: Create description of column holding arrays
makecoldesc(): Create description of any column
tabledefinehypercolumn(): Advanced definition of hypercolumn for tiled storage managers
tableexists(): Test if a table exists
tableiswritable(): Test if a table is writable
tablecopy(): Copy a table
tabledelete(): Delete a table
tablerename(): Rename a table
tableinfo(): Get the type info of a table
tablesummary(): Get a summary of the table

MeasurementSet utility functions¶

addImagingColumns(): Add MeasurementSet columns needed for the CASA imager
removeImagingColumns(): Remove CASA imager columns CORRECTED_DATA, MODEL_DATA, and IMAGING_WEIGHT
addDerivedMSCal(): Add the DerivedMSCal virtual columns like PA1, HA1 to a MeasurementSet
removeDerivedMSCal(): Remove the DerivedMSCal virtual columns like PA1, HA1 from a MeasurementSet
msconcat(): Concatenate spectral windows in different MSs to a single MS (in a virtual way)

Utility functions details¶

casacore.tables.taql(command, style='Python', tables=[], globals={}, locals={})¶

Execute a TaQL command and return a table object.

A TaQL command is an SQL-like command to do a selection of rows and/or columns in a table.

The default style used in a TaQL command is python, which means 0-based indexing, C-ordered arrays, and non-inclusive end in ranges.

It is possible to use python variables directly in the command using $var where var is the name of the variable to use. For example:

t = table('3c343.MS')
value = 5.1
t1 = taql('select from $t where COL > $value')

In this example the table $t is replaced by a sequence number (like $1) and $value by its value 5.1. The table object of t will be appended to a copy of the tables argument such that the sequence number inserted matches the table object in the list. The more advanced user can already use $n in the query string and supply the associated table object in the tables argument (where n represents the (n-1)th tables element).

The query() command makes use of this feature.

The arguments globals and locals can be used to pass in a dict containing the possible variables used in the TaQL command. They can be obtained with the python functions locals() and globals(). If locals is empty, the local variables in the calling function will be used, so normally one does not need to use these arguments.

casacore.tables.tablefromascii(tablename, asciifile, headerfile='', autoheader=False, autoshape=[], columnnames=[], datatypes=[], sep=' ', commentmarker='', firstline=1, lastline=-1, readonly=True, lockoptions='default', ack=True)¶

Create a table from an ASCII file.

Create a table from a file in ASCII format. Columnar data as well as table and column keywords may be specified. Once the table is created from the ASCII data, it is opened in the specified mode and a table object is returned.

The table columns are filled from a file containing the data values separated by a separator (one line per table row). The default separator is a blank. Blanks before and after the separator are ignored. If a non-blank separator is used, values can be empty. Such values default to 0, empty string, or F depending on the data type. E.g. 1,,2, has 4 values of which the 2nd and 4th are empty and default to 0. Similarly if fewer values are given than needed, the missing values get the default value.

Either the data format can be explicitly specified or it can be found automatically. The former gives more control in ambiguous situations. Both scalar and array columns can be generated from the ASCII input. The format string determines the type and optional shape.

It is possible to give the column names and their data types in various ways:

Using 2 header lines (as described below) as the first two lines in the data file or in a separate header file. This is the default way.
Derive them automatically from the data (autoheader=True).
Using the arguments columnnames and datatypes (as non-empty vectors of strings). It implies (autoheader=False). The data types should be given in the same way as done in headers.

In automatic mode (autoheader=True) the first line of the ASCII data is analyzed to deduce the data types. Only the types I, D, and A can be recognized. A number without decimal point or exponent is I (integer), otherwise it is D (double). Any other string is A (string). Note that a number may contain a leading sign (+ or -). The autoshape argument can be used to specify if the input should be stored as multiple scalars (the default) or as a single array. In the latter case one axis in the shape can be defined as variable length by giving it the value 0. It means that the actual array shape in a row is determined by the number of values in the corresponding input line. Columns get the names Column1, Column2, etc.. For example:

autoshape=[] (which is the default) means that all values are to be stored as scalar columns.
autoshape=0 means that all values in a row are to be stored as a variable length vector.
autoshape=10 defines a fixed length vector. If an input line contains less than 10 values, the vector is filled with default values. If more than 10 values, the latter values are ignored.
autoshape=[5,0] defines a 2-dim array of which the 2nd axis is variable. Note that if an input line does not contain a multiple of 5 values, the array is filled with default values.

If the format of the table is explicitly specified, it has to be done either in the first two lines of the data file (named by the argument filename), or in a separate header file (named by the argument headerfile). In both forms, table keywords may also be specified before the column definitions. The column names and types can be described by two lines:

The first line contains the names of the columns. These names may be enclosed in quotes (either single or double).
The second line contains the data type and optionally the shape of each column. Valid types are:
- S for Short data
- I for Integer data
- R for Real data
- D for Double Precision data
- X for Complex data (Real followed by Imaginary)
- Z for Complex data (Amplitude then Phase)
- DX for Double Precision Complex data (Real followed by Imaginary)
- DZ for Double Precision Complex data (Amplitude then Phase)
- A for ASCII data (a value must be enclosed in single or double quotes if it contains whitespace)
- B for Boolean data (False are empty string, 0, or any string starting with F, f, N, or n).

If a column is an array, the shape has to be given after the data type without any whitespace. E.g. I10 defines an integer vector of length 10. A2,5 defines a 2-dim string array with shape [2,5]. Note that I is not the same as I1 as the first one defines a scalar and the other one a vector with length 1. The last column can have one variable length axis denoted by the value 0. It “consumes” the remainder of the input line.

If the argument headerfile is set then the header information is read from that file instead of the first lines of the data file.

To give a simple example of the form where the header information is located at the top of the data file:

COLI   COLF   COLD       COLX        COLZ       COLS
  I      R      D          X           Z          A
  1      1.1    1.11       1.12 1.13   1.14 1.15  Str1
  10     11     12         13   14     15   16    ""

Note that a complex number consists of 2 numbers. Also note that an empty string can be given.

Let us now give an example of a separate header file that one might use to get interferometer data into casacore:

U     V      W         TIME        ANT1       ANT2      DATA
R     R      R          D           I          I        X1,0

The data file would then look like:

124.011 54560.0  3477.1  43456789.0990    1      2        4.327 -0.1132
34561.0 45629.3  3900.5  43456789.0990    1      3        5.398 0.4521

Note that the DATA column is defined as a 2-dim array of 1 correlation and a variable number of channels, so the actual number of channels is determined by the input. In this example both rows will have 1 channel (note that a complex value contains 2 values).

Tables may have keywords in addition to the columns. The keywords are useful for holding information that is global to the entire table (such as author, revision, history, etc.). The keywords in the header definitions must preceed the column descriptions. They must be enclosed between a line that starts with ”.key...” and a line that starts with ”.endkey...” (where ... can be anything). A table keywordset and column keywordsets can be specified. The latter can be specified by specifying the column name after the .keywords string. Between these two lines each line should contain the following:

The keyword name, e.g., ANYKEY
The datatype and optional shape of the keyword (cf. list of valid types above)
The value or values for the keyword (the keyword may contain a scalar or an array of values). e.g., 3.14159 21.78945

Thus to continue the example above, one might wish to add keywords as follows:

.keywords
DATE        A  "97/1/16"
REVISION    D 2.01
AUTHOR      A "Tim Cornwell"
INSTRUMENT  A "VLA"
.endkeywords
.keywords TIME
UNIT A "s"
.endkeywords
U     V      W         TIME        ANT1       ANT2      DATA
R     R      R          D           I          I        X1,0

Similarly to the column format string, the keyword formats can also contain shape information. The only difference is that if no shape is given, a keyword can have multiple values (making it a vector).

It is possible to ignore comment lines in the header and data file by giving the commentmarker. It indicates that lines starting with the given marker are ignored. Note that the marker can be a regular expression (e.g. ‘ *//’ tells that lines starting with // and optionally preceeded by blanks have to be ignored).

With the arguments firstline and lastline one can specify which lines have to be taken from the input file. A negative value means 1 for firstline or end-of-file for lastline. Note that if the headers and data are combined in one file, these line arguments apply to the whole file. If headers and data are in separate files, these line arguments apply to the data file only.

Also note that ignored comment lines are counted, thus are used to determine which lines are in the line range.

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

casacore.tables.maketabdesc(descs=[])¶

Create a table description.

Creates a table description from a set of column descriptions. The resulting table description can be used in the table constructor.

For example:

scd1 = makescacoldesc("col2", "aa")
scd2 = makescacoldesc("col1", 1, "IncrementalStMan")
scd3 = makescacoldesc("colrec1", {})
acd1 = makearrcoldesc("arr1", 1, 0, [2,3,4])
acd2 = makearrcoldesc("arr2", 0.+0j)
td = maketabdesc([scd1, scd2, scd3, acd1, acd2])
t = table("mytable", td, nrow=100)

This creates a table description td from five column descriptions and then creates a 100-row table called mytable from the table description.

The columns contain respectivily strings, integer scalars, records, 3D integer arrays with fixed shape [2,3,4], and complex arrays with variable shape.

casacore.tables.makescacoldesc(columnname, value, datamanagertype='', datamanagergroup='', options=0, maxlen=0, comment='', valuetype='', keywords={})¶

Create description of a scalar column.

A description for a scalar column can be created from a name for the column and a data value, which is used only to determine the type of the column. Note that a dict value is also possible.

It is possible to create the column description in more detail by giving the data manager name, group, option, and comment as well.

The data manager type tells which data manager (storage manager) is used to store the columns. The data manager type and group are explained in more detail in the casacore Tables documentation.

It returns a dict with fields name and desc which can thereafter be used to build a table description using function maketabdesc().

columname: Name of column
value: Example data value used to determine the column’s data type. It is only used if argument valuetype is not given.
datamanagertype: Type of data manager which can be one of StandardStMan (default) or IncrementalStMan. The latter one can save disk space if many subsequent cells in the column will have the same value.
datamanagergroup: Data manager group. Only for the expert user.
options: Options. Need not be filled in.
maxlen: Maximum length of string values in a column. Default 0 means unlimited.
comment: Comment: informational for user.
valuetype: A string giving the column’s data type. Possible data types are bool (or boolean), uchar (or byte), short, int (or integer), uint, float, double, complex, dcomplex, and string.
‘keywords’: A dict defining initial keywords for the column.

For example:

scd1 = makescacoldesc("col2", ""))
scd2 = makescacoldesc("col1", 1, "IncrementalStMan")
td = maketabdesc([scd1, scd2])

This creates a table description consisting of an integer column col1, and a string column col2. col1 uses the IncrementalStMan storage manager, while col2 uses the default storage manager StandardStMan.

casacore.tables.makearrcoldesc(columnname, value, ndim=0, shape=[], datamanagertype='', datamanagergroup='', options=0, maxlen=0, comment='', valuetype='', keywords={})¶

Create description of an array column.

A description for a scalar column can be created from a name for the column and a data value, which is used only to determine the type of the column. Note that a dict value is also possible.

It is possible to create the column description in more detail by giving the dimensionality, shape, data manager name, group, option, and comment as well.

The data manager type tells which data manager (storage manager) is used to store the columns. The data manager type and group are explained in more detail in the casacore Tables documentation.

It returns a dict with fields name and desc which can thereafter be used to build a table description using function maketabdesc().

name

The name of the column.

value

A data value, which is only used to determine the data type of the column. It is only used if argument valuetype is not given.

ndim

Optionally the number of dimensions. A value > 0 means that all arrays in the column must have that dimensionality. Note that the arrays can still differ in shape unless the shape vector is also given.

shape

An optional sequence of integers giving the shape of the array in each cell. If given, it forces option FixedShape (see below) and sets the number of dimensions (if not given). All arrays in the column get the given shape and the array is created as soon as a row is added. Note that the shape vector gives the shape in each table cell; the number of rows in the table should NOT be part of it.

datamanagertype

Type of data manager which can be one of StandardStMan (default), IncrementalStMan, TiledColumnStMan, TiledCellStMan, or TiledShapeStMan. The tiled storage managers are usually used for bigger data arrays.

datamanagergroup

Data manager group. Only for the expert user.

options

Optionally numeric array options which can be added to combine them.

1 means Direct.: It tells that the data are directly stored in the table. Direct forces option FixedShape. If not given, the array is indirect, which means that the data will be stored in a separate file.
4 means FixedShape.: This option does not need to be given, because it is enforced if the shape is given. FixedShape means that the shape of the array must be the same in each cell of the column. Otherwise the array shapes may be different in each column cell and is it possible that a cell does not contain an array at all. Note that when given (or implicitly by option Direct), the shape argument must be given as well.

Default is 0, thus indirect and variable shaped.

maxlen

Maximum length of string values in a column. Default 0 means unlimited.

comment

Comment: informational for user.

valuetype

A string giving the column’s data type. Possible data types are bool (or boolean), uchar (or byte), short, int (or integer), uint, float, double, complex, dcomplex, and string.

‘keywords’

A dict defining initial keywords for the column.

For example:

acd1= makescacoldesc("arr1", 1., 0, [2,3,4])
td = maketabdesc(acd1)

This creates a table description consisting of an array column arr1 containing 3-dim arrays of doubles with shape [2,3,4].

casacore.tables.makecoldesc(columnname, desc)¶

Create column description using the description of another column.

The other description can be obtained from a table using function getcoldesc() or from another column description dict using otherdesc[‘desc’].

It returns a dict with fields name and desc which can thereafter be used to build a table description using function maketabdesc().

columname: Name of column
desc: Description of the column

For example:

cd1 = makecoldesc("col2", t.getcoldesc('othercol'))
td = maketabdesc(cd1)

This creates a table description consisting of a column col2 having the same description as column othercol.

casacore.tables.tabledefinehypercolumn(tabdesc, name, ndim, datacolumns, coordcolumns=False, idcolumns=False)¶

Add a hypercolumn to a table description.

It defines a hypercolumn and adds it the given table description. A hypercolumn is an entity used by the Tiled Storage Managers (TSM). It defines which columns have to be stored together with a TSM.

It should only be used by expert users who want to use a TSM to its full extent. For a basic TSM s hypercolumn definition is not needed.

tabledesc: A table description (result from maketabdesc()).
name: Name of hypercolumn
ndim: Dimensionality of hypercolumn; normally 1 more than the dimensionality of the arrays in the data columns to be stored with the TSM
datacolumns: Data columns to be stored with TSM
coordcolumns: Optional coordinate columns to be stored with TSM
idcolumns: Optional id columns to be stored with TSM

For example:

scd1 = makescacoldesc("col2", "aa")
scd2 = makescacoldesc("col1", 1, "IncrementalStMan")
scd3 = makescacoldesc("colrec1", {})
acd1 = makearrcoldesc("arr1", 1, 0, [2,3,4])
acd2 = makearrcoldesc("arr2", as_complex(0))
td = maketabdesc([scd1, scd2, scd3, acd1, acd2])
tabledefinehypercolumn(td, "TiledArray", 4, ["arr1"])
tab = table("mytable", tabledesc=td, nrow=100)

This creates a table description td from five column descriptions
and then creates a 100-row table called mytable from the table
description.
The columns contain respectivily strings, integer scalars, records,
3D integer arrays with fixed shape [2,3,4], and complex arrays with
variable shape.
The first array is stored with the Tiled Storage Manager (in this case
the TiledColumnStMan).

casacore.tables.tableexists(tablename)¶: Test if a table exists.

casacore.tables.tableiswritable(tablename)¶: Test if a table is writable.

casacore.tables.tablecopy(tablename, newtablename, deep=False, valuecopy=False, dminfo={}, endian='aipsrc', memorytable=False, copynorows=False)¶

Copy a table.

It is the same as table.copy(), but without the need to open the table first.

casacore.tables.tabledelete(tablename, checksubtables=False, ack=True)¶

Delete a table on disk.

It is the same as table.delete(), but without the need to open the table first.

casacore.tables.tablerename(tablename, newtablename)¶

Rename a table.

The table with the given name is renamed (or moved) to the new name.

casacore.tables.tableinfo(tablename)¶

Get type info of a table.

It is the same as table.info(), but without the need to open the table first.

casacore.tables.tablesummary(tablename)¶

Get the summary of a table.

It is the same as table.summary(), but without the need to open the table first.

casacore.tables.addImagingColumns(msname, ack=True)¶

Add the columns to an MS needed for the casa imager.

It adds the columns MODEL_DATA, CORRECTED_DATA, and IMAGING_WEIGHT. It also sets the CHANNEL_SELECTION keyword needed for the older casa imagers.

A column is not added if already existing.

casacore.tables.removeImagingColumns(msname)¶

casacore.tables.addDerivedMSCal(msname)¶

Add the derived columns like HA to an MS or CalTable

It adds the columns HA, HA1, HA2, PA1, PA2, LAST, LAST1, LAST2, AZEL1, AZEL2, and UVW_J2000. They are all bound to the DerivedMSCal virtual data manager.

It fails if one of the columns already exists.

casacore.tables.removeDerivedMSCal(msname)¶

Remove the derived columns like HA from an MS or CalTable

It removes the columns using the data manager DerivedMSCal. Such columns are HA, HA1, HA2, PA1, PA2, LAST, LAST1, LAST2, AZEL1, AZEL2, and UVW_J2000.

It fails if one of the columns already exists.

casacore.tables.msconcat(names, newname, concatTime=False)¶

Virtually concatenate multiple MeasurementSets

Multiple MeasurementSets are concatenated into a single MeasurementSet. The concatenation is done in an entirely or almost entirely virtual way, so hardly any data are copied. It makes the command very fast and hardly any extra disk space is needed.

The MSs can be concatenated in time or frequency (spectral windows). If concatenated in time, no indices need to be updated and the concatenation is done in a single step.

If spectral windows are concatenated, tThe data-description-ids and spectral-window-ids in the resulting MS and its subtables are updated to make them unique. The spectral concatenation is done in two steps and results in two MSs:

The input MSs are virtually concatenated resulting in the MeasurementSet <newname>_CONCAT.
The MeasurementSet <newname> is created. It references all columns in <newname>_CONCAT with the exception of the DATA_DESC_ID column. This column is copied and updated to make the ids correct. Furthermore the MS contains a copy of all subtables (with the exception of SORTED_TABLE), where the DATA_DESCRIPTION and SPECTRAL_WINDOW subtables are the concatenation of those subtables in the input MSs. The ids in the resulting subtables are updated.

The FEED, FREQ_OFFSET, SOURCE, and SYSCAL subtables also have a SPECTRAL_WINDOW_ID column. Currently these subtables are not concatenated nor are their ids updated.

names: A sequence containing the names of the MeasurementSets to concatenate.
newname: The name of the resulting MeasurementSet. A MeasurementSet with this name followed by _CONCAT will also be created (and must be kept).
concatTime: False means that the spectral windows ids will be adjusted as explained above.

Class `tables.table`¶

class casacore.tables.table(tablename, tabledesc=False, nrow=0, readonly=True, lockoptions='default', ack=True, dminfo={}, endian='aipsrc', memorytable=False, concatsubtables=[], _columnnames=[], _datatypes=[], _oper=0, _delete=False)¶

The Python interface to Casacore tables.

One can open or create tables, get or put data in them, make selections, get meta information (like storage managers used), etc. It is possible to lock/unlock a table for concurrent access.

A table consists of numbered rows and named columns. A column can hold scalar values or arrays of any dimensionality and shape. Furthermore the table and each column can hold a possibly nested keyword set (e.g. to define the units).

The classes tablecolumn, tableiter, tableindex, and tablerow tablecolumn can be used for easier access to tables. Module tableutil contains some useful utility functions, for instance tablefromascii() to create a table from an ASCII file.

Several functions accept or return arrays for which numpy arrays are used. One dimensional arrays can also be passed as sequences (e.g., a list). A scalar value can also be passed to functions expecting an array and results in a 1-dim array of length 1. Scalar arguments can be passed as normal python scalars, but also as numpy scalars (which have a special data type). If needed and if possible, data type conversion is done automatically.

A table object contains a tablerow object which contains all columns. Similar to tablerow the table object can be indexed in the standard python way to get (or put) values in one or more rows. For example:

t = table('~/3c343.MS')
print t[0]

The table class supports the context manager idiom (__enter__ and __exit__). When used in a with statement, the table will be flushed and closed automatically, which is handy when writing a table. For example:

with table('my.ms') as t:
  t.putcell ('SPECTRAL_WINDOW_ID', 0, 0)

Usually a table is kept on disk, but it can also reside in memory. Furthermore, results of sort and selection are kept as so-called reference tables which are kept in memory (but can be made persistent).

table(‘tablename’, tabledesc): creates a new table using the given table description which can be obtained from an existing table (using table.getdesc) or created (using tableutil.maketabdesc). If memorytable=True, the table is created in memory.
table(‘tablename’, readonly=False): opens an existing table for read/write. Default is for readonly.

In general it is a bad idea to open a subtable using a path like ‘my.ms/ANTENNA’, because it will fail if ‘my.ms’ is a selection instead of a plain table. Therefore a double colon can be used like ‘my.ms::ANTENNA’ making the table system handle it in a correct way.
table([‘table1’,’table2’,...]): opens a virtual table as the concatenation of the given tables. The tables have to have the same columns.
table([tableobject1,tableobject2,...]): opens a virtual table as the concatenation of the given table objects. The tables have to have the same columns.

The following arguments can be used.

tablename: name of the table to be opened or created. As in most UNIX shells a table name can contain environment variables and a tilde with optional user name.

This argument can be a sequence of names in which case they are opened as a (virtual) concatenation of tables.

It can also be a sequence of table objects to be concatenated.
tabledesc: description of table to be created. If given as a dict (which should be created by maketabdesc(), the table is created. Otherwise it should exist and is opened.
nrow: initial number of rows in table to be created (default 0).
readonly = True/False: tell if a table has to be opened readonly (default) or read/write.
lockoptions: see below
ack=False: prohibit the printing of a message telling if the table was opened or created successfully.
dminfo: a dict (as returned by getdminfo()) giving specific data manager info for one or more columns. In this way expert users can tell how data are stored (or use virtual data managers).
endian: endianness of the data in table to be created

‘little’ = as little endian

‘big’ = as big endian

‘local’ = use the endianness of the machine being used

‘aipsrc’ = use a defined in an .aipsrc file (defaults to local)
memorytable=True: create table in memory instead of on disk.
concatsubtables: if tables are concatenated, it should contain a sequence of the names of subtables to be concatenated as well (default none). Non-mentioned subtables are considered to be identical in each table, so only the subtable of the first table is used as subtable for the concatenated table.

Locking/unlocking to share a table in a concurrent environment is controlled by the lockoptions argument.

auto: let the system take care of locking. It locks when needed, but unlocking is usually not done automatically.
autonoread: as auto, but no read locking is needed. This must be used with care, because it means that reading can be done while the table object is not synchronized with the table file (as is normally done when a lock is acquired). The method resync() can be used to explicitly synchronize the table object with the file.
user: the user takes care by explicit calls to lock and unlock
usernoread: as user and the no readlocking behaviour of autonoread.
permanent: use a permanent write lock; the constructor fails if the lock cannot be acquired because the table is already in use in another process
permanentwait: as above, but wait until the lock is acquired.
default: this is the default option. If the given table is already open, the locking option in use is not changed. Otherwise it reverts to auto.

If auto locking is used, it is possible to give a record containing the fields option, interval, and/or maxwait (see lockoptions() for their meaning). In this way advanced users can have full control over the locking process. In practice this is hardly ever needed.

For example:

t = table('3c343.ms')                  # open table readonly
t = table('3c343.ms', readonly=False)  # open table read/write
t1= table('new.tab', t.getdesc())      # create table
t = table([t1,t2,t3,t4])               # concatenate 4 tables

addcols(desc, dminfo={}, addtoparent=True)¶

Add one or more columns.

Columns can always be added to a normal table. They can also be added to a reference table and optionally to its parent table.

desc

contains a description of the column(s) to be added. It can be given in three ways:

a dict created by maketabdesc(). In this way multiple columns can be added.
a dict created by makescacoldesc(), makearrcoldesc(), or makecoldesc(). In this way a single column can be added.
a dict created by getcoldesc(). The key ‘name’ containing the column name has to be defined in such a dict.

dminfo

can be used to provide detailed data manager info to tell how the column(s) have to be stored. The dminfo of an existing column can be obtained using method getdminfo().

addtoparent

defines if the column should also be added to the parent table in case the current table is a reference table (result of selection). If True, it will be added to the parent if it does not exist yet.

For example, add a column using the same data manager type as another column:

coldmi = t.getdminfo('colarrtsm')     # get dminfo of existing column
coldmi["NAME"] = 'tsm2'               # give it a unique name
t.addcols (maketabdesc(makearrcoldesc("colarrtsm2",0., ndim=2)),
           coldmi)

addreadmeline(value)¶: Add a readme line to the table info.

addrows(nrows=1)¶: Add one or more rows to the table.

browse(wait=True, tempname='/tmp/seltable')¶

Browse a table using casabrowser or a simple wxwidget based browser.

By default the casabrowser is used if it can be found (in your PATH). Otherwise the wxwidget one is used if wx can be loaded.

The casabrowser can only browse tables that are persistent on disk. This gives problems for tables resulting from a query because they are held in memory only (unless an output table name was given).

To make browsing of such tables possible, the argument tempname can be used to specify a table name that will be used to form a persistent table that can be browsed. Note that such a table is very small as it does not contain data, but only references to rows in the original table. The default for tempname is ‘/tmp/seltable’.

If needed, the table can be deleted using the tabledelete() function.

If wait=False, the casabrowser is started in the background. In that case the user should delete a possibly created copy of a temporary table.

calc(expr, style='Python')¶

Do a TaQL calculation

The TaQL CALC command can be used to get the result of a calculation on table data. It is, however, also possible to use it without table data.

For instance, to use it for converting units:

t = table('',{})
t.calc ('(1 \in)cm')

expr: The CALC expression
style: The TaQL syntax style to be used (defaults to Python).

close()¶: Flush and close the table which invalidates the table object.

col(columnname)¶

Return a tablecolumn object for the given column.

If multiple operations need to be done on a column, a tablecolumn object is somewhat easier to use than the table object because the column name does not have to be repeated each time.

It is also possible to use a column name as an attribute, It is an easier way to get a column object.

For example:

tc = t.col('DATA')
tc[0:10]       # get first 10 rows of column DATA
t.DATA[0:10]   # does the same in an easier way

colarraytype(columnname)¶

Get the array type of a column holding arrays.

It tells if an array is fixed or variable shaped and if it is stored directly or indirectly. This is done by means of a string like Indirect, variable sized arrays

coldatatype(columnname)¶

Get the data type of a column.

It returns a string which can have the values: boolean integer float double complex dcomplex string record

coldesc(columnname, actual=True)¶

Make the description of a column.

Make the description object of the given column like makecoldesc() is doing with the description given by getcoldesc().

colfieldnames(columnname, keyword='')¶

Get the names of the fields in a column keyword value.

The value of a keyword can be a struct (python dict). This method returns the names of the fields in that struct. Each field in a struct can be a struct in itself. Names of fields in a sub-struct can be obtained by giving a keyword name consisting of multiple parts separated by dots (e.g. ‘key1.sub1.sub2’).

If an empty keyword name is given (which is the default), all keyword names of the column are shown and its behaviour is the same as colkeywordnames().

Instead of a keyword name an index can be given which returns the names of the struct value of the i-th keyword.

colkeywordnames(columnname)¶: Get the names of all keywords of a column.

colnames()¶: Get the names of all columns in the table.

copy(newtablename, deep=False, valuecopy=False, dminfo={}, endian='aipsrc', memorytable=False, copynorows=False)¶

Copy the table and return a table object for the copy.

It copies all data in the columns and keywords. Besides the table, all its subtables are copied too. By default a shallow copy is made (usually by copying files). It means that the copy of a reference table is also a reference table. Use deep=True to make a deep copy which turns a reference table into a normal table.

deep=True: a deep copy of a reference table is made.
valuecopy=True: values are copied, which reorganizes normal tables and removes wasted space. It implies deep=True. It is slower than a normal copy.
dminfo: gives the option to specify data managers to change the way columns are stored. This is a dict as returned by method getdminfo().
endian: specifies the endianness of the new table when a deep copy is made: | ‘little’ = as little endian | ‘big’ = as big endian | ‘local’ = use the endianness of the machine being used | ‘aipsrc’ = use as defined in an .aipsrc file (defaults to local)
memorytable=True: do not copy to disk, but to a table kept in memory.
copynorows=True: only copy the column layout and keywords, but no data.

For example:

t  = table('3c343.MS')
t1 = t.query('ANTENNA1 != ANTENNA2')   # do row selection
t2 = t1.copy ('3c343.sel', True)       # make deep copy
t2 = t.copy ('new.tab', True, True)    # reorganize storage

copyrows(outtable, startrowin=0, startrowout=-1, nrow=-1)¶

Copy the contents of rows from this table to outtable.

The contents of the columns with matching names are copied. The other arguments can be used to specify where to start copying. By default the entire input table is appended to the output table. Rows are added to the output table if needed.

startrowin: Row where to start in the input table.
startrowout: Row where to start in the output table, | -1 means write at the end of the output table.
nrow: Number of rows to copy | -1 means from startrowin till the end of the input table

The following example appends row to the table itself, thus doubles the number of rows:

t:=table('test.ms',readonly=F)
t.copyrows(t)

datachanged()¶: Tell if data in the table have changed since the last time called.

done()¶: Flush and close the table which invalidates the table object.

endianformat()¶: Return the endian format (‘little’ or ‘big’) in which the table is written.

fieldnames(keyword='')¶

Get the names of the fields in a table keyword value.

The value of a keyword can be a struct (python dict). This method returns the names of the fields in that struct. Each field in a struct can be a struct in itself. Names of fields in a sub-struct can be obtained by giving a keyword name consisting of multiple parts separated by dots (e.g. ‘key1.sub1.sub2’).

If an empty keyword name is given (which is the default), all table keyword names are shown and its behaviour is the same as keywordnames().

Instead of a keyword name an index can be given which returns the names of the struct value of the i-th keyword.

flush(recursive=False)¶

Flush the table to disk.

Until a flush or unlock is performed, the results of operations might not be stored on disk yet. | If recursive=True, all subtables are flushed as well.

getcell(columnname, rownr)¶

Get data from a column cell.

Get the contents of a cell which can be returned as a scalar value, a numpy array, or a dict depending on the contents of the cell.

getcellnp(columnname, rownr, nparray)¶

Get data from a column cell into the given numpy array .

Get the contents of a cell containing an array into the given numpy array. The numpy array has to be C-contiguous with a shape matching the shape of the column cell. Data type coercion will be done as needed.

getcellslice(columnname, rownr, blc, trc, inc=[])¶

Get a slice from a column cell holding an array.

The columnname and (0-relative) rownr indicate the table cell.

The slice to get is defined by the blc, trc, and optional inc arguments. (blc = bottom-left corner, trc=top-right corner, inc=stride). Not all axes have to be filled in for blc, trc, and inc. Missing axes default to begin, end, and 1. A negative blc or trc defaults to begin or end. Note that trc is inclusive (unlike python indexing).

getcellslicenp(columnname, nparray, rownr, blc, trc, inc=[])¶

Get a slice from a column cell into the given numpy array.

The columnname and (0-relative) rownr indicate the table cell.

The numpy array has to be C-contiguous with a shape matching the shape of the slice. Data type coercion will be done as needed.

The slice to get is defined by the blc, trc, and optional inc arguments. (blc = bottom-left corner, trc=top-right corner, inc=stride). Not all axes have to be filled in for blc, trc, and inc. Missing axes default to begin, end, and 1. A negative blc or trc defaults to begin or end. Note that trc is inclusive (unlike python indexing).

getcol(columnname, startrow=0, nrow=-1, rowincr=1)¶

Get the contents of a column or part of it.

It is returned as a numpy array. If the column contains arrays, they should all have the same shape. An exception is thrown if they differ in shape. In that case the method getvarcol() should be used instead.

The column can be sliced by giving a start row (default 0), number of rows (default all), and row stride (default 1).

getcoldesc(columnname, actual=True)¶

Get the description of a column.

By default it returns the actual description (thus telling the actual array shapes and data managers used). actual=False means that the original description as made by makescacoldesc() or makearrcoldesc() is returned.

getcolkeyword(columnname, keyword)¶

Get the value of a column keyword.

It is similar to getkeyword().

getcolkeywords(columnname)¶

Get the value of all keywords of a column.

It is returned as a dict. See getkeyword() for the possible value types.

getcolnp(columnname, nparray, startrow=0, nrow=-1, rowincr=1)¶

Get the contents of a column or part of it into the given numpy array.

The numpy array has to be C-contiguous with a shape matching the shape of the column (part). Data type coercion will be done as needed.

If the column contains arrays, they should all have the same shape. An exception is thrown if they differ in shape. In that case the method getvarcol() should be used instead.

The column can be sliced by giving a start row (default 0), number of rows (default all), and row stride (default 1).

getcolshapestring(columnname, startrow=0, nrow=-1, rowincr=1)¶

Get the shapes of all cells in the column in string format.

It returns the shape in a string like [10,20,30].

If the column contains fixed shape arrays, a single shape is returned. Otherwise a list of shape strings is returned.

The column can be sliced by giving a start row (default 0), number of rows (default all), and row stride (default 1).

getcolslice(columnname, blc, trc, inc=[], startrow=0, nrow=-1, rowincr=1)¶

Get a slice from a table column holding arrays.

The slice in each array is given by blc, trc, and inc (as in getcellslice). The column can be sliced by giving a start row (default 0), number of rows (default all), and row stride (default 1).

It returns a numpy array where the first axis is formed by the column cells. The other axes are the array axes.

getcolslicenp(columnname, nparray, blc, trc, inc=[], startrow=0, nrow=-1, rowincr=1)¶

Get a slice from a table column into the given numpy array.

The numpy array has to be C-contiguous with a shape matching the shape of the column (slice). Data type coercion will be done as needed.

The slice in each array is given by blc, trc, and inc (as in getcellslice). The column can be sliced by giving a start row (default 0), number of rows (default all), and row stride (default 1).

It returns a numpy array where the first axis is formed by the column cells. The other axes are the array axes.

getdesc(actual=True)¶

Get the table description.

By default it returns the actual description (thus telling the actual array shapes and data managers used). actual=False means that the original description as made by maketabdesc() is returned.

getdminfo(columnname=None)¶

Get data manager info.

Each column in a table is stored using a data manager. A storage manager is a data manager storing the physically in a file. A virtual column engine is a data manager that does not store data but calculates it on the fly (e.g. scaling floats to short to reduce storage).

By default this method returns a dict telling the data managers used. Each field in the dict is a dict containing:

NAME telling the (unique) name of the data manager
TYPE telling the type of data manager (e.g. TiledShapeStMan)
SEQNR telling the sequence number of the data manager (is ‘’i’’ in table.f<i> for storage managers)
SPEC is a dict holding the data manager specification
COLUMNS is a list giving the columns stored by this data manager

When giving a column name the data manager info of that particular column is returned (without the COLUMNS field). It can, for instance, be used when adding a column using addcols() that should use the same data manager type as an existing column. However, when doing that care should be taken to change the NAME because each data manager name has to be unique.

getdmprop(name, bycolumn=True)¶

Get properties of a data manager.

Each column in a table is stored using a data manager. A storage manager is a data manager storing the physically in a file. A virtual column engine is a data manager that does not store data but calculates it on the fly (e.g. scaling floats to short to reduce storage).

Some data managers have properties that can be changed on the fly (e.g. cachesize for a tiled storage manager). The properties of a given data manager are returned as a dict; function setdmprop() can be used to change the properties. Note the properties are also part of the data manager info returned by getdminfo().

The data manager can be specified in two ways: by data manager name or by the name of a column using the data manager. The argument bycolumn defines which way is used (default is by column name).

getkeyword(keyword)¶

Get the value of a table keyword.

The value of a keyword can be a:

scalar which is returned as a normal python scalar.
an array which is returned as a numpy array.
a reference to a table which is returned as a string containing its name prefixed by ‘Table :’. It can be opened using the normal table constructor which will remove the prefix.
a struct which is returned as a dict. A struct is fully nestable, thus each field in the struct can have one of the values described here.

Similar to method fieldnames() a keyword name can be given consisting of multiple parts separated by dots. This represents nested structs, thus gives the value of a field in a struct (in a struct, etc.).

Instead of a keyword name an index can be given which returns the value of the i-th keyword.

getkeywords()¶

Get the value of all table keywords.

It is returned as a dict. See getkeyword() for the possible value types.

getsubtables()¶: Get the names of all subtables.

getvarcol(columnname, startrow=0, nrow=-1, rowincr=1)¶

Get the contents of a column or part of it.

It is similar to getcol(), but the result is returned as a dict of numpy arrays. It can deal with a column containing variable shaped arrays.

haslock(write=True)¶: Test if the table is read or write locked.

index(columnnames, sort=True)¶

Return a tableindex object.

tableindex lets one get the row numbers of the rows holding given values for the columns for which the index is created. It uses an in-memory index on which a binary search is done. By default the table is sorted on the given columns to get the correct index order.

For example:

t = table('3c343.MS')
tinx = t.index('ANTENNA1')
print tinx.rownumbers(0)       # print rownrs containing ANTENNA1=0

info()¶: Return the table info (table type, subtype, and readme lines).

iscelldefined(columnname, rownr)¶

Tell if a column cell contains a value.

Columns containing variable shaped arrays can be empty. For these cases this method returns True. Doing getcell() on an empty cell results in an exception.

Note that an empty cell is not the same as an empty array. A cell can contain an empty array (of any dimensionality) as a value.

Also note that a cell in a column containing scalars or fixed shaped arrays cannot be empty.

ismultiused(checksubtables=False)¶

Tell if the table is used in other processes.

checksubtables=True means it will also check it for subtables.

isscalarcol(columnname)¶: Tell if the column contains scalar values.

isvarcol(columnname)¶: Tell if the column holds variable shaped arrays.

iswritable()¶: Return if the table is writable.

iter(columnnames, order='', sort=True)¶

Return a tableiter object.

tableiter lets one iterate over a table by returning in each iteration step a reference table containing equal values for the given columns. By default a sort is done on the given columns to get the correct iteration order.

order: ‘ascending’ is iterate in ascending order (is the default).

‘descending’ is iterate in descending order.
sort=False: do not sort (because table is already in correct order).

For example, iterate by time through a measurementset table:

t = table('3c343.MS')
for ts in t.iter('TIME'):
  print ts.nrows()

keywordnames()¶: Get the names of all table keywords.

lock(write=True, nattempts=0)¶

Acquire a read or write lock on a table.

write=False means a read lock, otherwise a write lock. | nattempts defines the nr of attempts (one attempt per second) to do before giving up. The default 0 means unlimited. An exception is thrown if no lock could be acquired.

If the table has already been locked appropriately, nothing will be done. Thus locks do NOT nest.

lockoptions()¶

Return the lockoptions.

They are returned as a dict with fields:

‘option’: the locking mode (user, usernoread, auto, autonoread, permanent, permanentwait).
interval: In case of AutoLocking the inspection interval defines how often the table system checks if another process needs a lock on the table.
maxwait: the maximum time to wait when acquiring a lock in AutoLocking mode.

name()¶: Return the table name.

ncols()¶: Return the number of columns in the table.

nrows()¶: Return the number of rows in the table.

partnames(recursive=False)¶

Return the names of the tables this table consists of.

A table can be a reference to another table (e.g. for a selection) or a concatenation of other tables. This function returns the names of such table parts. For a plain table it simply returns the name of that table.

In its turn a table part can be a reference or concatenated table. recursive=True means that it follows table parts until the end.

putcell(columnname, rownr, value)¶

Put a value into one or more table cells.

The columnname and (0-relative) rownrs indicate the table cells. rownr can be a single row number or a sequence of row numbers. If multiple rownrs are given, the given value is put in all those rows.

The given value has to be convertible to the data type of the column. If the column contains scalar values, the given value must be a scalar. The value for a column holding arrays can be given as:

a scalar resulting in a 1-dim array of 1 element
a sequence (list, tuple) resulting in a 1-dim array
a numpy array of any dimensionality

Note that the arrays in a column may have a fixed dimensionality or shape. In that case the dimensionality or shape of the array to put has to conform.

putcellslice(columnname, rownr, value, blc, trc, inc=[])¶

Put into a slice of a table cell holding an array.

The columnname and (0-relative) rownr indicate the table cell. Unlike putcell only a single row can be given.

The slice to put is defined by the blc, trc, and optional inc arguments. (blc = bottom-left corner, trc=top-right corner, inc=stride). Not all axes have to be filled in for blc, trc, and inc. Missing axes default to begin, end, and 1. A negative blc or trc defaults to begin or end. Note that trc is inclusive (unlike python indexing).

As in putcell the array can be given by a scalar, sequence, or numpy array. The shape of the array to put has to match the slice shape.

putcol(columnname, value, startrow=0, nrow=-1, rowincr=1)¶

Put an entire column or part of it.

If the column contains scalar values, the given value should be a 1-dim array. Otherwise it is a numpy array where the first axis is formed by the column cells.

The column can be sliced by giving a start row (default 0), number of rows (default all), and row stride (default 1).

putcolkeyword(columnname, keyword, value, makesubrecord=False)¶

Put the value of a column keyword.

It is similar to putkeyword().

putcolkeywords(columnname, value)¶

Put the value of multiple keywords in a column.

The value has to be a dict, so each field in the dict is a keyword. It puts all keywords similar to putkeyword().

putcolslice(columnname, value, blc, trc, inc=[], startrow=0, nrow=-1, rowincr=1)¶

Put into a slice in a table column holding arrays.

Its arguments are the same as for getcolslice and putcellslice.

putinfo(value)¶

Put the table info.

The table info is a dict containing the fields:

putkeyword(keyword, value, makesubrecord=False)¶

Put the value of a table keyword.

The value of a keyword can be a:

scalar which can be given a normal python scalar or numpy scalar.
an array which can be given as a numpy array. A 1-dimensional array can also be given as a sequence (tuple or list).
a reference to a table which can be given as a table object or as a string containing its name prefixed by ‘Table :’.
a struct which can be given as a dict. A struct is fully nestable, thus each field in the dict can be one of the values described here. The only exception is that a table value can only be given by the string.

If the keyword already exists, the type of the new value should match the existing one (e.g. a scalar cannot be replaced by an array).

Similar to method getkeyword() a keyword name can be given consisting of multiple parts separated by dots. This represents nested structs, thus puts the value into a field in a struct (in a struct, etc.). If makesubrecord=True structs will be created for the keyword name parts that do not exist.

Instead of a keyword name an index can be given which returns the value of the i-th keyword.

putkeywords(value)¶

Put the value of multiple table keywords.

The value has to be a dict, so each field in the dict is a keyword. It puts all keywords similar to putkeyword().

putvarcol(columnname, value, startrow=0, nrow=-1, rowincr=1)¶

Put an entire column or part of it.

It is similar to putcol, but the shapes of the arrays in the column can vary. The value has to be a dict of numpy arrays.

The column can be sliced by giving a start row (default 0), number of rows (default all), and row stride (default 1).

query(query='', name='', sortlist='', columns='', limit=0, offset=0, style='Python')¶

Query the table and return the result as a reference table.

This method queries the table. It forms a TaQL command from the given arguments and executes it using the taql() function. The result is returned in a so-called reference table which references the selected columns and rows in the original table. Usually a reference table is temporary, but it can be made persistent by giving it a name. Note that a reference table is handled as any table, thus can be queried again.

All arguments are optional, but at least one of query, name, sortlist, and columns should be used. See the TaQL note for the detailed description of the the arguments representing the various parts of a TaQL command.

query: The WHERE part of a TaQL command.
name: The name of the reference table if it is to be made persistent.
sortlist: The ORDERBY part of a TaQL command. It is a single string in which commas have to be used to separate sort keys.
columns: The columns to be selected (projection in data base terms). It is a single string in which commas have to be used to separate column names. Apart from column names, expressions can be given as well.
limit: If > 0, maximum number of rows to be selected.
offset: If > 0, ignore the first N matches.
style: The TaQL syntax style to be used (defaults to Python).

removecolkeyword(columnname, keyword)¶

Remove a column keyword.

It is similar to removekeyword().

removecols(columnnames)¶

Remove one or more columns.

Note that some storage managers (in particular the tiled ones) do not allow the removal of one of its columns. In that case all its columns have to be removed together.

Columns can always be removed from a reference table. It does NOT remove the columns from the referenced table.

removekeyword(keyword)¶

Remove a table keyword.

Similar to getkeyword() the name can consist of multiple parts. In that case a field in a struct will be removed.

Instead of a keyword name an index can be given which removes the i-th keyword.

removerows(rownrs)¶

Remove the given rows from the table.

The row numbers can be given in a sequence in any order. The rows will be removed from the end of the table towards the beginning. This is needed because the removal of a row decrements the row number of higher rows.

Thus:

t.removerow ([10,20])

is different from:

t.removerow(10)
t.removerow(20)

because in the latter row 20 was row 21 before the removal of row 10.

Some storage managers (in particular the tiled ones) do not allow removal of rows, so the operation may fail.

Rows can always be removed from a reference table. It does NOT remove the rows from the referenced table.

rename(newtablename)¶

Rename the table.

It renames the table and, if needed, adjusts the names of its subtables.

renamecol(oldname, newname)¶

Rename a single table column.

Renaming a column in a reference table does NOT rename the column in the referenced table.

resync()¶

Resync the table object with the file contents.

Usually concurrent access is handled by acquiring read and write locks. However, a table can be opened without the need for read locking using lock option usernoread or autonoread. in that case synchronization of the table object and actual file contents can be done manually using this method.

row(columnnames=[], exclude=False)¶

Return a tablerow object which includes (or excludes) the given columns.

tablerow makes it possible to get/put values in one or more rows.

rownumbers(table=None)¶

Return a list containing the row numbers of this table.

This method can be useful after a selection or a sort. It returns the row numbers of the rows in this table with respect to the given table. If no table is given, the original table is used.

For example:

t = table('W53.MS')
t1 = t.selectrows([1,3,5,7,9])  # select a few rows
t1.rownumbers(t)
# [1 3 5 7 9]
t2 = t1.selectrows([2,5])       # select rows from the selection
t2.rownumbers(t1)
# [2 5]                         # rownrs of t2 in table t1
t2.rownumbers(t)
# [3 9]                         # rownrs of t2 in t
t2.rownumbers()
# [3 9]

The last statements show that the method returns the row numbers referring to the given table. Table t2 contains rows 2 and 5 in table t1, which are rows 3 and 9 in table t.

select(columns, name='', style='Python')¶

Select columns and return the result as a reference table.

This method represents the SELECT part of a TaQL command using the given columns (or column expressions). It forms a TaQL command from the given arguments and executes it using the taql() function. The result is returned in a so-called reference table which references the columns and rows in the original table. Usually a reference table is temporary, but it can be made persistent by giving it a name. Note that a reference table is handled as any table, thus can be queried again.

columns: The columns to be selected (projection in data base terms). It is a single string in which commas have to be used to separate column names. Apart from column names, expressions can be given as well.
name: The name of the reference table if it is to be made persistent.
style: The TaQL syntax style to be used (defaults to Python).

selectrows(rownrs)¶: Return a reference table containing the given rows.

setdmprop(name, properties, bycolumn=True)¶

Set properties of a data manager.

Properties (e.g. cachesize) of a data manager can be changed by defining them appropriately in the properties argument (a dict). Current values can be obtained using function getdmprop() which also serves as a template. The dict can contain more fields; only the fields with the names as returned by getdmprop are handled.

The data manager can be specified in two ways: by data manager name or by the name of a column using the data manager. The argument bycolumn defines which way is used (default is by column name).

setmaxcachesize(columnname, nbytes)¶

Set the maximum cache size for the data manager used by the column.

It can sometimes be useful to limit the size of the cache used by a column stored with the tiled storage manager. This method requires some more knowledge about the table system and is not meant for the casual user.

showstructure(dataman=True, column=True, subtable=False, sort=False)¶

Show table structure in a formatted string.

The structure of this table and optionally its subtables is shown. It shows the data manager info and column descriptions. Optionally the columns are sorted in alphabetical order.

dataman: Show data manager info? If False, only column info is shown. If True, data manager info and columns per data manager are shown.
column: Show column description per data manager? Only takes effect if dataman=True.
subtable: Show the structure of all subtables (recursively). The names of subtables are always shown.
‘sort’: Sort the columns in alphabetical order?

sort(sortlist, name='', limit=0, offset=0, style='Python')¶

Sort the table and return the result as a reference table.

This method sorts the table. It forms a TaQL command from the given arguments and executes it using the taql() function. The result is returned in a so-called reference table which references the columns and rows in the original table. Usually a reference table is temporary, but it can be made persistent by giving it a name. Note that a reference table is handled as any table, thus can be queried again.

sortlist: The ORDERBY part of a TaQL command. It is a single string in which commas have to be used to separate sort keys. A sort key can be the name of a column, but it can be an expression as well.
name: The name of the reference table if it is to be made persistent.
limit: If > 0, maximum number of rows to be selected after the sort step. It can, for instance, be used to select the N highest values.
offset: If > 0, ignore the first offset matches after the sort step.
style: The TaQL syntax style to be used (defaults to Python).

summary(recurse=False)¶

Print a summary of the table.

It prints the number of columns and rows, column names, and table and column keywords. If recurse=True it also prints the summary of all subtables, i.e. tables referenced by table keywords.

toascii(asciifile, headerfile='', columnnames=(), sep=' ', precision=(), usebrackets=True)¶

Write the table in ASCII format.

It is approximately the inverse of the from-ASCII-contructor.

asciifile: The name of the resulting ASCII file.
headerfile: The name of an optional file containing the header info. If not given or if equal to argument asciifile, the headers are written at the beginning of the ASCII file.
columnnames: The names of the columns to be written. If not given or if the first name is empty, all columns are written.
sep: The separator to be used between values. Only the first character of a string is used. If not given or mepty, a blank is used.
precision: For each column the precision can be given. It is only used for columns containing floating point numbers. A value <=0 means using the default which is 9 for single and 18 for double precision.
usebrackets: If True, arrays and records are written enclosed in []. Multi-dimensional arrays have [] per dimension. In this way variable shaped array can be read back correctly. However, it is not supported by tablefromascii(). If False, records are not written and arrays are written linearly with the shape defined in the header as supported byI tablefromascii().

Note that columns containing records or variable shaped arrays are ignored, because they cannot be written to ASCII. It is told which columns are ignored.

For example:

t  = table('3c343.MS')
t1 = t.query('ANTENNA1 != ANTENNA2')   # do row selection
t1.toascii ('3c343.txt')               # write selection as ASCII

unlock()¶

Unlock the table.

Flush the table data and release a read or write lock on the table acquired by lock(). Nothing will be done if the table is not locked.

view(wait=True, tempname='/tmp/seltable')¶

View a table using casaviewer, casabrowser, or wxwidget based browser.

The table is viewed depending on the type:

MeasurementSet: is viewed using casaviewer.
Image: is viewed using casaviewer.
other: are browsed using the browse() function.

If the casaviewer cannot be found, all tables are browsed.

The casaviewer can only display tables that are persistent on disk. This gives problems for tables resulting from a query because they are held in memory only (unless an output table name was given).

To make viewing of such tables possible, the argument tempname can be used to specify a table name that will be used to form a persistent table that can be browsed. Note that such a table is very small as it does not contain data, but only references to rows in the original table. The default for tempname is ‘/tmp/seltable’.

If needed, the table can be deleted using the tabledelete() function.

If wait=False, the casaviewer is started in the background. In that case the user should delete a possibly created copy of a temporary table.

Class `tables.tablecolumn`¶

class casacore.tables.tablecolumn(table, columnname)¶

The Python interface to a column in a Casacore table.

The tablecolumn class is a convenience class to access data in a table column. All functionality provided in this class is available in table, but tablecolumn is more convenient to use because the column name does not have to be given over and over again.

For example:

t = table('3C343.MS')
tc = tablecolumn(t, 'DATA')
# tc = t.col('DATA')           # another way to construct a tablecolumn
tc.getcell(0)                  # get data from cell 0

As can be seen in the example table.col() offers a slightly more convenient way to create a tablecolumn object.

A tablecolumn can be indexed using Python’s [] operator. Negative start, end, and stride is possible. For example:

tc[0]               # get cell 0
tc[:5]              # get cell 0,1,2,3,4
tc[-5,-1,]          # get last 4 cells
tc[-1,-5,-1]        # get last 4 cells in reversed order
tc[1] = tr[0]       # put value of cell 0 into cell 1

The tablecolumn class supports the context manager idiom (__enter__ and __exit__). When used in a with statement, the table changes will be flushed automatically, which is handy when writing to the table column. For example:

with t.SPECTRAL_WINDOW_ID as tc:
  tc.putcell (0, 0)

arraytype()¶: Get the array type of a column holding arrays. (see table.colarraytype())

datatype()¶: Get the data type of the column. (see table.coldatatype())

fieldnames(keyword='')¶: Get the names of the fields in a column keyword value. (see table.colfieldnames())

getcell(rownr)¶: Get data from a column cell. (see table.getcell())

getcellslice(rownr, blc, trc, inc=[])¶: Get a slice from a column cell holding an array. (see table.getcellslice())

getcol(startrow=0, nrow=-1, rowincr=1)¶: Get the contents of the column or part of it. (see table.getcol())

getcolslice(blc, trc, inc=[], startrow=0, nrow=-1, rowincr=1)¶: Get a slice from a table column holding arrays. (see table.getcolslice())

getdesc()¶: Get the description of the column. (see table.getcoldesc())

getdminfo()¶: Get data manager info of the column. (see table.getdminfo())

getkeyword(keyword)¶: Get the value of a column keyword. (see table.getcolkeyword())

getkeywords()¶: Get the value of all keywords of the column. (see table.getcolkeywords())

getshapestring(startrow=1, nrow=-1, rowincr=1)¶: Get the shapes of all cells in the column in string format. (see table.getcolshapestring())

getvarcol(startrow=0, nrow=-1, rowincr=1)¶: Get the contents of the column or part of it. (see table.getvarcol())

index(sort=True)¶: Return a tableindex object on this column.

iscelldefined(rownr)¶: Tell if a column cell contains a value. (see table.iscelldefined())

isscalar()¶: Tell if the column contains scalar values.

isvar()¶: Tell if the column holds variable shaped arrays.

iter(order='', sort=True)¶: Return a tableiter object on this column.

keywordnames()¶: Get the names of all keywords of the column.

name()¶: Get the name of the column.

nrows()¶: Get number of cells in the column.

putcell(rownr, value)¶: Put a value into one or more table cells. (see table.putcell())

putcellslice(rownr, value, blc, trc, inc=[])¶: Put into a slice of a table cell holding an array. (see table.putcellslice())

putcol(value, startrow=0, nrow=-1, rowincr=1)¶: Put an entire column or part of it. (see table.putcol())

putcolslice(value, blc, trc, inc=[], startrow=0, nrow=-1, rowincr=1)¶: Put into a slice in a table column holding arrays. (see table.putcolslice())

putkeyword(keyword, value, makesubrecord=False)¶: Put the value of a column keyword. (see table.putcolkeyword())

putkeywords(value)¶: Put the value of multiple table keywords. (see table.putcolkeywords())

putvarcol(value, startrow=0, nrow=-1, rowincr=1)¶: Put an entire column or part of it. (see table.putvarcol())

removekeyword(keyword)¶: Remove a column keyword. (see table.removecolkeyword())

table()¶: Get the table object this column belongs to.

Class `tables.tablerow`¶

class casacore.tables.tablerow(table, columnnames=[], exclude=False)¶

The Python interface to Casacore table rows.

A table row is a record (dict) containing the values of a single row for one or more columns in a table. In constructing the tablerow object, one can specify which columns are to be included or excluded. By default all columns will be used, but if the table is writable, only writable columns will be used.

A tablerow object can easily be constructed using table.row().

One or more rows can be read or written using the standard python indexing syntax where (negative) strides are possible. For example:

t = table (‘3c343.MS’) tr = t.row ([‘ANTENNA1’, ‘ANTENNA2’, ‘ARRAY_ID’]) tr[0] # get row 0 tr[:5] # get row 0,1,2,3,4 tr[-5,-1,] # get last 4 rows tr[-1,-5,-1] # get last 4 rows in reversed order tr[1] = tr[0] # put values of row 0 into row 1

Note that the last line will fail because the table is opened readonly. The argument readonly=False is needed in the table constructor to make it work.

The tablerow class supports the context manager idiom (__enter__ and __exit__). When used in a with statement, the table changes will be flushed automatically, which is handy when writing to table rows. For example:

with t.row() as tr:
  tr.put (1, tr.get(0))   # copy row 0 to row 1

get(rownr)¶: Get the contents of the given row.

iswritable()¶: Tell if all columns in the row object are writable.

put(rownr, value, matchingfields=True)¶

Put the values into the given row.

The value should be a dict (as returned by method get(). The names of the fields in the dict should match the names of the columns used in the tablerow object.

matchingfields=True means that the value may contain more fields and only fields matching a column name will be used.

Class `tables.tableiter`¶

class casacore.tables.tableiter(table, columnnames, order='', sort=True)¶

The Python interface to Casacore table iterators

A tableiter allows iteration through a table based on the contents of one or more columns. Each step in the iteration process forms a subset of the table for which the specified columns have the same value.

It can easily be constructed using the table.iter() method as done in the example below:

t = table('3c343.MS')
for ts in t.iter('ANTENNA1'):
  print ts.nrows()

In this example ts will be a so-called reference table which can be operated on like any other table object.

Multiple column names should be given in a sequence (tuple or list).

next()¶

reset()¶: Reset the iterator to the beginning.

Class `tables.tableindex`¶

class casacore.tables.tableindex(table, columnnames, sort=True)¶

The Python interface to Casacore table index

A tableindex makes it possible to find rows in a table based on the contents of one or more columns. When constructing the tableindex it has to be specified for which column or columns an index has to be built. Those columns will be loaded in memory and thereafter row numbers can be found in a fast way using a binary search.

Using a table index is only useful if many searches will be done in the table. For a single or few searches it is better to query the table using method table.query().

Normally an index will be build on one or more scalar columns (e.g. on ANTENNA1 and ANTENNA2 in a measurementset table). However, it is also possible to buo.d an index for a column containing arrays (e.g. for a column where each cell can contain multiple names. In that case only a single column can be indexed.

The index can be unique, but does not need to be. A unique index can be asked for the row number containing a given key. A non-unique index can only be asked for the row numbers containing a key. The returned sequence can thereafter be used in table.selectrows() to form that subset of the table.

tableindex supports Python’s index operator [] as explained in the methods rownr() and rownrs().

colnames()¶: Return the column names the index is made of.

isunique()¶: Tell if all keys in the index are unique.

rownr(key)¶

Get the unique row number containing the key.

If the index is made from a single column, the keycan be given as a single value. Otherwise the key has to be given as a dict where the name of each field in the dict should correspond with the column name in the index.

For example:

t = table('3c343.MS/ANTENNA')
tinx = t.index ('NAME')        # build index for antenna name
rownr = tinx.rownr('RTE')      # find an antenna by name
rownr = tinx['RTE']            # same as above
t.getcell ('POSITION', rownr)  # get position of that antenna

As shown in the example above the python index operator can also be used to find a row number if the index if made of a single column.

An exception will be raised if the index is not unique. In that case method rownrs() should be used instead.

rownrs(key, upperkey={}, lowerincl=True, upperincl=True)¶

Get a sequence of row numbers containing the key(s).

A single key can be given, but by giving argument upperkey as well a key range can be given (where upper key must be > lower). One can specify if the lower and upper key should be part of the range (incl=True) or not. By default both keys are part of the range.

The key and optional upper key have to be given in the same way as for method rownr().

Similar to method rownr(). python’s index operator [] can be used if the index consists of a single column. However, in this case only key ranges can be used (because the index operator with a single key returns a single row number, thus can only be used for unique indices). The lower key is inclusive, but the upper key is exclusive conform the standard python index semantics.

For example:

t = table('3c343.MS')
tinx = t.index ('ANTENNA1')    # build index for antenna name
rownr = tinx.rownr(0)          # find antenna1 = 0
rownr = tinx[0:1]              # same as above

setchanged(columnnames=[])¶

Tell the index that data has changed.

The index is smart enough to detect that the number of rows in the indexed table has changed. However, it cannot detect if a value in a column contained in this inex has changed. So it has to be told explicitly.

columnnames: The names of the columns in which data have changed. Giving no names means that all columns in the index have changed.

Module tables¶

Table utility functions¶

MeasurementSet utility functions¶

Utility functions details¶

Class tables.table¶

Class tables.tablecolumn¶

Class tables.tablerow¶

Class tables.tableiter¶

Class tables.tableindex¶

Module `tables`¶

Class `tables.table`¶

Class `tables.tablecolumn`¶

Class `tables.tablerow`¶

Class `tables.tableiter`¶

Class `tables.tableindex`¶