NAME

fimgextract -- Extract a (vector) column from a table or a subset from an array, optionally summing over the rows.

USAGE

        fimgextract infile outfile cols rows

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.

PARAMETERS

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.

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.

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="-".

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.

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

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

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

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

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

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.

        fi> fimgextract OBSERV.FITS[3] OBJECT3.FITS CCDFRAME - clobber=yes
            nullval=-9

2. Average rows 3-20 of CCDFRAME and place result immediately after the primary array of OBJECT3.FITS.

        fi> fimgextract OBSERV.FITS[3] OBJECT3.FITS[1] CCDFRAME 3-20
          operation=AVG copykeys=no

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.

        fi> fimgextract OBJECT3.FITS ISOLATE.FITS 5-25,12-30 1-3,5,9-
          clobber=yes

4. Sum all the entries of an arbitrary N-dimensional array, creating an array of dimension N-1.

        fi> fimgextract Ndim.fits Mdim.fits - - operation=sum

BUGS

SEE ALSO

fvec2img

CATEGORY