---

STSDAS Tables: the ttools Package

Data in STSDAS tables are accessed using the name of the column. There is no need for the user to know the position of a column within a table, and the column names can be easily viewed using tasks in the ttools package. Because table entries are accessed by column name, information in a table can be easily shared by different applications: users (or programmers) need only know the name of the column containing the appropriate information.

Each STSDAS table is stored in a single file. By default, tables have the filename extension .tab. While you may give tables any filename and extension, it will be most convenient to use the default .tab extension, otherwise you will have to specify the extension explicitly when using the various table manipulation tools. Unless a table is opened read/write, STDIN and STDOUT are acceptable names for input and output text tables.

The table I/O software can also read and write plain ASCII tables. These are simply text files in row and column format. Column names in text tables are accessed by column number but using a character string starting with "c" and followed by the column number: c1, c2, c3, etc. While the file name of a binary table must have an extension, the name of a text table need not.

Users will find many opportunities for using STSDAS tables. Each calibration pipeline task (calxxx) reads from STSDAS tables to get the necessary calibration constants. The IRAF daophot package can produce results in either IRAF internal data base format or STSDAS table format. Tables produced by tasks such as daophot can then be analyzed using facilities in the ttools package.

The ttools Package

• Creating Tables:
  • tcreate will generate an STSDAS table from plain ASCII tables. Users must provide the ASCII text for the table and a description of the columns.

  • Using tedit, users can interactively create a new table, defining column names on the fly and then inserting values into the table.

• Reviewing and Editing Tables:
  • tprint will generate an ASCII listing of table contents (an option is provided to generate TeX or LaTeX output).

  • tread functions the same way as tedit, except that it runs in read- only mode.

  • tupar lets a user list and update header parameters in a table.

  • gtedit is a table editor with a graphical front-end. With gtedit, one can plot, for example, one column as a function of another and, using the graphics cursor, mark rows for deletion simply by pointing at points on the graph.

• Getting Information About Tables:
  • tinfo tells you the size of a table (number of rows, number of columns, number of header keywords, etc.).

  • tlcol displays the names and other attributes of the columns in a table.

• Data Base Functions: The tasks tquery, tsort, tproject, tselect, tdiffer, tjoin, tproduct, and texpand provide various functions to use STSDAS tables as if they were small relational data bases. Information that you have in one table (or several tables) can be combined according to certain selection criteria, sorted, and compared.
  • tselect allows you to extract a subset of the rows in an existing table, subject to a specified selection criterion.

  • tsort sorts the rows in a table by the values in one or more columns.

  • tproject creates a subset of a table by retaining only the specified columns.

  • tquery combines the actions of tselect, tsort, and tproject; it also functions like the query mechanisms used in standard data base applications.

  • tdiffer can be used to create an output table that includes only the rows that differ between two input tables.

  • tjoin combines input from two tables into a third table based on a test for equality of values in a common column (for example, given a table of object names and magnitudes, and a second table of object names and colors, make a table that, for each object, contains columns with the magnitudes and colors--but only if the object names match, if not, the row is not copied to output).

  • texpand uses a set of user-defined rules to convert specified elements in a row, creating one or more modified versions of the row in the output file.

  • tproduct creates the Cartesian product between two tables (every combination of rows in the two tables). This can quickly make a big table!

• Statistics and Analysis:
  • The thistogram task is used to compute a histogram for a given column in an STSDAS table. The output is directed to the IRAF standard output stream STDOUT or into a column in another table. The sgraph task can plot either type of output.

  • tlinear computes a linear regression on the data in two specified columns in an STSDAS table. The columns are used to specify the X and Y coordinates of the data to be fit. The output can be directed to a table or to STDOUT.

  • The data in columns of table can be resampled using the task trebin. The resampling is done over a user-specified range of the independent variable, and the output will be equally sampled over this interval. Four options are available for computing the sampled data values: nearest neighbor replacement, linear interpolation, third order polynomial interpolation, and spline interpolation.

  • The task tstat is used to determine the standard statistical parameters--mean, standard deviation, median, minimum, and maximum--for a column in an STSDAS table. The output can be directed either to STDOUT or to one row of another table.

• Performing Arithmetic on Table Columns:
  • The STSDAS task tcalc is a general purpose table calculator. You can specify virtually any mathematical expression (using standard arithmetic and functional operators) involving columns in a table, computing a new table column.

  • tintegrate computes the integral of the data in a table column with respect to a second column. The integration is simple--using the trapezoid rule--and the output is written to both STDOUT and task parameters.

• Converting Keywords, Parameters, and Entries: These tasks (keypar, keytab, parkey, partab, tabpar, and tabkey) are used to copy parameter values from one location to another location. The values can originate either as CL parameters (such as a task parameter), keyword values in a table or image header, or entries in a particular column and row of an STSDAS table. The six tasks discussed in this section provide for all possible of combinations of input and output destinations, with key indicating a header keyword, par indicating a CL parameter, and tab indicating an element from a table. For example, the keypar task name indicates that the program would convert keywords to tables.

• Changing Column Names or Table Sizes: These routines let users modify the structure of STSDAS tables.
  • tchcol lets users rename a column or change its display format or units.

  • tchsize is used to modify the allocated sizes of internal table structures, such as the size of the header area, the space allocated for column descriptions, the length of the table row, and the number of rows for which space is reserved. Using this task improperly can be counterproductive, so make sure you understand the task parameters before you use this facility.

• Copying and Deleting Tables:
  • tcopy copies an input table to an output table; it differs from a standard file copy operation only in that it automatically appends the standard table extension .tab and verifies that the file is a table.

  • trename and tdelete function like rename and delete except that they will assume a .tab extension if none is specified (and will verify that the file is a table).

The ttools Package

Generated with WebMaker