FCALC (Oct93) ftools.futils FCALC (Oct93) NAME fcalc -- Calculates values for a column using an arithmetic expression. USAGE fcalc infile[ext#] outfile column expr DESCRIPTION This task creates a new table from a using an arithmetic expression applied to the values stored in the input table's columns. Variables in the arithmetic expression represent columns in the input file. The named column for the results will be created unless it already exits. If the column named to store the results of the expression already exist, its values will be overwritten. Using the hidden parameters, fcalc will copy the primary extension, all extensions, all columns in the extension where the arithmetic expression is applied. Boolean operators can be used in the expression in either their Fortran or C forms. The following boolean operators can be used in the expression: .nf "equal" .eq. .EQ. == "not equal" .ne. .NE. != "less than" .lt. .LT. < "less than/equal" .le. .LE. <= =< "greater than" .gt. .GT. > "greater than/equal" .ge. .GE. >= => "or" .or. .OR. || "and" .and. .AND. && "negation" .not. .NOT. ! "approx. equal(1e-7)" ~ The expression may also include arithmetic operators and functions. Trigonometric functions use degrees, not radians. The following arithmetic operators and functions can be used in the expression: "addition" + "subtraction" - "multiplication" * "division" / "negation" - "exponentiation" ** ^ "absolute value" abs(x) "cosine" cos(x) "sine" sin(x) "tangent" tan(x) "arc cosine" arccos(x) "arc sine" arcsin(x) "arc tangent" arctan(x) "arc tangent" arctan2(x,y) "exponential" exp(x) "square root" sqrt(x) "natural log" log(x) "common log" log10(x) "modulus" i % j There are two functions that are primarily for use with SAO region files and the FSAOI task, but they can be used directly. They return a boolean true or false depending on whether a two dimensional point is in the region or not: "point in a rectangular region" -1- FCALC (Oct93) ftools.futils FCALC (Oct93) BOX(xcntr,ycntr,xhlf_wdth,yhlf_wdth,rotation,Xcolumn,Ycolumn) box(xcntr,ycntr,xhlf_wdth,yhlf_wdth,rotation,Xcolumn,Ycolumn) "point in an elliptical region" ELLIPSE(xcntr,ycntr,xhlf_wdth,yhlf_wdth,rotation,Xcolumn,Ycolumn) ellipse(xcntr,ycntr,xhlf_wdth,yhlf_wdth,rotation,Xcolumn,Ycolumn) where (xcntr,ycntr) are the (x,y) position of the center of the region (xhlf_wdth,yhlf_wdth) are the (x,y) half widths of the region (rotation) is the angle(degrees) that the region is rotated wrt (x,y) (Xcolumn,Ycolumn) are the (x,y) column names in the FITS table There is also a function for testing if two values are close to each other, i.e., if they are "near" each other to within a user specified tolerance.The arguments, value_1 and value_2 can be integer or real and represent the two values who's proximity is being tested to be within the specified tolerance, also an integer or real: near(value_1, value_2, tolerance) NEAR(value_1, value_2, tolerance) The following type casting operators are available, where the inclosing parentheses are required and taken from the C language usage. Also, the integer to real casts values to double precision: "real to integer" (int) x (INT) x "integer to real" (float) i (FLOAT) i In addition, several constants are built in for use in expressions: #pi 3.1415... #e 2.7182... #deg #pi/180 #row current row number A string constant must be enclosed in quotes as in 'Crab'. Due to the generalities of FITS column names, a column name which resembles an arithmetic or boolean expression must be enclosed in "$" characters as in $column-name$ to force its interpretation as a column and not as column minus name. Numerical keyword values found in the current TABLE extension's header my be used as part of the expression. Keywords should be preceded by a single "#" as in #MAXPHA. If the keyword contains a space or character might appear as an arithmetic term then inclose it in "$" characters as in #$MAX PHA$ or #$MAX-PHA$. Vector columns can also be used in building the expression. However, vector arithmetic is not supported. The expression for a vector column must give a single element from the vector column so that subsequent scalar evaluation on the whole expression will still reduce to a boolean. The convention for entering a vector is -2- FCALC (Oct93) ftools.futils FCALC (Oct93) to give the column name followed by a comma or semicolon separated list of coordinates inclosed in square brackets. For example, if a vector column named PHAS exists in the table with as a one dimensional, 256 component list of numbers from which you wanted to select the 57th component for use in the expression, then PHAS[57] would do the trick. Higher dimensional arrays of data may appear in a column. But in order to interpret them, the TDIMn keyword must appear in the header. Assuming that a (4,4,4,4) array is packed into each row of a column named ARRAY4D, the (1,2,3,4) component element of each row is accessed by either ARRAY4D[1,2,3,4] or ARRAY4D[1;2;3;4]. Arrays up to dimension 15 are currently supported. Vector columns which contain spaces or arithmetic operators must also be inclosed in "$" characters as with $ARRAY-4D[1,2,3,4]$. PARAMETERS infile [filename] A file name (including optional extension number in square brackets) of the FITS table to be searched. outfile [filename] The name of the created FITS file to contain the selected rows from the input table. If preceeded by a !, an existing file of the same name will be overwritten. column [string] Name of the column to contain the calculated values. If the column does not exist a new one will be created. If the column exists its values will be overwritten. expr [string] The boolean expression used to select out rows in the FITS file. (copycol=yes) [boolean] If true, all columns in the input table will be copied to the output table, otherwise only the column named by the column parameter will appear in the output table. (histkw=yes) [boolean] If true, history records will be added to the output file primary header indicating that fcalc created the file, and a history records of the expression used will be added to the extension header. (copyall=yes) [boolean] If true, all other extensions, including the primary array are copied to the output file. -3- FCALC (Oct93) ftools.futils FCALC (Oct93) (clobber=no) [boolean] If true, and existing file with the same name as the specified output file will be overwritten. EXAMPLES 1. Calculate the values for a column named AREA in the first extension of a the area.fits file using the columns X and Y found in the first extension of the input.fits file using the expression "X*Y": ft> fcalc input.fits area.fits AREA "X*Y" 2. Calculate the dot product of two 2-D vector columns, (A.B) of the input file named twovec.fits and store the result in the DOT column of the output file dot.fits: ft> fcalc twovec.fits dot.fits DOT "A[1]*B[1] + A[2]*B[2]" 3. Shift all the values in the ORIGIN column of the input file, in.fits by 5.50 and store the result in the same ORIGIN column of the output file out.fits: ft> fcalc in.fits out.fits ORIGIN "ORIGIN + 5.50" BUGS In IRAF, if fcalc has failed with an error condition, FLPRCACHE may be needed to flush the process cache. SEE ALSO fselect, maketime