table

class table

Access tables from casapy

table is the tool that contains all the functions relevant for table handling.

Methods Summary

addcols	!!!REQUIRES COLUMN DESCRIPTION FUNCTIONS THAT HAVE NOT BEEN IMPLEMENTED!!! add one or more columns
addreadmeline	add a readme line to the info record
addrows	add a specified number of rows
browse	browse a table using a graphical browser
calc	TaQL expression with calc to calculate an expression on a table
clearlocks	Clears any table lock associated with the current process
close	close the table tool
colarraytype	return the column array type
coldatatype	return the column data type
colfieldnames	get the names of fields in a keyword in a column
colkeywordnames	get the names of all keywords in a column
colnames	return the names of the columns
copy	copy a table
copyrows	copy rows from this table to another
create	create a new table
createmultitable	Create a virtually concatenated table
datachanged	has data changed in table?
done	end the table tool
endianformat	get the endian format used for this table
fieldnames	get the names of fields in a table keyword
flush	flush the current contents to disk
fromASDM	Create an CASA table from an ASDM table
fromascii	Create a casatable from a file containing data in ASCII format
fromfits	Create a casatable from a binary FITS file
getcell	get a specific cell
getcellslice	get a slice from a specific cell
getcol	get a specific column
getcoldesc	get the description of a specific column
getcolkeyword	get value of specific column keyword
getcolkeywords	get values of all keywords for a column
getcolshapestring	get shape of arrays in a specific column
getcolslice	array
getdesc	get the table description
getdminfo	get the info about data managers
getkeyword	get value of specific table keyword
getkeywords	get values of all table keywords
getvarcol	get a specific column (for variable arrays)
haslock	has this process a lock on the table?
info	get the info record
iscelldefined	test if a specific cell contains a value
ismultiused	is the table in use in another process?
isopened	Is the table name open in this process
isscalarcol	is the specified column scalar?
isvarcol	tell if column contains variable shaped arrays
iswritable	is the table writable?
keywordnames	get the names of all table keywords
listlocks	Lists any table lock associated with the current process
lock	acquire a lock on the table
lockoptions	get the lock options used for this table
name	return name of table on disk
ncols	return number of columns
nrows	return number of rows
ok	Is the table tool ok?
open	open an existing table
putcell	put a specific cell
putcellslice	put a slice into a specific cell
putcol	put a specific column
putcolkeyword	put a specific keyword for a column
putcolkeywords	put multiple keywords for a column
putcolslice	put a slice into a specific column
putinfo	set the info record
putkeyword	put a specific table keyword
putkeywords	!!!BROKEN!!! put multiple table keywords
putvarcol	put a specific column (for variable arrays)
query	Make a table from a query applied to the current table.
removecolkeyword	remove a specific keyword for a column
removecols	remove one or more columns
removekeyword	remove a specific table keyword
removerows	remove the specified rows
renamecol	rename a column
resync	resync the table tool with table file
rownumbers	!!!INPUT PARAMETERS IGNORED!!! return the row numbers in the (reference) table
selectrows	Make a table from a selection of rows
setmaxcachesize	set maximum cache size for column in the table
showcache	show the contents of the table cache
statistics	Get statistics on the selected table column
summary	summarize the contents of the table
table	Construct table tool
taql	Make a table from a TaQL command.
testincrstman	Checks consistency of an Incremental Store Manager bucket layout
toasciifmt	Write casatable into an ASCII format
unlock	unlock and flush the table

addcols(desc='', dminfo='')

!!!REQUIRES COLUMN DESCRIPTION FUNCTIONS THAT HAVE NOT BEEN IMPLEMENTED!!! add one or more columns

Columns can be added to a table that was opened nomodify=False. The new columns will be filled with a default value (0 or blank).

!!!THESE COLUMN DESCRIPTION FUNCTIONS HAVE NOT BEEN IMPLEMENTED!!! For each column to be added a column description has to be setup using function tablecreatescalarcoldesc or tablecreatearraycoldesc. When multiple columns are used, they have to be combined in a single record using tablecreatedesc. It is possible to specify data manager info in order to define a data manager (storage manager or virtual column engine) for the columns to be added.

Parameters

• desc (record='') - Description of one or more columns

• dminfo (record='') - Optional description data manager to use

addreadmeline(value='')

add a readme line to the info record

A readme line is part of the info record associated with a table. It is to inform the user, and is not used by any application directly.

Parameters

• value (string='') - readme line

addrows(nrow=1)

add a specified number of rows

Rows can be added to the end of a table that was opened nomodify=False. The new rows are empty.

Parameters

• nrow (int=1) - Number of rows to add

browse()

browse a table using a graphical browser

To start the browser, the environment variable DISPLAY must be set.

calc(expr='', prefix='using style base0, endincl, fortranorder', showtaql=False)

TaQL expression with calc to calculate an expression on a table

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

The expression can be any expression that can be given in the WHERE clause of a SELECT expression (thus including subqueries). The given expression determines if the result is a scalar, a vector, or a record containing arrays. See the examples below.

Parameters

