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:

  1. Modify multiple keywords at once by specifying an ASCII template file which lists the keywords to be added or deleted in the header.
  2. 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 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.

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  

SEE ALSO

ftkeypar, fdump, ftedit

fv, the interactive FITS file editor, can also be used to edit FITS header keywords.

The design of this task is based on the fmodhead, fkeypar, and fmodcomm tasks in the ftools package and the CXC dmhedit task.

LAST MODIFIED

Apr 2018