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 spreadsheet 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 4byte integer column (TFORM = 1J) and
a real expression will create an 8byte 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 4byte 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.
 Add 100.0 to column TIME and save it as a new column with
name NEWCOL:
NEWCOL = 100.0 + TIME

Multiply the RATE column by 2.0, overwriting the old RATE
column value:
RATE = 2.0 * RATE

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
 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.
 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.
 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
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 nonnull 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:
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, 16Jul2009 14:09:18 EDT
