fthedit HEADAS help file

NAME

fthedit - Edit one or more header keywords in the input HDU.

USAGE

fthedit infile[ext] @editfile.txt
or
fthedit infile[ext] keyword operation value

DESCRIPTION

fthedit edits the header keywords in the input FITS HDU in place, modifying the original file. There are 2 main ways to use fthedit:

Modify multiple keywords at once by specifying an ASCII template file which lists the keywords to be added or deleted in the header.
Modify, append, or delete a single keyword (or delete all instances of the keyword) by specifying the components of the keyword with the 'keyword', 'value', 'unit', and 'comment' parameters. In this mode, the keyword may also be inserted at a specific location in the header, or a specified keyword can be overwritten with a new keyword.

In the first mode of use, each line of the 'editfile' text file contains a template for a keyword that is to be appended, modified or deleted in the header:

To modify an existing keyword or to append a new keyword, add a line to the 'editfile' that contains the name, value, and comment field of the keyword in free format, as in:
```
          keyword = value / [units] comment
          EXPOSURE = 3.5 / [s] total exposure time
          OBJECT  M31  name of observed object
          COMMENT  this is a general comment
          HISTORY  provides file processing history information
```
Note that the equal sign and slash character are optional. In most cases the value of a string type keyword does not need to be enclosed in quotes, unless the value could be confused with a numeric or boolean value.
To delete a keyword, add a line to 'editfile' containing the name of the keyword preceded by a minus sign, as in:
```
          -DATEOBS
```
Wildcards are permitted in deletion operations. Thus,
```
          -DATE*
```
will remove the first keyword that begins with DATE, regardless of the trailing characters of the keyword name. The wildcard patterns are '*', which matches any string; '?', which matches a single character; and '#' which matches any string of numerical digits.
The above mechanism removes only a single keyword that matches the given pattern. To remove all keywords, use a trailing '+'. This example:
```
          -DATE*+
```
will remove all keywords that begin with DATE. Please also consult operation='deleteall' below.
To rename a keyword, add a line to 'editfile' containing the current name of the keyword, preceded by a minus sign, followed by the new name of the keyword, as in:
```
          -DATEOBS  TIMEOBS
```
Any lines in 'editfile' that begin with the pound sign '#' or consist entirely of 7 or fewer space characters are ignored by fthedit and are treated as comment lines. Lines beginning with 8 or more space characters are interpreted as a FITS comment keyword with a blank name.
If the keyword name is longer than 8 characters or contains special characters that are not allowed in a true FITS keyword name, then the FITS record will be constructed using the ESO HIERARCH convention. For example, if the keyword template looks like:
```
          CCD$camera:shutter_speed = 0.1 / [s] shutter speed
```
then the FITS header recorde will be written as:
```
          HIERARCH CCD$camera:shutter_speed = 0.1 / [s] shutter speed
```
where the effective keyword 'name' is 'CCD$camera:shutter_speed'.

To run fthedit in the other "single keyword" mode of use, enter the type of edit to be performed ('add', 'delete', 'replace', or 'deleteall') in the 'operation' parameter.

