NAME

ftedit - Edit the values in a FITS image or table.

USAGE

ftedit infile[ext] column row newvalue
or
ftedit infile[ext] @editfile

DESCRIPTION

ftedit can be used to modify the values in one or more image pixels or table cells. The changes are made directly to the input file, in place. There are 2 main ways to use ftedit:

  1. Modify a single image pixel or table cell value by directly specifying (via the task parameters) the column name or number, the row number, and the new value for the cell.
  2. Modify multiple elements at one time by specifying an ASCII template file in which each row lists the column name or number, row number, and new value for every cell that is to be modified.

In both cases an optional element number can be specified to modify a particular element within a vector table column. This task does not currently support modifying values in variable length array columns.

PARAMETERS

infile [filename]
File name and optional extension name or number enclosed in square brackets of the image or table to be modified (e.g., 'infile.fits' or infile.fits[events]'). If an extension name or number is not specified then the first 'interesting' HDU (e.g., the first non-null image HDU or the first table HDU that is not a Good Time Interval extension) will be opened and edited.

column or @template file [string]
This character string parameter can be interpreted in 3 different ways:
1) when editing a single element in a table, this parameter specifies the name (or index number) of the column containing the cell to be modified.
2) when editing a single pixel in a 1-D or 2-D image, it specifies the column number (i.e., the X coordinate, counting from 1) of the pixel to be modified.
3) when editing multiple image pixels or table elements at one time, it specifies the name of the ASCII text file, preceded by an '@' character, that contains the editing instructions.

In the latter case, and when editing image pixels, each line of the text file consist of 3 tokens separated by one or more spaces giving the integer X and Y pixel location (where Y = 1 when editing a 1-D image) and the new pixel value. Note that pixel (1,1) is usually displayed at the lower left hand corner of the image.

When editing a scalar table column, the text line contains 3 tokens giving the column name, row number, and new value for each element to be modfied. When editing a vector column the line must contain 4 tokens: column name, row number, element number within the vector, and new value. When editing a complex (TFORMn = 'C') or double complex (TFORM = 'M') column in a binary table, the new value actually consists of 2 tokens, separated by a comma or a space character, that give the real and imaginary parts of the complex value. See the description of the 'value' parameter, below, for more information on how to specify null values or logical table column values.

row [integer]
When editing a single element, this parameter gives the row number (counting from 1) containing the image pixel or table cell to be modified. Note that images are usually displayed such that the (1,1) pixel is at the lower left corner of the image. This parameter is ignored when the name of a text file is entered for the 'column' parameter.

value [string]
When editing a single element, this parameter gives the new value for the image pixel or table cell. This parameter is ignored when the name of a text file is entered for the 'column' parameter. The data type of the value must be consistent with the datatype of the column. Implicit datatype conversion (integer to float or float to integer) will be performed for numerical columns if necessary. If a Logical column (TFORMn = 'L') is being modified, then true values can be represented as 'TRUE', 'T', 'YES', 'Y', or '1' (in either upper or lower case). False values can be represented by 'FALSE', 'F', 'NO', 'N', or '0'.

To set an element value to be undefined, specify a value of 'INDEF', 'NULL', or 'NAN' (case insensitive). In the case of an integer data type image, or an integer table column this requires the presence of a BLANK or TNULLn keyword, respecively, to define what integer value should be used to represent a null value.

(element = 1) [integer]
When editing a single element in a vector column this specifies which element within the vector to modify. This parameter is ignored then editing scalar table columns or image pixels.

(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 table to record the current value of all the ftedit 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-cell edit mode in which the edit commands contained in the 'edittab.txt' text file are used to modify the EVENTS table in the input file: 

     ftedit  'infile.fits[events]'  @edittab.txt
In the following sample edit template file, the X and Y column values in rows 100 through 102 are set to 2000 and 1500, respectively, and row 1 of the Time column is set to be undefined. In this example, PHA is assumed to be a vector column with TFORMn = '9I', and so the last line in this template file modifies the 5th element of the vector in row 15 to equal 48. 

          # this is a comment line
          X  100  2000
          X  101  2000
          X  102  2000
          Y  100  1500
          Y  101  1500
          Y  102  1500
          Time 1  INDEF
          PHA 15 5 48
2. Open the 'light_curve' table and modify the value in row 8 of the RATE column to equal 120.5. 

     ftedit infile.fits[light_curve]  rate  8  120.5
3. In the 'RAWDATA' table extension in infile.fits, modify the 3rd element in row 4 of the SPECTRUM column to equal 0. 

     ftedit infile.fits[rawdata]  spectrum  4  0. element=3
4. Modify row 1 of the 'Name' column to equal "NGC 253". 

     ftedit infile.fits  name  1  'NGC 253'
5. Modify pixel (24,35) in the primary array to equal 1200. 

     ftedit myimage.fits  24  35  1200
6. Modify several pixels in row 140 of a floating point data type image using a template file. 

     ftedit  myimage.fits  @editimage.txt
where the editimage.txt file contains lines that look similar to this: 

        124 140 12.7
        125 140 12.6
        126 140 12.2
        127 140 12.1
        128 140 11.8

SEE ALSO

fthedit, ftlist

fv, the interactive FITS file editor, can also be used to edit FITS images and tables.

The design of this task is based on the fparimg, fpartab and fmodtab tasks in the ftools package.

LAST MODIFIED

September 2002