Previous: Arithmetic operators, Up: Arithmetic [Contents][Index]

Arithmetic will do pixel to pixel arithmetic operations on the individual pixels of input data and/or numbers. For the full list of operators with explanations, please see Arithmetic operators. Any operand that only has a single element (number, or single pixel FITS image) will be read as a number, the rest of the inputs must have the same dimensions. The general template is:

$ astarithmetic [OPTION...] ASTRdata1 [ASTRdata2] OPERATOR ...

One line examples:

## Calculate (10.32-3.84)^2.7 quietly (will just print 155.329): $ astarithmetic -q 10.32 3.84 - 2.7 pow ## Inverse the input image (1/pixel): $ astarithmetic 1 image.fits / --out=inverse.fits ## Multiply each pixel in image by -1: $ astarithmetic image.fits -1 x --out=negative.fits ## Subtract extension 4 from extension 1 (counting from zero): $ astarithmetic image.fits image.fits - --out=skysub.fits \ --hdu=1 --hdu=4 ## Add two images, then divide them by 2 (2 is read as floating point): $ astarithmetic image1.fits image2.fits + 2f / --out=average.fits ## Use Arithmetic's average operator: $ astarithmetic image1.fits image2.fits average --out=average.fits ## Calculate the median of three images in three separate extensions: $ astarithmetic img1.fits img2.fits img3.fits median \ -h0 -h1 -h2 --out=median.fits

If the output is an image, and the `--output` option is not given,
automatic output will use the name of the first FITS image encountered to
generate an output file name, see Automatic output. Also, output WCS
information will be taken from the first input image encountered. When the
output is a single number, that number will be printed in the standard
output and no output file will be created. Arithmetic’s notation for giving
operands to operators is described in Reverse polish notation. To
ignore certain pixels, set them as blank, see Blank pixels, for
example with the `where`

operator (see Arithmetic operators). See Common options for a review of the options in all
Gnuastro programs. Arithmetic just redefines the `--hdu` option as
explained below:

`-h INT/STR``--hdu INT/STR`The header data unit of the input FITS images, see Input/Output options. Unlike most options in Gnuastro (which will ultimately only have one value for this option), Arithmetic allows

`--hdu`to be called multiple times and the value of each invocation will be stored separately (for the unlimited number of input images you would like to use). Recall that for other programs this (common) option only takes a single value. So in other programs, if you specify it multiple times on the command-line, only the last value will be used and in the configuration files, it will be ignored if it already has a value.The order of the values to

`--hdu`has to be in the same order as input FITS images. Options are first read from the command-line (from left to right), then top-down in each configuration file, see Configuration file precedence.If the number of HDUs is less than the number of input images, Arithmetic will abort and notify you. However, if there are more HDUs than FITS images, there is no problem: they will be used in the given order (every time a FITS image comes up on the stack) and the extra HDUs will be ignored in the end. So there is no problem with having extra HDUs in the configuration files and by default several HDUs with a value of

`0`are kept in the system-wide configuration file when you install Gnuastro.`-g INT/STR``--globalhdu INT/STR`Use the value to this option as the HDU of all input FITS files. This option is very convenient when you have many input files and the dataset of interest is in the same HDU of all the files. When this option is called, any values given to the

`--hdu`option (explained above) are ignored and will not be used.

Arithmetic accepts two kinds of input: images and numbers. Images are
considered to be any of the inputs that is a file name of a recognized type
(see Arguments) and has more than one element/pixel. Numbers on the
command-line will be read into the smallest type (see Numeric data types) that can store them, so `-2`

will be read as a `char`

type (which is signed on most systems and can thus keep negative values),
`2500`

will be read as an `unsigned short`

(all positive
numbers will be read as unsigned), while `3.1415926535897`

will be
read as a `double`

and `3.14`

will be read as a `float`

. To
force a number to be read as float, add a `f`

after it, so
`5f`

will be added to the stack as `float`

(see Reverse polish notation).

Unless otherwise stated (in Arithmetic operators), the operators can
deal with numeric multiple data types (see Numeric data types). For
example in “`a.fits b.fits +`

”, the image types can be
`long`

and `float`

. In such cases, C’s internal type conversion
will be used. The output type will be set to the higher-ranking type of the
two inputs. Unsigned integer types have smaller ranking than their signed
counterparts and floating point types have higher ranking than the integer
types. So the internal C type conversions done in the example above are
equivalent to this piece of C:

size_t i; long a[100]; float b[100], out[100]; for(i=0;i<100;++i) out[i]=a[i]+b[i];

Relying on the default C type conversion significantly speeds up the
processing and also requires less RAM (when using very large
images). However this great advantage comes at the cost of preparing for
all the combinations of types while building/compiling Gnuastro. With the
full list of CFITSIO types, compilation can take roughly half an
hour. However, some types are not too common, therefore Gnuastro comes with
a set of configure time options letting you enable certain types for native
compilation. You can see the full list of `--enable-bin-op-XXXX`
options in Gnuastro configure options.

When a type isn’t enabled for native binary operations, the input data will
be internally converted to the smallest, larger type that was enabled. This
can slow down your processing (which is faster for smaller/integer types)
and consume more RAM (to copy the new type), so if you often deal with data
of a specific types, it is much better to make the one-time investment at
compilation time and reap the benefits each time you run
Gnuastro/Arithmetic. Note all arithmetic operations are done by
`gal_data_arithmetic`

function in Gnuastro library, so the
choice of native binary operator types will affect any program (within
Gnuastro or outside of it) that uses this function (including Arithmetic).

Some operators can only work on integer types (of any length, for example
bitwise operators) while others only work on floating point types,
(currently only the `pow`

operator). In such cases, if the operand
type(s) are different an error will be printed and internal conversion
won’t occur. Arithmetic also comes with internal type conversion operators
which you can use to convert the data into the appropriate type, see
Arithmetic operators.

The hyphen (`-`

) can be used both to specify options (see
Options) and also to specify a negative number which might be
necessary in your arithmetic. In order to enable you to do this, Arithmetic
will first parse all the input strings and if the first character after a
hyphen is a digit, then that hyphen is temporarily replaced by the vertical
tab character which is not commonly used. The arguments are then parsed and
these strings will not be specified as an option. Then the given arguments
are parsed and any vertical tabs are replaced back with a hyphen so they
can be read as negative numbers. Therefore, as long as the names of the
files you want to work on, don’t start with a vertical tab followed by a
digit, there is no problem. An important consequence of this implementation
is that you should not write negative fractions like this: `-.3`

,
instead write them as `-0.3`

.

Without any images, Arithmetic will act like a simple calculator and print the resulting output number on the standard output like the first example above. If you really want such calculator operations on the command-line, AWK (GNU AWK is the most common implementation) is much faster, easier and much more powerful. For example, the numerical one-line example above can be done with the following command. In general AWK is a fantastic tool and GNU AWK has a wonderful manual (https://www.gnu.org/software/gawk/manual/). So if you often confront situations like this, or have to work with large text tables/catalogs, be sure to checkout AWK and simplify your life.

$ echo "" | awk '{print (10.32-3.84)^2.7}' 155.329

Previous: Arithmetic operators, Up: Arithmetic [Contents][Index]

GNU Astronomy Utilities 0.4 manual, September 2017.