| keyselect | tables | keyselect |
keyselect -- Copy selected image header keywords to an STSDAS table.
keyselect input output cols
This task copies the specified image header keywords to an STSDAS table. The required parameters are the input list of image names, the output STSDAS table name, and the list of header keywords. All groups of each image will be examined if the list of header keywords contains a group parameter. Otherwise only the first group of each image will be examined. The task appends rows to the output table if it exists or creates a new table if the output table does not exist. If the output table exists, column names must match the names in the existing table. The column names in the output table are the same as the header keywords unless they are explicitly specified, as described below.
If a keyword is missing from an image header a warning message is printed and a null value inserted into the table. The default type of the table column is determined from the type of the header keyword. Text columns have a default length of 19 characters, unless the table column is the concatenation of several keywords, in which case the default length will be 63 characters. A column description file must be used if you want to override the default type or length of a table column.
The third parameter (cols) is a list of items specifying the header keyword names and table column names. Items in the list are separated by commas or whitespace. Three different kinds of items may appear in the list: a keyword name, a table column name followed by a equals sign followed by a keyword name, or a table column name followed by an equals sign followed by a list of keyword names separated by colons. If the item in the list is a keyword name, the table column name is the same as the keyword name. To specify a table column name different than the keyword name, the item in the list should be the table column name followed by an equals sign followed by the keyword name. To concatenate several header keywords into a string separated by commas, a list of keyword names separated by colons should replace the header keyword name in the item. The following list gives examples of the three types of items.
FGWA_ID GRATING=FGWA_ID OBS_MODE=DETECTOR:FGWA_ID:APER_ID
In the first case, both the header keyword name and table column name are fgwa_id. In the second case the table column name is grating. In the third case table column name is obs_mode and the values in the column are the concatenation of the header keywords detector, fgwa_id, and aper_id separated by commas.
Special keywords may also be used in the list wherever a header keyword may be used. Special keywords are used to place the image name or parts of the image name in the output table. The name of a special keyword always starts with a "$". The different special keywords, their types, and default table column names are given in the following list.
$group int group $dir text directory $ext text extension $hdr text header_file $pix text data_file $root text rootname
If an image has the name yref$y00vk101a.r1h[1], the group will be 1, the directory yref$, the extension r1h, the header file y00vk101a.r1h, the data file y00vk101a.r1d, and the root name y00vk101a.
The hidden task parameter expr is used to select which images are examined when writing header keywords to the output table. If this task parameter is set to its default value, (a blank string), all images named in the image template will be examined. Otherwise the task parameter is interpreted as a boolean (logical) expression. The variables in the expression are header keyword names. As each image is opened the values of the header keywords are substituted for the keyword name. If the expression is true, the header keywords specified in the cols parameter are copied into the output table. The special keywords mentioned above may also be used in the expression. If a keyword name contanis dashes the keyword name should be preceded by a @ and enclosed in quotes. For example, date-obs should be given as @"date-obs" in the expression.
The following boolean operators may be used in the expression:
equal == not equal != less than < less than or equal <= greater than > greater than or equal >= or || and && negation !
The expression may also include the usual arithmetic operators and functions. Arguments to the trigonometric functions must be in degrees. The available operators are:
addition + subtraction - multiplication * division / negation - exponentiation ** string concatenation //
The following is a list of the available functions:
absolute value abs(x) cosine cos(x) sine sin(x) tangent tan(x) arc cosine acos(x) arc sine asin(x) arc tangent atan(x) arc tangent atan2(x,y) exponential exp(x) square root sqrt(x) natural log log(x) common log log10(x) minimum min(x,y) maximum max(x,y) modulo mod(x,y) keyword found find(x,y,z,..)
One new function, find, is available in addition to the usual arithmetic functions. The argument of this function is a list of header keyword names. The function returns true if all the header keywords are found in the image and false if one or more header keywords in the list are not found. The arguments to this function should be placed in quotes as otherwise the value of the header keyword will checked instead of the name. That is, if find(detector) is used instead of find("detector"), the task will look for a header keyword whose name is the value of the detector keyword.
The cols and expr parameters can also be the name of a file preceded by an @ character. If this is done, the task will read the list of keyword names or boolean expression from the specified file. Newlines in the file are treated as if they were blanks, so lines may be broken wherever a blank would be correct. Comments (lines starting with a # character) are not permitted in either file.
The hidden parameter cdfile is the name of the column description file. The default value for this parameter is (a blank string). If the parameter contains a blank string no column description file is used and the column data type is taken from the type of the header keyword. A column description file contains one line for each column in the table. Each line contains four fields in the following order: the column name, the data type, the print format, and the units. Any of the fields except the column name may be omitted. If a field is omitted the default for that field will be used instead. Fields are not case sensitive except for the units field. The column name in the column description file must match the column name in the cols parameter. If a column name in the cols parameter is not found in the column description file, a warning message is printed and the defaults are used for that table column. Column names in the column description file that are not in the cols parameter are ignored. For further information on the format of a column description file, refer to the help file for tlcol.
1. Create an STSDAS table from the headers of the dead diode reference images:
tt> keyselect yref$*.r4h ddt.tab detector,headname,dataname
2. Create the same table, only name the columns "header_file" and "data_file":
tt> keyselect yref$*.r4h ddt.tab \ >>> detector,header_file=headname,data_file=dataname
3. Only select images with the blue detector:
tt> keyselect yref$*.r4h ddt.tab detector,headname,dataname \ >>> expr="detector='blue'"
4. Use a column description file when creating the table:
tt> keyselect yref$*.r4h ddt.tab \ >>> detector,header_file=headname,data_file=dataname cdfile="ddt.cd"
The contents of the column description file:
DETECTOR CH*5 HEADER_FILE CH*18 DATA_FILE CH*18
This task was written by Bernie Simon.
Type "help tables opt=sys" for a description of the tables package.