• expr (string='') - Expression string

• prefix (string='using style base0, endincl, fortranorder') - TaQL prefix for style and ordering etc …check TaQL note 199 for usage

• showtaql (bool=False) - Show the full taql command used

clearlocks()

Clears any table lock associated with the current process

Occasionally a table will be inretrievably locked to another process no matter how much closing is done.

So clearLocks will unlock all the files in the table cache that use AutoLocking.

close()

close the table tool

First a flush is done, then the table is closed inside casapy and is no longer available for use.

colarraytype(columnname='')

return the column array type

The possible column array types are defined as: egin{description} item[FixedShape] FixedShape means that the shape of the array must be the same in each cell of the column. If not given, the array shape may vary. Option Direct forces FixedShape. item[Direct] Direct means that the data is directly stored in the table. Direct forces option FixedShape. If not given, the array is indirect, which implies that the data will be stored in a separate file. end{description}

Parameters

• columnname (string='') - Name of column

coldatatype(columnname='')

return the column data type

A column may contain various data types. This tool function returns the type of the column as a string.

Parameters

• columnname (string='') - Name of column

colfieldnames(columnname='', keyword='')

get the names of fields in a keyword in a column

This function returns a vector of strings containing the names of all fields in the given keyword in the given column. It is only valid if the keyword value is a record. If no keyword name is given, the names of all keywords in the column are returned.

Parameters

• columnname (string='') - column name

• keyword (string='') - keyword name

colkeywordnames(columnname='')

get the names of all keywords in a column

This function returns a vector of strings containing the names of all keywords in the column with the given name..

Parameters

• columnname (string='') - column name

colnames()

return the names of the columns

The names of the columns in the table are returned as a vector of Strings.

copy(newtablename='', deep=False, valuecopy=False, dminfo='', endian='aipsrc', memorytable=False, returnobject=False, norows=False)

copy a table

Copy the table. All subtables are also copied. References to another table are preserved.

The argument exttt{deep} determines how a reference table (i.e. the result of a query) is copied. By default a file copy is made, thus the resulting table still contains references and no actual data. If, however, exttt{deep=True} is given, a deep copy is made which means that the actual data are copied. Also all subtables are copied. Normally a plain table is copied by copying the files. However, if exttt{deep=True} and exttt{valuecopy=True} are given, a plain table is copied by copying all its values and subtables. This is useful to reorganize the tables, i.e. to regain file space that is wasted by frequent updates to a table. The argument exttt{dminfo} can be used to specify explicit data manager info for the columns in the new plain table. It can be used to change, for example, a storage manager from IncrStMan to StandardStMan. The exttt{dminfo} is a record as returned by the getdminfo If exttt{dminfo} is a non-empty record, it forces exttt{valuecopy=True}.

The standard operation is make the copy to a plain table. It is, however, possible to copy to a memory table by giving exttt{memorytable=True}.

The endian format for the newly created table can be specified. This is only meaningful if a deep copy is made to a plain table. The possible values are: - big: big endian format (as used on e.g. SUN) - little: little endian format (as used on e.g. PC) - local: use the endian format of the machine being used - aipsrc: use the endian format specified in aipsrc variable table.endianformat (which defaults to big). The default is aipsrc.

Normally the exttt{copy} function only copies the table and does not create a new table tool object. The user can do that by opening the newly created table in the standard way. However, it is possible to get an object back by using exttt{returnobject=True}. An object is always returned if the copy is made to a memory table.

Parameters

• newtablename (string='') - Name of newtable on disk

• deep (bool=False) - Make a deep copy of a reference table?

• valuecopy (bool=False) - Make a deep copy of any table?

• dminfo (record='') - Data manager info for new table

• endian (string='aipsrc') - Endian format of new table

• memorytable (bool=False) - Hold new table in memory?

• returnobject (bool=False) - Return a tool object for the new table

• norows (bool=False) - Don’t copy any rows (useful for copying only the table structure)

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

copy rows from this table to another

Copy rows from this table to another. By default all rows of this table are appended to the output table. It is possible though to control which rows are copied. Rows are added to the output table as needed. Because no rows can be added to a reference table, it is only possible to overwrite existing rows in such tables.

Only the data of columns existing in both tables will be copied. Thus by making a reference table consisting of a few columns, it is possible to copy those columns only.

Parameters

• outtable (string='') - table object of output table

• startrowin (int=0) - First row to take from input table

• startrowout (int=-1) - First row to write in output table, -1 (=end)

• nrow (int=-1) - Nr of rows to copy, -1 (=all)

create(tablename='', tabledesc='', lockoptions='default', endianformat='', memtype='', nrow=0, dminfo='')

create a new table

Create a new casaTable.

Most of the time you just need to specify the table’s name and a description of its format.

A table can be shared by multiple processes by using the appropriate locking options. The possible options are: - auto: let the system take care of locking. At regular time intervals these autolocks are released to give other processes the opportunity to access the table. - 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 tool is not synchronized with the table file (as is normally done when a lock is acquired). The function exttt{resync} can be used to explicitly synchronize the table tool - 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 lock; the constructor fails when the table is already in use in another process - permanentwait: as above, but wait until the other process releases its lock - 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. When auto locking is used, it is possible to give a record containing the fields option, interval, and/or maxwait. In this way advanced users have full control over the locking options. In practice this is hardly ever needed.

