Harvard-Smithsonian Center for Astrophysics, 60 Garden Street MS 81, Cambridge, MA 02138

Massachusetts Institute of Technology, Center for Space Research

We have developed a format convention that allows one to specify an
* n*-dimensional function in a FITS binary table, the FITS Embedded
Function (FEF). The format allows for enumerated values, constants,
and analytical functions, and arithmetic combinations of those three.
The parameters of the analytical functions may, again, be enumerated,
constant, or function values.
The concept is intended to allow the user to extract a
multi-dimensional subimage from a FEF in the same way one would
extract a subimage from a primary array or image extension. The
format is extremely versatile and has many potential applications.
Developing a generic FEF extractor is very challenging but will allow
very cost-effective reuse.

The FITS standard provides for the definition of * n*-dimensional images
of data points, but in certain situations it can be extremely useful
to have the ability to store an image in parameterized form, as an
arbitrary function of parameters (coordinate axes). Just as one can
extract a sub-image from a primary HDU or an image extension, one
should be able to extract an * n*-dimensional sub-image of enumerated
values from an extension containing such a parameterized image.

In cases where the parameterization is possible, this representation
effects a huge savings in storage space. We have developed a
convention that accommodates arbitrary function specifications using
FITS binary tables. We have called it the * FITS Embedded Function*
(FEF).

As an example, within the Chandra X-ray Center we have applied the FITS Embedded Function to the Chandra response matrix specification. As a result, a generic FEF image extractor will be able to construct response matrices using the FEF response matrix definition.

Function tables are identified by:

HDUCLASS= 'ASC ' HDUCLAS1= 'FUNCTION'

The function is defined by:

FUNCTION= '<expression>' FUNCNAME= '<name>'

The function expression may contain the arithmetic operators , , , , , and five types of operands or ``parameters:''

- FTYPE
*i*: axes of the function evaluation space; these may just be specified as a range or may also appear as a table column (TTYPE*j*) if other parameters are to be enumerated along such an axis. - DTYPE
*i*: constants; the name is provided by DTYPE*i*, the value by DVAL*i*, and the units by DUNIT*i*. This is the ``constant column.'' - TTYPE
*i*: parameters enumerated in table column*i*. - VTYPE
*i*: function components; the name is provided by VTYPE*i*, the function expression by VFUNC*i*. This is the ``virtual function column.'' - WTYPE
*i*: arithmetic components; the name is provided by WTYPE*i*, the arithmetic expression by WFUNC*i*. This is the ``virtual arithmetic column.''

The assumption is that implementation of a FEF reader will include the following functionality.

typedef struct { char name[32] ; double min ; double max ; int num ; } FefParam ; FefParam parms[n] ; fits_file fef ; double* image = readFef (fef, n, parms) ;

Extraneous columns are allowed. However, one should take care when
filtering on such a column (or any other, for that matter), that such
filtering can only be guaranteed to yield a valid FEF extension if all
but one of the FTYPE variables contains more than one point. Even
then, it will still require that all FAXIS* i* keywords are corrected.

The evaluation space of the function (or the image coordinates, if you like) is set by a set of ``pseudo coordinate axis'' keywords:

- FTYPE
*i*: - FAXIS: The number of coordinate axes in evaluation space
- FAXIS
*i*: The number of points along axis i (for enumerated axes only) - FTYPE
*i*: Name of axis i - FLMIN
*i*: Legal minimum values for axis i (required for free-running variables) - FLMAX
*i*: Legal maximum values for axis i (required for free-running variables)

FLMIN and FLMAX are clearly needed for free-running variables to define the range over which the function is defined.

We shall assume that if function values are requested for values of
enumerated variables that fall between the enumerated grip points, the
values of all enumerated
columns will be interpolated linearly. It is important to note that
* the parameter values are interpolated, not the function values.*

If the values of an entire row are to be held constant for a range of values of an enumerated variable, one may specify bins by using a FTYPE_LO and FTYPE_HI column.

In some cases (sparse images, e.g., response matrices) it is desirable
to limit the
domain of a free running variable depending on the values of the
enumerated variables. This may be done by incorporating two columns
for FDMIN* i* and FDMAX* i*.

The FUNCTION definition is an arithmetic expression in which the
operands may be the * values* of any of the following:
FTYPE* n*,
DTYPE* n*,
TTYPE* n*,
VTYPE* n*, and
WTYPE* n*,
with operators , , , , , and parentheses allowed, as
in:

FUNCTION= 'Norm - Scale * (X2 + Y2)' FUNCNAME= 'HRMA_EffArea' BUNIT = 'mm**2 '

Virtual function columns (VTYPE* i*) are defined through functions:

VFUNCi = 'G(P1, P2, P3, ...; C)'where is chosen from a defined set of function names and where may be the value of any valid operand--one of the following: FTYPE

Note that allowing VTYPEs and WTYPEs to be used in the definition of VTYPEs provides for the specification of nested functions. This is a powerful capability that requires particular care to prevent recursion.

In general, arithmetic virtual columns (WTYPE* i*) are defined as:

WFUNCi = 'P1 ^ P2 ^ ...'Where ``^ '' denotes an arithmetic operator , , , , , and parentheses are allowed. may be the value of any of the following: FTYPE

This project is supported by the Chandra X-ray Center under NASA contract NAS8-39073.

© Copyright 2001 Astronomical Society of the Pacific, 390 Ashton Avenue, San Francisco, California 94112, USA

adass-editors@head-cfa.harvard.edu