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):
## Note that without the '.0', the '2' will be read/used as an integer.
$ astarithmetic image1.fits image2.fits + 2.0 / --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
Arithmetic’s notation for giving operands to operators is fully described in Reverse polish notation. The output dataset is last remaining operand on the stack. When the output dataset a single number, and --output is not called, it will be printed on the standard output (command-line). When the output is an array, it will be stored as a file.
The name of the final file can be specified with the --output option, but if it is not given (and the output dataset has more than one element), Arithmetic will use “automatic output” on the name of the first FITS image encountered to generate an output file name, see Automatic output.
By default, if the output file already exists, it will be deleted before Arithmetic starts operation.
However, this can be disabled with the --dontdelete option (see below).
At any point during Arithmetic’s operation, you can also write the top operand on the stack to a file, using the tofile or tofilefree operators, see Arithmetic operators.
By default, the world coordinate system (WCS) information of the output dataset will be taken from the first input image (that contains a WCS) on the command-line. This can be modified with the --wcsfile and --wcshdu options described below. When the --quiet option is not given, the name and extension of the dataset used for the output’s WCS is printed on the command-line.
Through operators like those starting with collapse-, the dimensionality of the inputs may not be the same as the outputs.
By default, when the output is 1D, Arithmetic will write it as a table, not an image/array.
The format of the output table (plain text or FITS ASCII or binary) can be set with the --tableformat option, see Input/Output options).
You can disable this feature (write 1D arrays as FITS images/arrays, or to the standard output) with the --onedasimage or --onedonstdout options.
See Common options for a review of the options in all Gnuastro programs. Arithmetic just redefines the --hdu and --dontdelete options as explained below.
A plain-text file containing the command-line arguments that will be used by Arithmetic. This option is only relevant when no arguments are given on the command-line: if any arguments are given, this option is ignored.
This is necessary when the set of of input files and operators (arguments; see Arguments and options) are very long (thousands of long file names for example; usually generated within large pipelines).
Such long arguments will cause the shell to abort with an Argument list too long error.
In such cases, you can put the list into a plain-text file and use this option like below (assuming you want to stack all the files in a certain directory with the mean operator; see Stacking operators):
$ counter=0;
$ for f in $(pwd)/*.fits; do \
echo $f; counter=$((counter+1)); \
done > arguments.txt; \
echo "$counter mean" >> arguments.txt
$ astarithmetic --arguments=list.txt -g1
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.
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.
FITS Filename containing the WCS structure that must be written to the output. The HDU/extension should be specified with --wcshdu.
When this option is used, the respective WCS will be read before any processing is done on the command-line and directly used in the final output. If the given file does not have any WCS, then the default WCS (first file on the command-line with WCS) will be used in the output.
This option will mostly be used when the default file (first of the set of inputs) is not the one containing your desired WCS. But with this option, you can also use Arithmetic to rewrite/change the WCS of an existing FITS dataset from another file:
$ astarithmetic data.fits --wcsfile=other.fits -ofinal.fits
HDU/extension to read the WCS within the file given to --wcsfile. For more, see the description of --wcsfile.
Use the environment for the random number generator settings in operators that need them (for example, mknoise-sigma).
This is very important for obtaining reproducible results, for more see Generating random numbers.
Metadata (name) of the output dataset.
For a FITS image or table, the string given to this option is written in the EXTNAME or TTYPE1 keyword (respectively).
If this keyword is present in a FITS extension, it will be printed in the table output of a command like astfits image.fits (for images) or asttable table.fits -i (for tables).
This metadata can be very helpful for yourself in the future (when you have forgotten the details), so it is recommended to use this option for files that should be archived or shared with colleagues.
Metadata (units) of the output dataset.
For a FITS image or table, the string given to this option is written in the BUNIT or TTYPE1 keyword respectively.
In the case of tables, recall that the Arithmetic program only outputs a single column, you should use column arithmetic in Table for more than one column (see Column arithmetic).
For more on the importance of metadata, see the description of --metaname.
Metadata (comments) of the output dataset.
For a FITS image or table, the string given to this option is written in the COMMENT or TCOMM1 keyword respectively.
In the case of tables, recall that the Arithmetic program only outputs a single column, you should use column arithmetic in Table for more than one column (see Column arithmetic).
For more on the importance of metadata, see the description of --metaname.
Write final dataset as a FITS image/array even if it has a single dimension. By default, if the output is 1D, it will be written as a table, see above. If the output has more than one dimension, this option is redundant.
Write final dataset (only when it is 1D) to standard output, not as a file. By default 1D datasets will be written as a table, see above. If the output has more than one dimension, this option is redundant.
Do not delete the output file, or files given to the tofile or tofilefree operators, if they already exist.
Instead append the desired datasets to the extensions that already exist in the respective file.
Note it does not matter if the final output file name is given with the --output option, or determined automatically.
Arithmetic treats this option differently from its default operation in other Gnuastro programs (see Input/Output options). If the output file exists, when other Gnuastro programs are called with --dontdelete, they simply complain and abort. But when Arithmetic is called with --dontdelete, it will appended the dataset(s) to the existing extension(s) in the file.
Write all datasets on the stack as separate HDUs in the output file. This only affects datasets with multiple dimensions (or single-dimension datasets when the --onedasimg is called). This option is useful to debug Arithmetic calls: to check all the images on the stack while you are designing your operation. The top dataset on the stack will be on HDU number 1 of the output, the second dataset will be on HDU number 2 and so on.
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, put a . after it (possibly followed by a zero for easier readability), or add an f after it.
Hence while 5 will be read as an integer, 5., 5.0 or 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).
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.
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, do not 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
GNU Astronomy Utilities 0.22 manual, February 2024.