thedit: Edit or print table header keywords.

Package: nttools

Usage

thedit table keywords value

Description

This table header editor can be used to add, delete, edit, or just print the values of table header keywords.

Although this task was based on 'hedit', there are significant differences. The 'add', 'verify', and 'update' parameters of 'hedit' are not included in 'thedit'. If a specified keyword does not already exist, then it will be added (equivalent to add=yes in 'hedit'). If a keyword does not exist, and the value expression is ".", a warning will be printed ('hedit' is silent in this case).

Such parameters as the number of rows or columns in the table are stored differently in FITS, STSDAS, and text tables. The following special "keywords" can be used to reference such information regardless of table type. These may be used in the 'keywords' parameter when value=".", or they can be used in the 'value' parameter as part of an expression.

i_table   string    table name (may include extension ID)
i_file    string    name of the file containing the table
i_ctime   string    file modification (or creation) time
i_nrows   int       number of rows in the table
i_ncols   int       number of columns in the table
i_npar    int       number of keywords in the table header
i_type    string    table type

'thedit' supports two of the special operands that are available in 'hedit': "$" and "$I". When 'value' is an expression, "$" gives the value of the current keyword. "$I" is equivalent to "i_table", the name of the current table. "$I" can be used as a keyword or as part of an expression.

Parameters

table [file name template]: A list of tables for which keywords are to be edited or printed. If 'value' is ".", each table will be opened read-only; otherwise, each table will be opened read-write.

keywords [string]: One or more keywords, separated by commas and/or blanks, which are to be added, modified, or printed. If the value expression (see 'value') is not ".", any keyword in 'keywords' that is not already present will be added to the header. Wildcards are supported; however, the "@filename" syntax is not supported. Do not use wildcard or other special characters if a keyword is to be added to the header.

value = "." [string]: This is the value to be assigned to each keyword in 'keywords'. The special value "." means that the keywords should be printed rather than edited, and in this case the table will be opened read-only. If 'value' is not equal to ".", the same value will be assigned to all the keywords matching the template 'keywords'. In order to set a keyword value to "." or ",", specify the value as "\." or "\," respectively. (Note that if given on the command line, the quotes are required in this case.) Requiring "," to be escaped was added as protection against accidentally typing "," instead of ".". As with 'hedit', a general expression may be given for 'value' by enclosing the expression in parentheses. The expression may include constants and/or keyword names; it will be evaluated and then assigned to each keyword in 'keywords'. Note that if delete = yes, then 'value' will be ignored.

(delete = no) [bool]: If delete = yes, the specified keywords will be deleted. All the keywords listed in 'keywords' will be deleted, for each table in 'table'.

(show = yes) [bool]: Print a record of each edit operation?

Examples

1. Display all the header keywords (except blank) in "example.tab".

tt> thedit example.tab * .

2. Display only the special keywords for "timetag.fits[events]".

tt> thedit timetag.fits[events] i_* .

timetag.fits[events],i_table = timetag.fits[events]
timetag.fits[events],i_file = timetag.fits
timetag.fits[events],i_ctime = "Wed 12:07:58 31-May-2000"
timetag.fits[events],i_nrows = 337824
timetag.fits[events],i_ncols = 6
timetag.fits[events],i_npar = 58
timetag.fits[events],i_type = "fits, binary"

3. Print all HISTORY keywords in "example.txt".

tt> thedit example.txt history .

4. Add a new HISTORY keyword to "example.tab".

tt> thedit example.tab history \
"('file name is ' // i_file) // '; number of rows = ' // str (i_nrows)"

5. Increment the value of COUNT.

tt> thedit example.tab count "($ + 1)"

6. Delete all HISTORY and COMMENT keywords in "example.fits[1]".

tt> thedit example.fits history,comment delete+

7. Evaluate a simple expression and assign the result to keyword WAVELEN. Keywords TCRVL1, TCDLT1, and NELEM are assumed to be already present in the header.

tt> thedit example.fits wavelen "(tcrvl1 + tcdlt1 * nelem/2.)"

8. A keyword can be renamed by using a two-step process, first creating a new keyword with the old value, and then deleting the old keyword. Note that while this procedure does copy the value, the comment will be lost. (The "k" instruction in 'tupar' can also be used to rename a keyword.)

tt> thedit example.tab newkey "(oldkey)"
tt> thedit example.tab oldkey delete+

9. The primary header or an image extension of a FITS file can also be opened as a table in order to access the keywords.

tt> thedit o47s01kdm_raw.fits[0] rootname .
tt> thedit o47s01kdm_flt.fits[1] bunit "COUNTS/S"

10. This could have been a big mistake.

tt> thedit abc.fits[1] * ,

ERROR: In order to set a keyword value to ',' you must use value='\,'

Bugs

Expressions are evaluated using EVEXPR, which does not support double precision.

Header lines with keyword = ' ' cannot be displayed.

The 'value' parameter is of type string, and 'thedit' interprets the value to determine what data type to use when writing the value to the table. This can fail when a value appears to be a number but really should be treated as a string. For example, a date and time could be written as "19940531:11515000". 'thedit' would interpret this as hours and minutes (HH:MMss) and convert the value to 1994053. + 11515000./60. A workaround for this case is to use 'tupar' instead of 'thedit'; use the "pt" instruction, meaning put a keyword of type text.

References

This task was written by Phil Hodge, based on the 'hedit' task.