Parameters

• tablename (string='')

• tabledesc (record='') - description of the table’s format

• lockoptions (record='default') - locking to be used

• endianformat (string='')

• memtype (string='')

• nrow (int=0)

• dminfo (record='') - Data Manager information

createmultitable(outputTableName='', tables='', subdirname='')

Create a virtually concatenated table

Parameters

• outputTableName (string='') - name of the concatenated table

• tables (stringArray='') - list of the names of the tables to be concatenated

• subdirname (string='') - optional name of the subdirectory into which the input tables are moved

datachanged()

has data changed in table?

This function tests if data in the table have changed (by another process) since the last call to this function.

done()

end the table tool

Effectively a synonym for function close.

endianformat()

get the endian format used for this table

Get the endian format used for this table. It returns a string with value ‘big’ or ‘little’.

fieldnames(keyword='')

get the names of fields in a table keyword

This function returns a vector of strings containing the names of all fields in the given table keyword. It is only valid if the keyword value is a record. If no keyword name is given, the names of all table keywords are returned.

Parameters

• keyword (string='') - keyword name

flush()

flush the current contents to disk

Until a flush is performed, the results of all operations are not reflected in any change to the disk file. Hence you {em must} do a flush to write the changes to disk.

fromASDM(tablename='', xmlfile='')

Create an CASA table from an ASDM table

