GNU Astronomy Utilities


Next: , Previous: , Up: Table   [Contents][Index]


5.4.1 Column arithmetic

After reading the requested columns from the input table, you can also do operations/arithmetic on the columns and save the resulting values as new column(s) in the output table (possibly in between other requested columns). To enable column arithmetic, the first 6 characters of the value to --column (-c) should be the arithmetic activation word ‘arith ’ (note the space character in the end, after ‘arith’).

After the activation word, you can use the reverse polish notation to identify the operators and their operands, see Reverse polish notation. Just note that white-space characters are used between the tokens of the arithmetic expression and that they are meaningful to the command-line environment. Therefore the whole expression (including the activation word) has to be quoted on the command-line or in a shell script (see the examples below).

To identify a column you can directly use its name, or specify its number (counting from one, see Selecting table columns). When you are giving a column number, it is necessary to prefix it with a c (otherwise it is not distinguishable from a constant number to use in the arithmetic operation).

For example with the command below, the first two columns of table.fits will be printed along with a third column that is the result of multiplying the first column with \(10^{10}\) (for example to convert wavelength from Meters to Angstroms). Note how without the ‘c’, it is not possible to distinguish between 1 as a column-counter, or as a constant number to use in the arithmetic operation.

$ asttable table.fits -c1,2 -c"arith c1 1e10 x"

Alternatively, if the columns have meta-data and the first two are respectively called AWAV and SPECTRUM, the command above is equivalent to the command below. Note that the c is no longer necessary in this scenario.

$ asttable table.fits -cAWAV,SPECTRUM -c"arith AWAV 1e10 x"

Comparison of the two commands above clearly shows why it is recommended to use column names instead of numbers. When the columns have clear names, the command/script actually becomes much more readable, describing the intent of the operation. It is also independent of the low-level table structure: for the second command, the position of the AWAV and SPECTRUM columns in table.fits is irrelevant.

Finally, since the arithmetic expressions are a value to --column, it doesn’t necessarily have to be a separate option, so the commands above are also identical to the command below (note that this only has one -c option). Just be very careful with the quoting!

$ asttable table.fits -cAWAV,SPECTRUM,"arith AWAV 1e10 x"

Almost all the arithmetic operators of Arithmetic operators are also supported for column arithmetic in Table. In particular, the few that are not present in the Gnuastro library aren’t yet supported. For a list of the Gnuastro library arithmetic operators, please see the macros starting with GAL_ARITHMETIC_OP and ending with the operator name in Arithmetic on datasets (arithmetic.h). Besides the operators in Arithmetic operators, several operators are only available in Table to use on table columns.

wcstoimg

Convert the given WCS positions to image/dataset coordinates based on the number of dimensions in the WCS structure of --wcshdu extension/HDU in --wcsfile. It will output the same number of columns. The first popped operand is the last FITS dimension.

For example the two commands below (which have the same output) will produce 5 columns. The first three columns are the input table’s ID, RA and Dec columns. The fourth and fifth columns will be the pixel positions in image.fits that correspond to each RA and Dec.

$ asttable table.fits -cID,RA,DEC,"arith RA DEC wcstoimg" \
           --wcsfile=image.fits
$ asttable table.fits -cID,RA -cDEC \
           -c"arith RA DEC wcstoimg" --wcsfile=image.fits
imgtowcs

Similar to wcstoimg, except that image/dataset coordinates are converted to WCS coordinates.

angular-distance

Return the spherical angular distance (along a great circle, in degrees) between the given two points. Note that each point needs two coordinates (in degrees), so this operator needs four operands. The first and second popped operands are considered to belong to one point and the third and fourth popped operands to the second point.

Each of the input points can be a single coordinate or a full table column (containing many points. In other words, the following commands are all valid:

$ asttable table.fits \
           -c"arith RA1 DEC1 RA2 DEC2 angular-distance"
$ asttable table.fits \
           -c"arith RA DEC 12.345 6.789 angular-distance"
$ asttable table.fits \
           -c"arith 12.345 6.789 RA DEC angular-distance"

In the first case we are assuming that table.fits has the following four columns RA1, DEC1, RA2, DEC2. The returned column by this operator would be the difference between two points in each row with coordinates like the following (RA1, DEC1) and (RA2, DEC2). In other words, for each row, the angular distance between different points is calculated.

In the second and third cases (which are identical), it is assumed that table.fits has the two columns RA and DEC. The returned column by this operator will be the difference of each row with the fixed point of (12.345, 6.789).

The distance (along a great circle) on a sphere between two points is calculated with the equation below, where \(r_1\), \(r_2\), \(d_1\) and \(d_2\) are the right ascensions and declinations of points 1 and 2.

$$\cos(d)=\sin(d_1)\sin(d_2)+\cos(d_1)\cos(d_2)\cos(r_1-r_2)$$


Next: , Previous: , Up: Table   [Contents][Index]