If operation = add, then the specified 'keyword' will be modified if it already exists, or added to the header if not. The commentary keywords such as COMMENT or HISTORY are always added to the header. The keyword record is formed by concatenating the 'keyword', 'value', 'unit' and 'comment' parameter strings into one long string, then reformatting it to conform to the rules for a FITS keyword. Note that the 'value', 'unit', and 'comment' parameters are somewhat redundant and the unit and comment strings can be specified as part of the 'value' parameter if desired. An error will be returned if an attempt is made to modify a write-protected keyword (see the 'protect' parameter). If the 'insert' parameter is not blank it will be interpreted as the name or sequence number of an existing keyword in the header after which the new keyword should be inserted.
If operation = delete, then the specified 'keyword' name (or the first instance of that keyword if there are more than one) will be deleted from the input HDU.
If operation = deleteall, then all instances of the specified 'keyword' name will be deleted from the input HDU. This is useful for deleting all the HISTORY or COMMENT keywords in a header. Wild card characters (*, ? or #) may also be used when specifying the keyword name, where * matches any string of characters, ? matches any single character, and # matches any consecutive string of decimal digits. Example: ?COEF# will match all keywords where the 2nd through 5th characters are the string 'COEF' followed by one or more digits. All the keywords that match the template will be deleted.
If operation = replace, then the 'keyword' and 'value' parameters take on slightly different meanings: 'keyword' is used to supply a text search string. The first non-protected header keyword that contains this case-sensitive string, anywhere in the 80-character length of the header record, will be overwritten by the string given by the 'value' parameter. In this case, 'value' gives the entire new keyword string, including name, value, and comment string if relevant, for the new keyword. The value string is not reformatted by fthedit (only the first 8 characters will be capitalized if necessary) so the string must conform to all the rules governing the format of a FITS keyword. The 'replace' operation is especially useful for modifying COMMENT or HISTORY keywords which cannot generally be modified with the 'add' operation because there are usually more than one keyword with the same name.

PARAMETERS

infile [filename]: File name and optional extension name or number enclosed in square brackets of the HDU to be modified (e.g., 'infile.fits[0]' or infile.fits[events]'). If a specific extension name or number is not specified, then the first 'interesting' HDU (e.g., the first image HDU that has more than 0 dimensions, or the first table HDU that is not a Good Time Interval extension) will be opened and operated upon.
keyword [string]: This parameter has 2 modes of use.
1) It may give the name of an ASCII text file, preceded by the '@' character, that contains a list of the edit operations to be performed. Each line of this file specifies a keyword to be added, modified, or deleted in the header.
2) If the string does not begin with the '@' character, then it is used to specify the name of the keyword to be added or deleted (case insensitive), or, if operation = replace, then a unique text search string (case sensitive). In the latter case, the first non-protected 80-character header keyword that contains this string (in the keyword and/or value and/or comment fields) will be replaced in its entirety by the text string given by the 'value' parameter.
operation [string]: Type of edit operation to be performed if no 'editfile' is specified. Valid operations are 'add' or 'a' to add or update a keyword, 'delete' or 'd' to delete a keyword, 'deleteall' to delete all instances of a keyword, and 'replace' or 'r' to overwrite an existing keyword with a new keyword. This parameter is ignored when the name of a text file is entered for the 'keyword' parameter.
value [string]: The value (and optional comment field) of the keyword to be added, or, if operation = replace, the entire 80-character record that will overwrite the header record identified by the 'keyword' parameter search string. The datatype of the keyword value is determined by context. String values can be enclosed in single quotes. Boolean keywords may have a value of T or F (note too that when 'value' is lower or upper case 'T' or 'F', it is assumed to be boolean, not a string). This parameter is ignored if operation = delete or if the name of a text file is entered for the 'keyword' parameter.
(unit = " ") [string]: Optional physical units of the value (e.g., 'km/s'). This string will be written enclosed in square brackets at the beginning of the keyword comment field. This parameter is only used if operation = add.
(comment = " ") [string]: Optional comment string for the keyword. The comment string may be entered as part of the value parameter instead. This parameter is only used if operation = add.
(insert = " ") [string]: If operation = add, then this parameter gives the name or sequence number of the keyword after which the new keyword will be inserted. If 'insert' is blank, then the new keyword will either be updated if it already exists or appended to the end of the header if not.
(protect = YES) [boolean]: If protect = YES, then the mandatory keywords that define the structure of the HDU will be write protected and may not be edited. This includes the SIMPLE, BITPIX, NAXIS, NAXISn, PCOUNT, GCOUNT, TFORMn, TBCOLn, keywords. Setting protect = NO will allow any of these keywords to be modified or deleted, which if done improperly, can corrupt the input file and make it completely unreadable! One should always make a backup copy of the file before trying to edit the protected keywords.
(longstring = NO) [boolean]: If longstring = YES, then string keywords whose values are too long (> 68 characters) to fit in a single FITS header keyword will be written using the HEASARC Long String Keyword convention. The value string is divided up into 68-character segments, and each segment is written in sequence to multiple header keywords. All the subsequent continued keywords will have "CONTINUE" in the first 8 characters of the header record. Note that this option currently can only be used in the "single keyword" mode, and it does not support inserting the new keyword at a specific location in the header. If the value string contains embedded space characters then the whole string must be enclosed with single quote characters. If the value string is given on the unix command line, then this quoted string must in turn be enclosed with double quote characters (e.g., "'This is the long string value'").
(chatter = 1) [integer, 0 - 5]: Controls the amount of informative text written to standard output. Setting chatter = 5 will produce detailed diagnostic output, otherwise this task normally does not write any output.
(history = NO) [boolean]: If history = YES, then a set of HISTORY keywords will be written to the header of the input file to record the current value of all the fthedit task parameters.

