txtable: Extract 2-D tables from rows of 3-D tables.

Package: nttools

Usage

txtable intable outtable

Description

This task extracts one or more rows from a 3-D table and writes each row as a 2-D table. The input may be a filename template, including wildcard characters, or the name of a file (preceded by an @ sign) containing table names. The output may be either a directory specification or a list of table names. If the output is a list of tables then there must be the same number of names in the input and output lists, and the names are taken in pairs, one from input and one from output. The input and output tables must not be the same.

This task supports row/column selectors in the input table name. These may be used to select subsets of both rows and columns from the input table. If no selectors are used, all columns will be extracted, and the number of output tables will be the number of rows in the input table. Type 'help selectors' to see a description of the selector syntax.

Since one input table may generate several output tables, the task adopts the following naming scheme for these output tables: their names are built by appending a suffix to the name given in parameter "outtable". The suffix has the form "_rXXXX", where XXXX stands for the row number in the input table. The suffix is appended before the file name extension. The task recognizes as valid table name extensions the values ".tab", ".fits" and ".fit". Any other extension is assumed to be part of the root file name. If only one row is extracted, or in case of ASCII output, no suffixing takes place.

NOTE: Be careful when using a wildcard for the extension. If you have the files "table.tab" and "table.lis" in the current directory, for example, then the command "txtable tab* test/" would expand both files to the subdirectory "test".

There are two forms of handling scalar columns in the input table. If task parameter "compact" is set to 'no', the corresponding column in the output table will have the scalar value in its first row, and all other rows will be filled with INDEF. If parameter "compact" is set to 'yes', scalar columns will be written into the header as a set of header keywords. These keywords can be used later by task 'titable' to re-insert the scalars as cell elements of a 3-D table.

The task does not propagate array dimensionality when extracting arrays into columns in the output table. If dimensionality information exists in the 3-D table, that information is lost, that is, the table cell from the input table is written as a structureless, plain table column.

The input row number is written to the header of the output table in keyword ORIG_ROW. This allows 'titable' to put the data back where 'txtable' got them from.

Parameters

intable [file name list/template]: A list of one or more tables to be expanded. Row/column selectors are supported.

outtable [file name template]: Either a directory name or a list of output table names. The standard value "STDOUT" generates ASCII output that can be redirected to a file.

(compact = yes) [boolean]: Write scalars as header keywords ?

(verbose = yes) [boolean]: Display names of input and output tables as files are processed ?

Examples

Extract columns named FLUX and WAVELENGTH from rows 11 to 13 of a 3-D table:

cl> txtable "table.tab[c:FLUX,WAVELENGTH][r:row=(11:13)]" tableout

This will generate three tables named "tableout_r0011", "tableout_r0012" and "tableout_r0013".

Bugs

References

This task was written by I. Busko.