STScI Logo

keyselect tables


NAME · USAGE · DESCRIPTION · PARAMETERS · EXAMPLES · BUGS · REFERENCES
SEE_ALSO

NAME

keyselect -- Copy selected image header keywords to an STSDAS table.

USAGE

keyselect input output cols

DESCRIPTION

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.

PARAMETERS

input [file name template]
List of image names. The usual wild card characters can be used. If the list of keyword names or the expression contains a group parameter all groups of each image will be examined unless a group is explicitly specified as part of the image name.
output [file name]
The name of the output STSDAS table. If the table already exists new rows will be added to the existing table. Column names must match names in the existing table. If the table does not exist a new table will be created and any column names may be used.
cols [string]
The list of header keyword names separated by white space or commas. Table column names are the same as the keyword names unless explicitly specified in the form <colname>=<keyword>. Several keywords can be concatenated by using the form <colname>=<keyword>:<keyword>. If the first character in the parameter is an @, the rest of the parameter is interpreted as a file name containing the list of keyword names.
(expr = " ") [string]
A boolean expression used to select which images are examined for header keywords. If the string is blank (the default) all images named in the input list are examined. Variables in the expression are header keyword names. An image is selected if substituting the value of the header keywords for their names makes the expression true. The syntax of the expression follows the usual CL and SPP conventions. If the first character in the expression is a @, the rest of the expression is interpreted as a filename containing the expression.
(cdfile = " ") [file name]
The name of the column description file. The format of a column description file is defined in the help for tlcol. Column names used in the column description file must match the names in the cols parameter (except for case).

EXAMPLES

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

BUGS

REFERENCES

This task was written by Bernie Simon.

SEE ALSO

Type "help tables opt=sys" for a description of the tables package.


Source Code · Search Form · STSDAS