FITS Table Calculator

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" was checked, it will applied only to the selected rows in table.

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.

• NEWCOL = 100.0 + TIME

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

• RATE = 2.0 * RATE

  Multiply 2.0 with column RATE and replace the old RATE column.

• NEWCOL = 0.0

  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.

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

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

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

  NEWCOL = ASCIICOL

  NEWCOL = TIME

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

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

Arithmetic functions supported:

• abs(x)
• acos(x)
• asin(x)
• atan(x)
• atan2(y,x)
• ceil(x)
• cos(x)
• cosh(x)
• exp(x)
• floor(x)
• log(x)
• log10(x)
• min(x,y)
• max(x,y)
• random()
• round(x)
• sin(x)
• sinh(x)
• sqrt(x)
• tan(x)
• tanh(x)

Vector functions supported:

• nelem(x)
• sum(x)

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