EXAMPLES

Note that when commands are issued on the Unix command line, strings containing special characters such as '[' or ']' must be enclosed in single or double quotes.

1. This example illustrates the multi-keyword edit mode in which the edit commands are contained in the 'editfile.txt' text file.

      fthedit infile.fits @editfile.txt

Here is an example of an edit file. Note that the equal sign and slash field delimiters are normally optional in the template file, and the keyword names need not be given in upper case.

          # the following lines insert or update keywords
          object = 'Mira star' / name of observed object
          ra = 146.5677 / [deg] Right Ascension
          dec -45.4343 [deg] Declination
          nobs 45 sequence number
          COMMENT        this comment is written verbatim
          HISTORY  file processed by Joe Bloggs on 04-03-2001

          # the following lines delete existing keywords
          -OBSERVER
          -exposure

          # the following lines rename keywords
          -RA   RA-NOM
          -DEC  DEC-NOM

2. Append the EXPOSURE keyword or update the value and comment fields if the EXPOSURE keyword already exists. The 2 examples shown here produce exactly the same result.

      fthedit infile.fits keyword=exposure operation=add  
           value=11000.0 unit=s comment='nominal exposure time'

      fthedit infile.fits none add exposure
           value='11000.0 / [s] nominal exposure time' 

    Both of these commands will create the following header keyword:

      EXPOSURE=              11000.0 / [s] nominal exposure time

3. Insert a new TDISP2 keyword immediately following the TFORM2 keyword.

      fthedit infile.fits TDISP2 add F8.2 
           comment='column display format' insert=TFORM2

    will insert the following header keyword:
 
      TDISP2  = 'F8.2    '           / column display format

4. Insert a new COMMENT keyword following the 10th keyword currently in the header.

      fthedit infile.fits COMMENT add  
         'All times are given in units of seconds.' insert=10

    will insert the following header keyword:

      COMMENT All times are given in units of seconds.

5. Change the value of the SIMPLE keyword in the primary array. Since this keyword is normally write protected, the 'protect' parameter must be set to NO.

      fthedit 'infile.fits[0]' SIMPLE add F
      comment='non-conforming FITS file' protect=NO

    will modify the following header keyword:

      SIMPLE  =                    F / non-conforming FITS file

6. Delete the EQUINOX keyword.

      fthedit infile.fits EQUINOX delete

7. Modify a COMMENT keyword containing the string "preliminary data".

      fthedit infile.fits keyword='preliminary data' replace 
      value='COMMENT  This file contains final processed data.'

    The original keyword looked like this:
      
      COMMENT  This file contains preliminary data.

    After running fthedit, the keyword now looks like this:

      COMMENT  This file contains final processed data.

8. Delete a particular HISTORY keyword in the header that contains the string "horizontal axis". Since there are often multiple HISTORY keywords in the header it is usually not possible to delete one directly. Instead the 'replace' operation is used to rename the HISTORY keyword to a unique keyword ('DUMMY' in this example) then fthedit is run a second time to delete the DUMMY keyword.

      fthedit infile.fits keyword='horizontal axis' replace 
         value='DUMMY   = 0'

      fthedit infile.fits DUMMY delete

LAST MODIFIED