.help fimgextract Oct97 ftools.fimage
.ih
NAME
fimgextract -- Extract a (vector) column from a table or a subset from an
array, optionally summing over the rows.
.ih
USAGE
fimgextract infile outfile cols rows
.ih
DESCRIPTION
Create an image from data extracted from either a table extension or
another image.  A single column of a table (single valued or
vector/array) or a contiguous subset of a data cube/image serves as
the input.  An arbitrary list of rows of the table (or final dimension
of a data cube) can be selected to be STACKed/concatenated, SUMmed, or
AVeraGed.  The resulting image can be placed into the primary array of
a new file or inserted into an already existing file as an image
extension.
.ih
PARAMETERS
.ls infile [filename]
The FITS file to read.  If no extension is given, the program first
tries to read the primary array, but if it is empty the program reads
the first extension.
.le
.ls outfile [filename]
The FITS file to which to write the new image.  If no extension is
given, the image will be placed in a new primary array in a new file or
appended to a pre-existing file,
otherwise the image will be inserted into a file at the given extension,
appending it to the file if the file has fewer extensions.  An empty
primary array will be created if the file does not exist and a nonzero
extension is given.
.le
.ls cols [string]
If infile points to a table, cols is the name of the single column
to read.  The column can contain a single numerical value or an
N-dimensional array.  (Variable size arrays are not supported, yet.)
Alternatively, if infile points to an N-dimensional image (or primary array),
cols is a list of bounds for the first N-1 dimensions of
the array to be operated on. The final, Nth dimension of the array is
selected by the rows parameter.  If the array
is one-dimensional, it will be interpretted as a 1xM array, requiring
cols="1".  To select the full extent of the array for each of its
first N-1 dimensions, set cols="-".
.le
.ls rows [string]
A list of row ranges to process.  Ranges can be in reverse order (ie, hi to
low) or can leave off one (or both) ends to indicate a range starting
with the first or ending with the last row in the extension.
.le
.ls (operation = "STACK") [string]
The operation to perform on the data.  "STACK" simply places each
input row into consecutive rows of the output image.  "SUM" combines
each input row into a single, summed array.  "AVG" also sums the data,
but before outputting the array renormalizes it by the number or rows
read.  "SUM" and "AVG" create an image (or data cube) of the same
dimension and size as the named column or data cube defined by cols.
.le
.ls (nullval = -99) [int]
The numerical value to assign to NULLs found in an integer column of
an input ASCII table extension.  In all
other cases the TNULLn or BLANK keyword from the input extension is
used instead for integer data and NaN for real data.
.le
.ls (clobber = no) [boolean]
If outfile already exists and clobber=yes, outfile is deleted and a
new file created with the output image going into the primary array,
unless outfile contains a nonzero extension.  If clobber=no, the image
will be inserted into an already existing file, aborting if the file does
not exist.
.le
.ls (copykeys = yes) [boolean]
If copykeys=yes, the input header keywords are copied to the output
header, excluding the basic keywords and keywords which are probably
invalid after the operation.  If reading from a table, the relevant
TSCALn, TZEROn, and TUNITn are converted to BSCALE, BZERO, and BUNIT.
If copykeys=no, no keys are copied and the output header only contains
the necessary keywords for the image (NAXIS, etc).  It is recommended
that copykeys=yes if operation=STACK, but otherwise it may be safer to
have copykeys=no, since the data is being modified.
.le
.ls (history = yes) [boolean]
If history=yes, history keywords will be appended to the header,
listing the input file, input columns and rows, and the operation
performed.
.le
.ih
EXAMPLES
1. Copy the entire column CCDFRAME (an array) from extension 3 of file
OBSERV.FITS into a new primary array in OBJECT3.FITS.  NULLs should be
assigned values of -9 in the resulting image.
.nj
.ls
fi> fimgextract OBSERV.FITS[3] OBJECT3.FITS CCDFRAME - clobber=yes
nullval=-9
.ju
.le

2. Average rows 3-20 of CCDFRAME and place result immediately after the
primary array of OBJECT3.FITS.
.nj
.ls
fi> fimgextract OBSERV.FITS[3] OBJECT3.FITS[1] CCDFRAME 3-20
operation=AVG copykeys=no
.ju
.le

3. Copy rows 1-3, row 5, and all rows 9 and higher of a small region
of a 3-D primary array into a new file.
.ls
.nj
fi> fimgextract OBJECT3.FITS ISOLATE.FITS 5-25,12-30 1-3,5,9-
clobber=yes
.ju
.le

4. Sum all the entries of an arbitrary N-dimensional array, creating
an array of dimension N-1.
.nj
.ls
fi> fimgextract Ndim.fits Mdim.fits - - operation=sum
.ju
.le
.ih
BUGS
.ih
SEE ALSO
fvec2img
.endhelp
