tablefromascii - Constructor

Create an AIPS++ table from an ASCII format

Synopsis
tablefromascii(tablename, asciifile, headerfile, autoheader, autoshape, sep, commentmarker, firstline, lastline, readonly, lockoptions, ack, tableserver)

Description
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 tool 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 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 (autoheader=T) 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:

1.: autoshape=[] (which is the default) means that all values are to be stored as scalar columns.
2.: autoshape=0 means that all values in a row are to be stored as a variable length vector.
3.: 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.
4.: 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:

1.

The first line contains the names of the columns. These names may be enclosed in quotes (either single or double).

2.

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 AIPS++:

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

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. texttt' *//' 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.

Arguments

tablename	in	Name of table to be created
		Allowed:	String
asciifile	in	Name of ASCII file to be read
		Allowed:	String
headerfile	in	Name of an optional file defining the format
		Allowed:	String
		Default:	''
autoheader	in	Determine header information automatically
		Allowed:	Boolean
		Default:	F
autoshape	in	Shape to be used if autoheader=T
		Allowed:	Vector of Ints
		Default:	[]
sep	in	Value separator
		Allowed:	String
		Default:	' '
commentmarker	in	Regex indicating comment line
		Allowed:	String
		Default:	''
firstline	in	First line to use
		Allowed:	Int
		Default:	1
lastline	in	Last line to use
		Allowed:	Int
		Default:	-1
readonly	in	Open Read-only?
		Allowed:	Bool
		Default:	T
lockoptions	in	locking to be used
		Allowed:	String\|Record
		Default:	default
ack	in	Acknowledge creations, etc
		Allowed:	Bool
		Default:	T
tableserver	in	Table server to be used
		Allowed:	Any tableserver
		Default:	defaulttableserver

Returns
table tool

Next: table.flush - Function Up: table - Tool Previous: tablefromfits - Constructor Contents Index

	Package	utility
	Module	table
	Tool	table