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:
- 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.
- 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