finterp -- Interpolate a column from one FITS table extension into another.
finterp infile1 infile2 outfile incol [sortkey1] [sortkey2] [order]
[tcheck] [extrap] [strnull] [intnull]
The finterp task interpolates the values from one FITS table using an interpolation key from another table. As an example, it is a way to interpolate a light curve with tabulated TIME values to another time grid with different TIME values. Although TIME is used as an example here, the data is not required to be light curve data, nor are the interpolation keys required to be TIME.
This task uses the following notation.
infile2 is the "tabulated" table containing source data to be interpolated. The interpolation index key is the column in infile2 named by sortkey2. The column or columns to be interpolated are named by incol, and these columns must be present in this table.
infile1 is the "destination" table where interpolated results are desired. The interpolation index key is the column named by sortkey1. The interpolated columns named by incol will be placed in this table. The resulting output with interpolated values will be placed in outfile. (Outfile is allowed to be the same as infile1, in which case infile1 is modified in place.)
The file containing the destination table may be copied to a new file, and the output from the program written to this copy, thus leaving the original file intact. The user may also opt to write the program output directly into the destination table in the original file. (see parameter outfile below).
For each row of the destination table infile1, the task attempts to find values in the tabulated column from which a representative single value may be interpolated. Tabulated values are selected based on a comparison of the sort key columns. The value of column sortkey1 in the given destination row is used as a look-up index into the tabulated table using column sortkey2. See the discussion of parameters sortkey1 and sortkey2 for more details of the interpolation process, and restrictions on the data types and values these columns may contain.
Options also exist for how to handle rows of the destination column which are out of bounds, that is, for which no value of the destination column can be computed, based on the values in the sort key columns (see EXTRAPOLATION below, as well as documentation of strnull and intnull below).
The method for computing values in the source column to use for the interpolation is as follows. For each row in the column sortkey1 (destination), the column sortkey2 (source) is searched for two sequential values which form an interval containing the value in sortkey1. The corresponding values of the source column are then used to perform the interpolation.
The allowed interpolation options are order=0 (nearest neighbor), order=1 (linear), and order=-1 (log-linear). Nearest neighbor interpolation is allowed for any column data type, including logical and string. Linear and log-linear interpolation is only allowed for tabulated columns with numerical data types.
Nearest neighbor (order=0, or 0th order interpolation, is a direct copy of the nearest tabulated column value selected by comparison of the sort key columns (always looking toward the lower bracketing tabulated sample).
Linear interpolation (order=1), or 1st order interpolation, is a linear interpolation between tabulated samples. If either of the two bracketing tabulated samples is NULL, then the output is NULL.
Log-linear interpolation (order=-1), is comparable to interpolation in log space (i.e. if plotted on a log plot, the interpolation would be linear in that space). The sort key values are still treated linearly however (hence, log-lin interpolation). This option is most useful for tabulated values that vary over many orders of magnitude and would typically be plotted on a log plot. If either of the two bracketing samples is non-positive (or NULL) then the output is NULL.
In both tables, the index key columns must be a scalar numerical type (i.e. not a vector), and monotonically increasing.
Each of the tabulated columns listed in incol will be interpolated and inserted into the output table (plus, optionally renamed or changing data type as described in the ADVANCED OPTIONS section below).
The tabulated column(s) may be of any data type, and there are no restrictions on the values they may hold. The task also properly handles scaled-integer values (using TSCALn and TZEROn keywords).
If the named column already exists in the destination file, its numerical type will be kept unchanged, regardless of the data type of the tabulated column (and regardless of any data-type changing request specified with advanced options described below). However, the description, units and any data scaling descriptors (such as TSCALn and TZEROn) will be transferred from the tabulated column.
If the named column already exists in the destination file, a check is made to determine if the the existing column can accomodate the tabulated data with a similar precision and dynamic range, or better. If instead the numerical precision would be degraded, finterp will refuse to make the interpolation by default, but this error can be disabled using the parameter setting errdegrade=NO. Even so, the internal FITS library CFITSIO may generate an error if the interpolated quantities exceed the allowed numerical data range of the output column data type. This error condition cannot be disabled.
Interpolation of a logical column to an existing numerical destination is allowed if order=0; False is interpolated as 0 and True as 1.
The tabulated column may be a vector valued column. In this case, each vector element is interpolated individually using the sort keys, and the vector array structure of the input is transferred to the output. In other words, vector element 1 of the column is interpolated using the sort keys, then vector element 2, and so on. This task does not interpolate between elements of the vector.
A new column with the same name and qualities as the tabulated column will be inserted at the end of the destination table if a column with this name does not already exist. The standard FITS tabular keywords are copied to the output (TFORMn, TTYPEn, TNULLn, TUNITn, TSCALn, TZEROn, TDISPn). Also, the standard World Coordinate System (WCS) keywords for pixel lists are also copied, if present.
The input column name maybe a single FITS column name. The user may also specify multiple columns in a comma-separated list.
If the sort key columns contain time stamps, the user has the option of having the program check and correct for differences between the temporal origins in the tabulated and destination files. When this option is selected, a consistency check of the time units is also performed (see parameter tcheck below).
If tcheck is "YES", the keywords TIMESYS and TIMEUNIT will be checked in the source and destination table extensions. The program will correctly account for any differences in temporal origins reflected in the keywords TIMESYS. An error is generated if the keyword TIMESYS is missing in either table. An error is also generated if the units specified by TIMEUNIT are different. However, the units will be ignored if the keyword TIMEUNIT is missing from either table. If tcheck is "NO", no consistency check is performed.
For sortkey1 only (i.e. for the destination table), it is possible to use an expression enclosed in parentheses, rather than a column name. This expression must follow the CFITSIO calculator expression syntax rules (use 'fhelp calc_express' to learn more). This allows the user to use more complicated matching expressions. For example, if infile2 is tabulated by TIME in seconds and infile1 is tabulated by TIME in minutes, one can use sortkey1="(TIME*60)" to convert its TIME column to match the units of seconds in infile2. Time checking with tcheck=YES is ignored in this case however.
The list of input columns, incol, may provide additional transformative descriptors, which allow renaming or changing the data type of the resulting column.
By default, incols is a comma-separated list of column names that will be found in the tabulated file.
incols=COLNAME1,COLNAME2,...
These same column names will be used in the output file by default. To use different names, use the following syntax.
incols=NEWCOLNAME1=COLNAME1,...
where NEWCOLNAME1 is the name of the new column in the output file. COLNAME1 will be used as the source column name from the tabulated file.
incols=NEWCOLNAME1(c)=COLNAME1,...
means to change the output column data type to the type specified by 'c'. The character corresponds to FITS data type characters ('I' for integer*2, 'J' for integer*4, 'E' for real*4, 'D' for real*8, etc). See below for some restrictions on data type changing. For example, NEW_RATE(E)=RATE will make a new column named NEW_RATE based on RATE in infile2, and the new column will be single precision floating point ('E').
incols=COLNAME(c)
will not change the column name, but will change the data type as described above. Note that when the data type is changed, the any TNULLn, TZEROn or TSCALn keywords that may be present for that column are not transferred to the new file, but other FITS standard keywords such as TUNITn and TDIMn are transferred.
Important restriction: if the desired column name already exists in the destination file, then the (c) character is ignored and the data type of this column is kept unchanged. If the requested column is an integer with TSCALn or TZEROn scalings, these will be transferred to the output table in order to preserve the scalings, but the fundamental numerical type of the column will not be changed if it already exists in the output.
The extrap parameter chooses what action to take in rows of the destination table which are "out of bounds". A row is "out of bounds" if no interval can be extracted from the source key column which contains the destination key value for that row. Out of bounds rows can only occur at the beginning or the end of a destination table, because their sort key values must come "before" the first row of the source table, or "after" the last row of the source table. Note that any rows of the destination column which are NOT out of bounds are set to undefined if and only if the corresponding source column value(s) are undefined, regardless of the value of this parameter.
There are three choices for the extrap parameter:
NULL - set out of bounds rows in the destination column to undefined, using the parameters strnull and intnull below, if necessary. This is also the default selection made if a null string is entered for the extrap parameter.
REPEAT - repeatedly copy a value from the source column to all rows in the destination column which are out of bounds. The first value in the source column is copied to all rows of the destination column whose key value is smaller than the first source key value. The last value in the source column is copied to all rows of the destination column whose key value is larger than the last source key value.
IGNORE - do not write anything at all if rows are out of bounds. This is useful if several different source files, covering different, disjoint ranges of the destination table, are to be interpolated one at a time into the same destination table without overwriting each other.
1. Interpolate a column named ETI, with TTYPE = '4B' from the 1st extension in file hk.fits into the 1st extension of file events.fits. Store the result in file output.fits.
ft>finterp events.fits+1 hk.fits+1 output.fits ETI
2. Interpolate a column named VALUE, with TTYPE = '1J' from the 3rd extension of file hk1.fits into the 2nd extension of file events.fits. Store the result in file output.fits. For undefined values, use the integer -999. Perform the linear interpolation option. (Assume that the extensions are both binary tables.)
ft>finterp events.fits[2] hk1.fits[3] output.fits VALUE \
order = 1 intnull = -999
Now, perform a similar interpolation from a second file, hk2.fits, storing the results in place in the file output.fits. Do not take any action on out of bounds rows, as this would overwrite some of the values which were just written.
ft>finterp output.fits[2] hk2.fits[3] output.fits VALUE \
order = 1 extrap = IGNORE
3. Perform an interpolation of two column values, RA and DEC, in a single call to the finterp task.
ft>finterp table.fits[1] catalog.fits[1] table2.fits RA,DEC \
order=1
The multiple columns are given as a comma-separated list to the incol keyword parameter.
4. Interpolate a column named LOCATION, TTYPE = 'A80' from the file atlas.fits into the file travel_log.fits. Use the column in each file named MILEAGE as its sort key, and set undefined values to the string NOWHERE. Store the results in place in the file travel_log.fits. It is necessary to disable time checking, since the sort keys do not contain time stamp data. (Assume that the extensions in both files are ASCII tables.)
ft>finterp travel_log.fits+1 atlas.fits+1 travel_log.fits \
LOCATION sortkey1 = MILEAGE sortkey2 = MILEAGE \
tcheck = no strnull = NOWHERE
In this example, it is assumed that the columns named MILEAGE in each column contain values which may be converted to numbers, and that these numbers are in ascending order.