Search:

[Advanced Search]



FITS Table Calculator

[See also the Calculator Expressions help file for more details on the expression syntax].

The calculator tool can be used to perform spread-sheet type calculations on columns in a FITS table. The expression is evaluated on each row of the table and the result is written either to an existing column in the table (overwriting the previous values), or to a new column. If "Apply only to selected rows" is checked, then the calculation will only be applied to the selected rows that have the row number (in the first column) highlighted.

Results Column

The entry field on the left hand side of the "=" sign is used to specify the name of the column to which the results will be written. Click on the the 'down arrow' icon to bring up a selection menu with a list of all the existing columns in the table. Otherwise, a new column name may be entered, in which case a new column with that name will be created when the calculation is performed.

Normally, when creating a new column, the column's data type will be the same as that of the expression. That is, an integer expression will create a 4-byte integer column (TFORM = 1J) and a real expression will create an 8-byte double column (TFORM = 1D). This can be overridden by placing the desired TFORM value within parentheses after the column's name. For example, specifying a column name NewCol(1E) will create a new column named 'NewCol' with a TFORM of '1E'. (The numerical value is optional and will be filled in with the vector size of the expression.) The expression's results will thus be converted to a 4-byte real when written to the column, even though the result could be of type integer or double.

Formula

The entry field on the right hand side of the "=" sign is for entering the expression for calculation. You can either type in the expression or use the buttons. To use a column in the calculation, one just inserts the column's name. Below are some sample expressions.

  1. Add 100.0 to column TIME and save it as a new column with name NEWCOL:

    NEWCOL = 100.0 + TIME

  2. Multiply the RATE column by 2.0, overwriting the old RATE column value:

    RATE = 2.0 * RATE

  3. Create a new column with all the element value = 0.0 and save it in the table. This can also be used to create a new ASCII column with a initial value, e.g. NEWSCOL = "string value". Be sure the string has the quote characters around it.

    NEWCOL = 0.0

  4. Conditional operations ( > , < , == , >= , <= , && , || ) are also allowed. You can perform conditional evaluations, such as

    NEWCOL = (COLUMN1 > 3.0) ? expr1 : expr2

    The result of the above expression is expr1 if values in COLUMN1 is greater than 3.0, otherwise, expr2.

  5. Individual elements of a vector column may be referenced by specifying the element number within square brackets, as in:

    NEWCOL = COUNTS[1] + COUNTS[3]

    which will create a new scalar column equal to the sum of the 1st and 3rd elements of the COUNTS vector column.

  6. The value in an ASCII character column (TFORMn = 'A') may be used in conditional calculation using the '==', '!=', '>', and '<' operators. e.g. if a table lists the declination of a set of objects in 3 separate columns, one for the sign ('+' or '-') and 2 integer columns giving the degrees and minutes values, the the declination value in decimal degree can be calculated by:

    Dec = (deg_sign != "-") * (degree + minute/60.) - (deg_sign == "-") * (degree + minute/60.)

    In effect, the conditional expressions evaluate to 1 if true and 0 if false when multiplied by a numerical value.

  7. The calculator can also be used to copy one column to a new column. e.g.

    NEWCOL = ASCIICOL

    NEWCOL = TIME

    Illegal operations such as divide by zero will result in a Null value.

    To access a table entry in a row other than the current one, follow the column's name with a row offset within curly braces. For example, 'PHA{-3}' will evaluate to the value of column PHA, 3 rows above the row currently being processed. One cannot specify an absolute row number, only a relative offset. Rows that fall outside the table will be treated as undefined, or NULLs.

    If a calculation involves a column with Nulls or NaNs for certain rows, then these rows in the result column will be Nulls. An exception is if the Null is encountered within an && or || construction whose value is determined by the nonNull value. For example, "TRUE || NULL" evaluates to TRUE. The calculator has several special functions which can be used to test for Null values in columns.

    Calculator pad

    The expression to be calculated may be constructed by clicking on the calculator function buttons in the left 1/3 of the the window. Alternatively, the expression may be typed in directly in the formula window.

    Column name listing

    All the column names are listed as buttons. Clicking on any of them will insert (replacing any selected text) the column name in the formula window. If the number of columns is greater than 24, the "Up" and "Down" buttons can be used to scroll through the column name list.

    Functions

    Below are lists of all the functions supported by the calculator. For detailed descriptions of its operations, see the Calculator Expressions help file.

    Arithmetic functions supported:

    • abs(x)
    • cos(x)
    • sin(x)
    • tan(x)
    • acos(x)
    • asin(x)
    • atan(x)
    • atan2(y,x)
    • cosh(x)
    • sinh(x)
    • tanh(x)
    • round(x) - round to nearest integer
    • ceil(x) - round up to nearest integer
    • floor(x) - round down to nearest integer
    • exp(x)
    • sqrt(x)
    • log(x)
    • log10(x)
    • min(x,y)
    • max(x,y)
    • i % j - modulus operator
    • random() - random number in range [0.0, 1.0)
    • b?x:y - if 'b' then 'x', else 'y'

    Vector functions supported:

    • min(x)
    • max(x)
    • average(x)
    • median(x)
    • stddev(x) - Standard Deviation
    • sum(x)
    • nelem(x) - size of the vector
    • nvalid(x) - No. of non-null elements

    Boolean functions supported:

    • circle(x0,y0,R,rot,X,Y)
    • ellipse(x0,y0,Rx,Ry,rot,X,Y)
    • box(x0,y0,Rx,Ry,rot,X,Y)
    • near(x,y,delta)
    • gtifilter("file",time,"start","stop")
    • regfilter("file",X,Y,"wcs")

    NULL functions supported:

    • isnull(x)
    • defnull(x,y)

    Type conversions supported:

    • (double)x or (float)x
    • (int)x
    Go to About fv.
    Pages maintained by Bryan Irby
    Send bug reports or feature requests via the FTOOLS help desk.
    HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public
    Last modified: Thursday, 16-Jul-2009 14:09:18 EDT