.keywords DATE A “07/7/23” REVISION D 0 AUTHOR A “Paulo C. Cortes” INSTRUMENT A “ALMA” .endkeywords

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 implement the task. The asdmCasaSaxHandler encapsulate all the operations returning a reference to a CASA::Table. The class uses xerces-c to parse the XML table and creates the CASA::Table. The implementation assumes the integrity of the XML data, it not attempting to check whether the XML data meets a column format or not. In detail, an ArrayString column should agree with the following format: nd nx … data, where nd is the number of dimensions, nx is the size of the first dimension (implemented upto a cube, i.e. nx,ny,nz), and data is the array itself which should have the appropiate number of elements. For example, a VectorString column could be: 1 2 “I” “Q” or dimension 1, size 2, and two string elements. Due to the lack of data type spefication in the XML tables, the column names are hardcoded into the asdmCasaSaxHandler based on the ASDM specification (see http://aramis.obspm.fr/~alma/ASDM/ASDMEntities/index.html). While missing data from a table column will be accepted by the task, any new column beyond the specification has to be added into the class, also, any change in data types form the specificatin will produce a crash, CASA is picky with data types integrity. So far, the list of tables included in the class is:

AlmaCorrelatorMode.xml, Antenna.xml ConfigDescription.xml, DataDescription.xml, ExecBlock.xml, Feed.xml, Field.xml, Main.xml, Polarization.xml, Processor.xml, Receiver.xml, SBSummary.xml, Scan.xml, Source.xml, SpectralWindow.xml, State.xml, Station.xml, Subscan.xml, SwitchCycle.xml, CalCurve.xml, CalData.xml, CalPhase.xml

more tables will follow. The usage of fromASDM is simple, it gets two string, tablename and xmlfile, where tablename is the CASA::Table to be written and xmlfile represents the ASDM XML table. To call it do: tb.fromasdm(tablename,xmlfile)

Parameters

• tablename (string='') - Name of table to be created

• xmlfile (string='') - Name of the XML file to be read

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

Create a casatable from a file containing data in ASCII format

Create a table from an ASCII file. 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 by the table tool.

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 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.

In automatic mode ( exttt{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 exttt{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 exttt{Column1}, exttt{Column2}, etc.. For example: egin{enumerate} item

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

are to be stored as scalar columns. item

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

a variable length vector. item

exttt{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. item

exttt{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. end{enumerate}

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:

egin{enumerate} item The first line contains the names of the columns. These names may be enclosed in quotes (either single or double). item The second line contains the data type and optionally the shape of each column. Valid types are: egin{itemize} item S for Short data item I for Integer data item R for Real data item D for Double Precision data item X for Complex data (Real followed by Imaginary) item Z for Complex data (Amplitude then Phase) item DX for Double Precision Complex data (Real followed by Imaginary) item DZ for Double Precision Complex data (Amplitude then Phase) item A for ASCII data (a value must be enclosed in single or double quotes

if it contains whitespace)

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

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

end{itemize} end{enumerate} If a column is an array, the shape has to be given after the data type without any whitespace. E.g. exttt{I10} defines an integer vector of length 10. exttt{A2,5} defines a 2-dim string array with shape [2,5]. Note that exttt{I} is not the same as exttt{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:

egin{verbatim} 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 “” end{verbatim} 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 casa:

egin{verbatim} U V W TIME ANT1 ANT2 DATA R R R D I I X1,0 end{verbatim}

The data file would then look like:

egin{verbatim} 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 end{verbatim} 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, {em 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). Between these two lines each line should contain the following as listed below. A table keywordset and column keywordsets can be specified. The latter can be specified by specifying the column name after the .keywords string.

egin{itemize} item The keyword name, e.g., ANYKEY item The datatype and optional shape of the keyword

(cf. list of valid types above)

item The value or values for the keyword (the keyword may contain a scalar or an array of values). e.g., 3.14159 21.78945 end{itemize}

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

egin{verbatim} .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 end{verbatim} 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 exttt{commentmarker}. It indicates that lines starting with the given marker are ignored. Note that the marker can be a regular expression (e.g. texttt{‘ *//’} tells that lines starting with // and optionally preceeded by blanks have to be ignored).

With the arguments exttt{firstline} and exttt{lastline} one can specify which lines have to be taken from the input file. A negative value means 1 for exttt{firstline} or end-of-file for exttt{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.

Parameters

• tablename (string='') - Name of table to be created

• asciifile (string='') - Name of ASCII file to be read

• headerfile (string='') - Name of an optional file defining the format

• autoheader (bool=False) - Determine header information automatically

• autoshape (intArray=[-1]) - Shape to be used if autoheader=True

• sep (string='') - Value separator

• commentmarker (string='') - Regex indicating comment line

• firstline (int=0) - First line to use

• lastline (int=-1) - Last line to use

• nomodify (bool=True) - Open Read-only?

• columnnames (stringArray=['']) - Column Names

• datatypes (stringArray=['']) - Data types

fromfits(tablename='', fitsfile='', whichhdu=1, storage='standard', convention='none', nomodify=True, ack=True)

Create a casatable from a binary FITS file

Create a table from binary FITS format. This generates a CASA table from the binary FITS table in the given HDU (header unit) of the FITS file. Note that other FITS formats ({em e.g.} Image FITS and UVFITS) are read by other means. It is possible to specify the storage manager to use for the table: exttt{standard} is the default storage manager. exttt{incremental} is efficient for slowly varying data. exttt{memort} is for in memory use for e.g to grab given columns via getcol.

Parameters

• tablename (string='') - Name of table to be created

• fitsfile (string='') - Name of FITS file to be read

• whichhdu (int=1) - Which HDU to read (0-relative to primary HDU i.e. 1 is the smallest valid value)

• storage (string='standard') - Storage manager to use (standard or incremental or memory)

• convention (string='none') - Convention to use (sdfits or none)

• nomodify (bool=True) - Open Read-only?

• ack (bool=True) - Acknowledge creations, etc

getcell(columnname='', rownr=0)

get a specific cell

A cell is the value at one row in one column. It may be a scalar or an array.

Parameters

• columnname (string='') - Name of column

• rownr (int=0) - Row number, starting at 0

getcellslice(columnname='', rownr='', blc='', trc='', incr=[1])

get a slice from a specific cell

A cell is the value at one row in one column. It must be an array. The slice must be specified as blc, trc with an optional stride. In blc and trc -1 can be used to indicate all values for a dimension (-1 in blc is equivalent to 0, so -1 is especially useful for trc).

Parameters

• columnname (string='') - Name of column

• rownr (int='') - Row number, starting at 0

• blc (intArray='') - Bottom left corner (e.g. [0,0,0] is start of 3D array)

• trc (intArray='') - Top right corner

• incr (intArray=[1]) - Stride (defaults to 1 for all axes)

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

get a specific column

The entire column (or part of it) is returned. Warning: it might be big! The functions can only be used if all arrays in the column have the same shape. That is guaranteed for columns containing scalars or fixed shaped arrays. For columns containing variable shaped arrays it only succeeds if all those arrays happen to have the same shape. Note that function exttt{getvarcol} can be used to get a column of arbitrary shaped arrays, which also handles empty cells correctly. Function exttt{isvarcol} tells if a column contains variable shaped arrays. shaped

Parameters

• columnname (string='') - Name of column

• startrow (int=0) - First row to read (default 0)

• nrow (int=-1) - Number of rows to read (default -1 means till the end)

• rowincr (int=1) - Increment in rows to read (default 1)

getcoldesc(columnname='')

get the description of a specific column

The column description is a casapy record that contains a complete description of the layout of a specified column (except for the number of rows). It can be used to construct a table description.

Parameters

• columnname (string='') - Name of column

getcolkeyword(columnname='', keyword='')

get value of specific column keyword

The value of the given column keyword is returned. The value can be of any type, including a record and a table. If a keyword is a table, its value is returned as a string containing the table name prefixed by ‘Table: ‘. It is possible that the value of a keyword is a record itself (arbitrarily deeply nested). A field in such a subrecord can be read by separating the name with dots.

Parameters

• columnname (string='') - Name of column

• keyword (variant='') - Name or seqnr of keyword: string or int

getcolkeywords(columnname='')

get values of all keywords for a column

The values of all keywords for the given column are returned. The values can be of any type, including a record and a table. If a keyword is a table, its value is returned as a string containing the table name prefixed by ‘Table: ‘.

Parameters

• columnname (string='') - Name of column

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

get shape of arrays in a specific column

The shapes of the arrays in the entire column (or part of it) are returned as strings like [20,3]. When the column contains fixed shaped arrays, a single string is returned. Otherwise a vector of strings is returned.

Parameters

• columnname (string='') - Name of column

• startrow (int=0) - First row to read (default 0)

• nrow (int=-1) - Number of rows to read (default -1 means till the end)

• rowincr (int=1) - Increment in rows to read (default 1)

getcolslice(columnname='', blc='', trc='', incr='', startrow=0, nrow=- 1, rowincr=1)

array

A slice from the entire column (or part of it) is returned. Warning: it might be big! In blc and trc -1 can be used to indicate all values for a dimension (-1 in blc is equivalent to 1, so -1 is especially useful for trc). Note that blc and trc should not contain the row number, only the blc and trc of the arrays in the column.

Parameters

• columnname (string='') - Name of column

• blc (intArray='') - Bottom left corner (e.g. [0,0,0] is start of 3D array)

• trc (intArray='') - Top right corner

• incr (intArray='') - Stride (defaults to 1 for all axes)

• startrow (int=0) - First row to read (default 0)

• nrow (int=-1) - Number of rows to read (default -1 means till the end)

• rowincr (int=1) - Increment in rows to read (default 1)

getdesc(actual=True)

get the table description

The table description is a casapy record that contains a complete description of the layout of the table (except for the number of rows). By default the actual table description is returned (thus telling the actual shapes and data managers used). It is also possible to get the table description used when creating the table.

Parameters

• actual (bool=True) - actual table description?

getdminfo()

get the info about data managers

This function returns the types and names of the data managers used. For each data manager it also returns the names of the columns served by it. The information is returned as a record containing a subrecord for each data manager. Each subrecord contains the fields TYPE, NAME and COLUMNS.

getkeyword(keyword='')

get value of specific table keyword

The value of the given table keyword is returned. The value can be of any type, including a record and a table. If a keyword is a table, its value is returned as a string containing the table name prefixed by ‘Table: ‘. It is possible that the value of a keyword is a record itself (arbitrarily deeply nested). A field in such a subrecord can be read by separating the name with dots.

Parameters

• keyword (variant='') - Name or seqnr of keyword: string or int

getkeywords()

get values of all table keywords

The values of all table keywords are returned. The values can be of any type, including a record and a table. If a keyword is a table, its value is returned as a string containing the table name prefixed by ‘Table: ‘.

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

get a specific column (for variable arrays)

Function exttt{getcol} can only used if values in the column cells to get have the same shape. Function exttt{getvarcol} addresses this limitation by returning the values as a record instead of an array. Each field in the record contains the value for a column cell. If the value is undefined (i.e. the cell does not contain a value), the unset value is put in the record. Each field name is the letter r followed by the row number. The length of the record is the number of rows to get. Note that the function exttt{isvarcol} tells if a column contains variable shaped arrays.

Parameters

• columnname (string='') - Name of column

• startrow (int=0) - First row to read (default 0)

• nrow (int=-1) - Number of rows to read (default -1 means till the end)

• rowincr (int=1) - Increment in rows to read (default 1)

haslock(write=True)

has this process a lock on the table?

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

Parameters

• write (bool=True) - Has it a write lock? (F=read lock)

info()

get the info record

The info record contains information on the table.

iscelldefined(columnname='', rownr=0)

test if a specific cell contains a value

A column containing variable shaped arrays can have an empty cell (if no array has been put into it). This function tests if a cell is defined (thus is not empty). Note that a scalar column and a fixed shape array column cannot have empty cells.

Parameters

• columnname (string='') - Name of column

• rownr (int=0) - Row number, starting at 0

ismultiused(checksubtables=False)

is the table in use in another process?

Is the table still in use in another process? If so, the table cannot be deleted.

Parameters

• checksubtables (bool=False) - check if subtables are multiused?)

isopened(tablename='')

Is the table name open in this process

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

Parameters

• tablename (string='') - table name to see if it is opened

isscalarcol(columnname='')

is the specified column scalar?

A column may contain either scalars or arrays in each cell. This tool function tests if the specified column has scalar contents.

Parameters

• columnname (string='') - Name of column

isvarcol(columnname='')

tell if column contains variable shaped arrays

This functions tells if the column contains variable shaped arrays. If so, the function exttt{getvarcol} should be used to get the entire column. Otherwise exttt{getcol} can be used.

Parameters

• columnname (string='') - Name of column

iswritable()

is the table writable?

Test if the table is opened for write.

keywordnames()

get the names of all table keywords

This function returns a vector of strings containing the names of all table keywords.

listlocks()

Lists any table lock associated with the current process

Occasionally a table will be inretrievably locked to another process no matter how much closing is done.

So listLocks will list the offending tables (and unoffending ones, too), so we can figure out where the problem might be.

lock(write=True, nattempts=0)

acquire a lock on the table

Try to acquire a read or write lock on the table. Nothing will be done if the table is already correctly locked by this process. It is only needed when user locking is used. When the lock is acquired, the internal caches will be synchronized with the (possibly changed) contents of the table. It is possible to specify the number of attempts to do (1 per second) in case the table is locked by another process. The default 0 is trying indefinitely.

Parameters

• write (bool=True) - Write lock? (F=read lock)

• nattempts (int=0) - Nr of attempts

lockoptions()

get the lock options used for this table

Get the lock options used for this table. It returns a record with the fields: option, interval and maxwait. The record can be used as the lockoptions argument when opening a table.

name()

return name of table on disk

Gives the name of the casatable on disk that the table tool has open.

ncols()

return number of columns

nrows()

return number of rows

Note that rows are numbered starting at 0.

ok()

Is the table tool ok?

Perform a number of sanity checks and return T if ok. Failure (returning F) is a sign of a bug.

open(tablename='', lockoptions='', nomodify=True)

open an existing table

Opens a disk file containing an existing casaTable.

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

A table can be shared by multiple processes by using the appropriate locking options. The possible options are: - auto: let the system take care of locking. At regular time intervals these autolocks are released to give other processes the opportunity to access the table. - 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 tool is not synchronized with the table file (as is normally done when a lock is acquired). The function exttt{resync} can be used to explicitly synchronize the table tool - 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 lock; the constructor fails when the table is already in use in another process - permanentwait: as above, but wait until the other process releases its lock - 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. When auto locking is used, it is possible to give a record containing the fields option, interval, and/or maxwait. In this way advanced users have full control over the locking options. In practice this is hardly ever needed.

Parameters

• tablename (string='')

• lockoptions (record='') - locking dictionary to be used : dict keys are ‘option’, ‘interval’, ‘maxwait’

• nomodify (bool=True)

putcell(columnname='', rownr='', thevalue='')

put a specific cell

A cell is the the value at one row in one column. It may be a scalar or an array.

Parameters

• columnname (string='') - Name of column

• rownr (intArray='') - Row number(s) (0-relative)

• thevalue (variant='') - Value

putcellslice(columnname='', rownr='', value='', blc='', trc='', incr=[1])

put a slice into a specific cell

A cell is the value at one row in one column. It must be an array. The slice must be specified as blc, trc with an optional stride. In blc and trc -1 can be used to indicate all values for a dimension (-1 in blc is equivalent to 0, so -1 is especially useful for trc).

Parameters

• columnname (string='') - Name of column

• rownr (int='') - Row number, starting at 0

• value (variant='') - Value

• blc (intArray='') - Bottom left corner (e.g. [0,0,0] is start of 3D array)

• trc (intArray='') - Top right corner

• incr (intArray=[1]) - Stride (defaults to 1 for all axes)

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

put a specific column

Parameters

• columnname (string='') - Name of column

• value (variant='') - Array

• startrow (int=0) - First row to put (default 0)

• nrow (int=-1) - Number of rows to put (default -1 means till the end)

• rowincr (int=1) - Increment in rows to put (default 1)

putcolkeyword(columnname='', keyword='', value='')

put a specific keyword for a column

Put a keyword in the given column. The value of the keyword can be a scalar or an array of any type or it can be a record. It is possible to define a keyword holding a subtable. In that case a special string containing the name of the subtable will be passed to the table client. It is possible that the value of a keyword is a record itself (arbitrarily deeply nested). A field in such a subrecord can be written by separating the name with dots. If a subrecord does not exist, an error is returned unless exttt{makesubrecord=True} is given. In such a case intermediate records are created when needed.

Parameters

• columnname (string='') - Name of column

• keyword (variant='') - Name or seqnr of keyword,string or int

• value (variant='') - Value of keyword

putcolkeywords(columnname='', value='')

put multiple keywords for a column

Put multiple keywords in the given column. All fields in the given record are put as column keywords. The value of each field can be a scalar or an array of any type or it can be a record. It is also possible to define a keyword holding a subtable. This can be done by giving the keyword a string value consisting of the subtable name prefixed by ‘Table: ‘.

Parameters

• columnname (string='') - Name of column

• value (record='') - Record of keyword=value pairs

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

put a slice into a specific column

In blc and trc, -1 can be used to indicate all values for a dimension (-1 in blc is equivalent to 0, so -1 is especially useful for trc). Note that blc and trc should not contain the row number, only the blc and trc of the arrays in the column.

Parameters

• columnname (string='') - Name of column

• value (variant='') - Array

• blc (intArray='') - Bottom left corner (e.g. [0,0,0] is start of 3D array)

• trc (intArray='') - Top right corner

• incr (intArray=[1]) - Stride (defaults to 1 for all axes)

• startrow (int=0) - First row to put (default 0)

• nrow (int=-1) - Number of rows to put (default -1 means till the end)

• rowincr (int=1) - Increment in rows to put (default 1)

putinfo(value='')

set the info record

The info record contains information on the table. It is written by applications, and used to determine what type of information is stored in a table.

Parameters

• value (record='') - Info record

putkeyword(keyword='', value='', makesubrecord=False)

put a specific table keyword

Put a table keyword. The value of the keyword can be a scalar or an array of any type or it can be a record. It is possible to define a keyword holding a subtable. In that case a special string containing the name of the subtable will be passed to the table client. It is possible that the value of a keyword is a record itself (arbitrarily deeply nested). A field in such a subrecord can be written by separating the name with dots. If a subrecord does not exist, an error is returned unless exttt{makesubrecord=True} is given. In such a case intermediate records are created when needed.

Parameters

• keyword (variant='') - Name or seqnr of keyword: string or int

• value (variant='') - Value of keyword

• makesubrecord (bool=False) - Create intermediate records

putkeywords(value='')

!!!BROKEN!!! put multiple table keywords

Put multiple table keywords. All fields in the given record are put as table keywords. The value of each field can be a scalar or an array of any type or it can be a record. It is also possible to define a keyword holding a subtable. This can be done by giving the keyword a string value consisting of the subtable name prefixed by ‘Table: ‘.

Parameters

• value (record='') - Record of keyword=value pairs

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

put a specific column (for variable arrays)

exttt{putcol} can only used if values in the column cells to put

have the same shape. exttt{putvarcol} addresses this limitation by passing the values as a record instead of an array. Each field in the record contains the value for a column cell. So the length of the record has to match the number of rows to put. If a value is the unset value, no put is done for that row.

Parameters

• columnname (string='') - Name of column

• value (record='') - Record with values

• startrow (int=0) - First row to put (default 0)

• nrow (int=-1) - Number of rows to put (default -1 means till the end)

• rowincr (int=1) - Increment in rows to put (default 1)

query(query='String', name='', sortlist='', columns='', style='')

Make a table from a query applied to the current table. It is possible to specify column(s) and/or expressions to sort on and to specify the columns to be contained in the output table. See the example below. A new “on-the-fly” table tool is returned. The new (reference) table can be given a name and will then be written to disk. Note that the resulting table is just a reference to the original table. One can make a deep copy of the query result using the copy function (see example).

Parameters

• query (string='String') - Query string

• name (string='') - Name of resulting reference table

• sortlist (string='') - Sort string (one or more expressions separated by commas)

• columns (string='') - List of column names separated by commas

• style (string='') - How to handle numeric ranges and order axes

removecolkeyword(columnname='', keyword='')

remove a specific keyword for a column

Parameters

• columnname (string='') - Name of column

• keyword (variant='') - Name or seqnr of keyword: string or int

removecols(columnames='')

remove one or more columns

Columns can be removed from a table that was opened nomodify=False. It may not always be possible to remove a column, because some data managers do not support column removal. However, if all columns of a data manager are removed, it will always succeed. It results in the removal of the entire data manager (and its possible files). Note that function getdminfo can be used to find which columns are served by which data manager.

Parameters

• columnames (stringArray='') - names of columns to be removed

removekeyword(keyword='')

remove a specific table keyword

Parameters

• keyword (variant='') - Name or seqnr of keyword: string or int

removerows(rownrs='')

remove the specified rows

Remove the row numbers specified in the vector from the table. It fails when the table does not support row removal.

Parameters

• rownrs (intArray='') - Row numbers to remove

renamecol(oldname='', newname='')

rename a column

A column can be renamed in a table that was opened nomodify=False. However, renaming is not possible in a (reference) table resulting from a select or sort operation.

Parameters

• oldname (string='') - name of column to be renamed

• newname (string='') - new name of column

resync()

resync the table tool with table file

Acquiring a read or write lock automatically synchronizes the internals of the table tool with the actual contents of the table files. In this way different processes accessing the same table always use the same table data. However, a table can be used without read locking. In that case the table tool internals are not synchronized automatically. The resync function offers a way to do explicit synchronization. It is only useful if the table is opened with locking mode

exttt{autonoread} or exttt{usernoread}.

rownumbers(tab='', nbytes=0)

!!!INPUT PARAMETERS IGNORED!!! return the row numbers in the (reference) table

!!!NOTE INPUT PARAMETERS IGNORED!!!

This function 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: egin {verbatim} !!!NOTE INPUT PARAMETERS IGNORED!!!

tb.open(‘3C273XC1.MS’) t1=tb.selectrows([1,3,5,7,9]) t1.rownumbers()

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

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

# [2L, 4L]

t2.rownumbers(tb.name())

# [5L, 9L]

t2.rownumbers()

# [5L, 9L] end{verbatim} The last statements show that the function returns the row numbers referring to the given table. Table t2 contains rows 2 and 4 in table t1, which are rows 5 and 9 in table ‘3C273XC1.MS’.

Note that when a table is opened using its name, that table can be a reference table. Thus in the example above the last 2 statements may give different results depending on the fact if 3C273XC1.MS is a reference table or not. The function should always be called with a table argument. The ability of omitting the argument is only present for backward compatibility.

The function can be useful to get the correct values from the result of a getcol or getcolslice on the original table.

!!!NOTE INPUT PARAMETERS IGNORED!!!

Parameters

• tab (record='') - Table to which the row numbers refer

• nbytes (int=0) - Maximum cache size in bytes

selectrows(rownrs='', name='')

Make a table from a selection of rows

Create a (reference) table containing a given subset of rows. It is, for instance, useful when a selection is done on another table containing the row numbers in the main table. It can be useful to apply the casapy function unique to those row numbers, otherwise the same row might be included multiple times (see example).

It is possible to give a name to the resulting table. If given, the resulting table is made persistent with that table name. Otherwise the table is transient and disappears when closed or when casapy exits.

The rownumbers function returns a vector containing the row number in the main table for each row in the selection table. Thus given a row number vector exttt{rownrs}, the following is always true. egin{verbatim}

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

end{verbatim} However, it is not true when selectrows is used on a selection table. because exttt{rownumbers} does not return the row number in that selection table but in the main table. It means that one has to take great care when using

exttt{selectrows} on a selection table.

Parameters

• rownrs (intArray='') - 0-based Row Numbers

• name (string='') - Name of resulting table

setmaxcachesize(columnname='', nbytes='')

set maximum cache size for column in the table

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

Parameters

• columnname (string='') - Name of column

• nbytes (int='') - Maximum cache size in bytes

showcache(verbose=True)

show the contents of the table cache

Show the contents of the table cache.

Parameters

• verbose (bool=True)

statistics(column='', complex_value='')

Get statistics on the selected table column

This function computes descriptive statistics on the table column.

It returns the statistical values as a dictionary. The given column name must be a numerical column. If it is a complex valued column, the parameter complex_value defines which derived real value is used for the statistics computation. This method does not honor any flags in the input table.

Parameters

• column (string='') - Column name

• complex_value (string='') - Which derived value to use for complex columns (amp, amplitude, phase, imag, real, imaginary)

summary(recurse=False)

summarize the contents of the table

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

Parameters

• recurse (bool=False) - Summarize subtables recursively

table()

Construct table tool

Use this constructor to construct a table tool inside casapy from the name of a disk file containing a casaTable. A new table may also be created from a table descriptor (see tablecreatedesc). When creating a new table, detailed data manager information can be given using the exttt{dminfo} argument. This is a record as returned by the getdminfo function.

Most of the arguments are rarely used: most of the time, you’ll just need to use the tablename, and perhaps nomodify.

A table can be shared by multiple processes by using the appropriate locking options. The possible options are: - auto: let the system take care of locking. At regular time intervals these autolocks are released to give other processes the opportunity to access the table. The aipsrc variable exttt{table.relinquish.reqautolocks.interval} defines the number of seconds between releasing autolocks on tables needed in another process. exttt{table.relinquish.allautolocks.interval} defines the number of seconds between releasing all autolocks. - 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 tool is not synchronized with the table file (as is normally done when a lock is acquired). The function exttt{resync} can be used to explicitly synchronize the table tool - 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 lock; the constructor fails when the table is already in use in another process - permanentwait: as above, but wait until the other process releases its lock - 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. When auto locking is used, it is possible to give a record containing the fields option, interval, and/or maxwait. In this way advanced users have full control over the locking options. In practice this is hardly ever needed.

When creating a new table, the endian format in which the data should be stored, can be specified. The possible values are: - big: big endian format (as used on e.g. SUN) - little: little endian format (as used on e.g. PC) - local: use the endian format of the machine being used - aipsrc: use the endian format specified in aipsrc variable table.endianformat (which defaults to big). The default is aipsrc. Note that usually it is best to store data in local endian format, because that requires the least amount of byte swapping. However, if the table must be accessible with AIPS++ version 1.7 or before, big endian should be used.

When creating a new table, the table will normally reside on disk. It is, however, possible to specify that the table should be held in memory. In such a case the table is process specific, thus cannot be seen by other processes. Note that a memory table uses the MemoryStMan storage manager for all its stored columns, but it is still possible to use virtual columns as well.

taql(taqlcommand='TaQL expression')

Make a table from a TaQL command.

This method Expose TaQL to the user.

Details on TaQL maybe found at http://www.astron.nl/aips++/docs/notes/199

Parameters

• taqlcommand (string='TaQL expression') - TaQL expression

testincrstman(column='')

Checks consistency of an Incremental Store Manager bucket layout

In case of corruption it returns False and a SEVERE msg is posted containing information about the location of the corrupted bucket

Parameters

• column (string='') - Column name

toasciifmt(asciifile='', headerfile='', columns=[''], sep='')

Write casatable into an ASCII format

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. The separator between values can be specified and defaults to a blank. Note that columns containing invalid data or record type data are ignored and a warning is issued.

If the argument headerfile is set then the header information is written to that file instead of the first two lines of the data file.

Parameters

• asciifile (string='') - Name of ASCII file to be written

• headerfile (string='') - Name of an optional file defining the format

• columns (stringArray=['']) - Names of columns to be written, default is all

• sep (string='') - Value separator, default is one blank

unlock()

unlock and flush the table

The table is flushed and the lock on the table is released. This function is only needed when user locking is used. However, it is also possible to use it with auto locking. In that case the lock will automatically be re-acquired before the next table operation.