Next: Invoking astarithmetic, Previous: Reverse polish notation, Up: Arithmetic [Contents][Index]
The recognized operators in Arithmetic are listed below. See Reverse polish notation for more on how the operators and operands should be
ordered on the commandline. The operands to all operators can be a data
array (for example a FITS image) or a number, the output will be an array
or number according to the inputs. For example a number multiplied by an
array will produce an array. The conditional operators will return pixel,
or numerical values of 0 (false) or 1 (true) and stored in an
unsigned char
data type (see Numeric data types).
+
Addition, so “4 5 +
” is equivalent to \(4+5\).

Subtraction, so “4 5 
” is equivalent to \(45\).
x
Multiplication, so “4 5 x
” is equivalent to
\(4\times5\).
/
Division, so “4 5 /
” is equivalent to \(4/5\).
%
Modulo (remainder), so “3 2 %
” is equivalent to
\(1\). Note that the modulo operator only works on integer types.
abs
Absolute value of first operand, so “4 abs
” is
equivalent to \(4\).
pow
First operand to the power of the second, so “4.3 5f pow
” is
equivalent to \(4.3^{5}\). Currently pow
will only work on
single or double precision floating point numbers or images. To be sure
that a number is read as a floating point (even if it doesn’t have any
nonzero decimals) put an f
after it.
sqrt
The square root of the first operand, so “5 sqrt
” is equivalent
to \(\sqrt{5}\). The output will have a floating point type, but its
precision is determined from the input: if the input is a 64bit floating
point, the output will also be 64bit. Otherwise, the output will be 32bit
floating point (see Numeric data types for the respective
precision). Therefore if you require 64bit precision in estimating the
square root, convert the input to 64bit floating point first, for example
with 5 float64 sqrt
.
log
Natural logarithm of first operand, so “4 log
” is equivalent to
\(ln(4)\). The output type is determined from the input, see the
explanation under sqrt
for more.
log10
Base10 logarithm of first operand, so “4 log10
” is equivalent
to \(\log(4)\). The output type is determined from the input, see the
explanation under sqrt
for more.
minvalue
Minimum (nonblank) value in the top operand on the stack, so
“a.fits minvalue
” will push the the minimum pixel value in this
image onto the stack. Therefore this operator is mainly intended for data
(for example images), if the top operand is a number, this operator just
returns it without any change. So note that when this operator acts on a
single image, the output will no longer be an image, but a number. The
output of this operand is in the same type as the input.
maxvalue
Maximum (nonblank) value of first operand in the same type, similar to
minvalue
.
numbervalue
Number of nonblank elements in first operand in the uint64
type,
similar to minvalue
.
sumvalue
Sum of nonblank elements in first operand in the float32
type,
similar to minvalue
.
meanvalue
Mean value of nonblank elements in first operand in the float32
type, similar to minvalue
.
stdvalue
Standard deviation of nonblank elements in first operand in the
float32
type, similar to minvalue
.
medianvalue
Median of nonblank elements in first operand with the same type, similar
to minvalue
.
min
For each pixel, find the minimum value in all given datasets. The output will have the same type as the input.
The first popped operand to this operator must be a positive integer number which specifies how many further operands should be popped from the stack. All the subsequently popped operands must have the same type and size. This operator (and all the variableoperand operators similar to it that are discussed below) will work in multithreaded mode unless Arithmetic is called with the numthreads=1 option, see Multithreaded operations.
Each pixel of the output of the min
operator will be given the
minimum value of the same pixel from all the popped operands/images. For
example the following command will produce an image with the same size and
type as the three inputs, but each output pixel value will be the minimum
of the same pixel’s values in all three input images.
$ astarithmetic a.fits b.fits c.fits 3 min
Important notes:
min
and max
operators, but for other similar operators
(for example sum
, or average
) the perpixel operations
will be done in double precision floating point and then stored back in the
input type. Therefore, if the input was an integer, C’s internal type
conversion will be used.
max
For each pixel, find the maximum value in all given datasets. The output
will have the same type as the input. This operator is called similar to
the min
operator, please see there for more.
number
For each pixel count the number of nonblank pixels in all given
datasets. The output will be an unsigned 32bit integer datatype (see
Numeric data types). This operator is called similar to the
min
operator, please see there for more.
sum
For each pixel, calculate the sum in all given datasets. The output will
have the a singleprecision (32bit) floating point type. This operator is
called similar to the min
operator, please see there for more.
mean
For each pixel, calculate the mean in all given datasets. The output will
have the a singleprecision (32bit) floating point type. This operator is
called similar to the min
operator, please see there for more.
std
For each pixel, find the standard deviation in all given datasets. The
output will have the a singleprecision (32bit) floating point type. This
operator is called similar to the min
operator, please see there
for more.
median
For each pixel, find the median in all given datasets. The output will have
the a singleprecision (32bit) floating point type. This operator is
called similar to the min
operator, please see there for more.
sigclipnumber
For each pixel, find the sigmaclipped number (after removing outliers) in all given datasets. The output will have the an unsigned 32bit integer type (see Numeric data types).
This operator will combine the specified number of inputs into a single
output that contains the number of remaining elements after
\(\sigma\)clipping on each element/pixel (for more on
\(\sigma\)clipping, see Sigma clipping). This operator is very
similar to min
, with the exception that it expects two operands
(parameters for sigmaclipping) before the total number of inputs. The
first popped operand is the termination criteria and the second is the
multiple of \(\sigma\).
For example in the command below, the first popped operand (0.2
)
is the sigma clipping termination criteria. If the termination criteria is
larger than 1 it is interpreted as the number of clips to do. But if it is
between 0 and 1, then it is the tolerance level on the standard deviation
(see Sigma clipping). The second popped operand (5
) is the
multiple of sigma to use in sigmaclipping. The third popped operand
(10
) is number of datasets that will be used (similar to the
first popped operand to min
).
astarithmetic a.fits b.fits c.fits 3 5 0.2 sigclipnumber
sigclipmedian
For each pixel, find the sigmaclipped median in all given datasets. The
output will have the a singleprecision (32bit) floating point type. This
operator is called similar to the sigclipnumber
operator, please
see there for more.
sigclipmean
For each pixel, find the sigmaclipped mean in all given datasets. The
output will have the a singleprecision (32bit) floating point type. This
operator is called similar to the sigclipnumber
operator, please
see there for more.
sigclipstd
For each pixel, find the sigmaclipped standard deviation in all given
datasets. The output will have the a singleprecision (32bit) floating
point type. This operator is called similar to the sigclipnumber
operator, please see there for more.
filtermean
Apply mean filtering (or moving average) on the input dataset. During mean filtering, each pixel (data element) is replaced by the mean value of all its surrounding pixels (excluding blank values). The number of surrounding pixels in each dimension (to calculate the mean) is determined through the earlier operands that have been pushed onto the stack prior to the input dataset. The number of necessary operands is determined by the dimensions of the input dataset (first popped operand). The order of the dimensions on the commandline is the order in FITS format. Here is one example:
$ astarithmetic 5 4 image.fits filtermean
In this example, each pixel is replaced by the mean of a 5 by 4 box around it. The box is 5 pixels along the first FITS dimension (horizontal when viewed in ds9) and 4 pixels along the second FITS dimension (vertical).
Each pixel will be placed in the center of the box that the mean is calculated on. If the given width along a dimension is even, then the center is assumed to be between the pixels (not in the center of a pixel). When the pixel is close to the edge, the pixels of the box that fall outside the image are ignored. Therefore, on the edge, less points will be used in calculating the mean.
The final effect of mean filtering is to smooth the input image, it is essentially a convolution with a kernel that has identical values for all its pixels (is flat), see Convolution process.
Note that blank pixels will also be affected by this operator: if there are
any nonblank elements in the box surrounding a blank pixel, in the
filtered image, it will have the mean of the nonblank elements, therefore
it won’t be blank any more. If blank elements are important for your
analysis, you can use the isblank
with the where
operator to
set them back to blank after filtering.
filtermedian
Apply median filtering
on the input dataset. This is very similar to filtermean
, except
that instead of the mean value of the box pixels, the median value is used
to replace a pixel value. For more on how to use this operator, please see
filtermean
.
The median is less susceptible to outliers compared to the mean. As a result, after median filtering, the pixel values will be more discontinuous than mean filtering.
filtersigclipmean
Apply a \(\sigma\)clipped mean filtering onto the input dataset. This
is very similar to filtermean
, except that all outliers (identified
by the \(\sigma\)clipping algorithm) have been removed, see
Sigma clipping for more on the basics of this algorithm. As described
there, two extra input parameters are necessary for
\(\sigma\)clipping: the multiple of \(\sigma\) and the
termination criteria. filtersigclipmean
therefore needs to pop two
other operands from the stack after the dimensions of the box.
For example the line below uses the same box size as the example of
filtermean
. However, all elements in the box that are iteratively
beyond \(3\sigma\) of the distribution’s median are removed from the
final calculation of the mean until the change in \(\sigma\) is less
than \(0.2\).
$ astarithmetic 3 0.2 5 4 image.fits filtersigclipmean
The median (which needs a sorted dataset) is necessary for
\(\sigma\)clipping, therefore filtersigclipmean
can be
significantly slower than filtermean
. However, if there are strong
outliers in the dataset that you want to ignore (for example emission lines
on a spectrum when finding the continuum), this is a much better solution.
filtersigclipmedian
Apply a \(\sigma\)clipped median filtering onto the input
dataset. This operator and its necessary operands are almost identical to
filtersigclipmean
, except that after \(\sigma\)clipping, the
median value (which is less affected by outliers than the mean) is added
back to the stack.
interpolatemedianngb
Interpolate all the blank elements of the second popped operand with the median of its nearest nonblank neighbors. The number of the nearest nonblank neighbors used to calculate the median is given by the first popped operand. Note that the distance of the nearest nonblank neighbors is irrelevant in this interpolation.
collapsesum
Collapse the given dataset (second popped operand), by summing all elements along the first popped operand (a dimension in FITS standard: counting from one, from fastest dimension). The returned dataset has one dimension less compared to the input.
The output will have a doubleprecision floating point type irrespective of the input dataset’s type. Doing the operation in doubleprecision (64bit) floating point will help the collapse (summation) be affected less by floating point errors. But afterwards, singleprecision floating points are usually enough in real (noisy) datasets. So depending on the type of the input and its nature, it is recommended to use one of the type conversion operators on the returned dataset.
If any WCS is present, the returned dataset will also lack the respective dimension in its WCS matrix. Therefore, when the WCS is important for later processing, be sure that the input is aligned with the respective axises: all nondiagonal elements in the WCS matrix are zero.
One common application of this operator is the creation of pseudo broadband or narrowband 2D images from 3D data cubes. For example integral field unit (IFU) data products that have two spatial dimensions (first two FITS dimensions) and one spectral dimension (third FITS dimension). The command below will collapse the whole third dimension into a 2D array the size of the first two dimensions, and then convert the output to singleprecision floating point (as discussed above).
$ astarithmetic cube.fits 3 collapsesum float32
collapsemean
Similar to collapsesum, but the returned dataset will be the mean value along the collapsed dimension, not the sum.
collapsenumber
Similar to collapsesum, but the returned dataset will be the number of nonblank values along the collapsed dimension. The output will have a 32bit signed integer type. If the input dataset doesn’t have blank values, all the elements in the returned dataset will have a single value (the length of the collapsed dimension). Therefore this is mostly relevant when there are blank values in the dataset.
collapsemin
Similar to collapsesum, but the returned dataset will have the same numeric type as the input and will contain the minimum value for each pixel along the collapsed dimension.
collapsemax
Similar to collapsesum, but the returned dataset will have the same numeric type as the input and will contain the maximum value for each pixel along the collapsed dimension.
unique
Remove all duplicate (and blank) elements from the first popped operand. The unique elements of the dataset will be stored in a singledimensional dataset.
Recall that by default, singledimensional datasets are stored as a table column in the output. But you can use onedasimage to store them as a singledimensional FITS array/image.
erode
Erode the foreground pixels (with value 1
) of the input dataset
(second popped operand). The first popped operand is the connectivity (see
description in connectedcomponents
). Erosion is simply a
flipping of all foreground pixels (to background; with value 0
) that
are “touching” background pixels. “Touching” is defined by the
connectivity. In effect, this carves off the outer borders of the
foreground, making them thinner. This operator assumes a binary dataset
(all pixels are 0
and 1
).
dilate
Dilate the foreground pixels (with value 1
) of the input dataset
(second popped operand). The first popped operand is the connectivity (see
description in connectedcomponents
). Erosion is simply a
flipping of all background pixels (with value 0
) to foreground that
are “touching” foreground pixels. “Touching” is defined by the
connectivity. In effect, this expands the outer borders of the
foreground. This operator assumes a binary dataset (all pixels are 0
and 1
).
connectedcomponents
Find the connected components in the input dataset (second popped operand). The first popped is the connectivity used in the connected components algorithm. The second popped operand is the dataset where connected components are to be found. It is assumed to be a binary image (with values of 0 or 1). It must have an 8bit unsigned integer type which is the format produced by conditional operators. This operator will return a labeled dataset where the nonzero pixels in the input will be labeled with a counter (starting from 1).
The connectivity is a number between 1 and the number of dimensions in the dataset (inclusive). 1 corresponds to the weakest (symmetric) connectivity between elements and the number of dimensions the strongest. For example on a 2D image, a connectivity of 1 corresponds to 4connected neighbors and 2 corresponds to 8connected neighbors.
One example usage of this operator can be the identification of regions above a certain threshold, as in the command below. With this command, Arithmetic will first separate all pixels greater than 100 into a binary image (where pixels with a value of 1 are above that value). Afterwards, it will label all those that are connected.
$ astarithmetic in.fits 100 gt 2 connectedcomponents
If your input dataset doesn’t have a binary type, but you know all its
values are 0 or 1, you can use the uint8
operator (below) to convert
it to binary.
fillholes
Flip background (0) pixels surrounded by foreground (1) in a binary
dataset. This operator takes two operands (similar to
connectedcomponents
): the first popped operand is the connectivity
(to define a hole) and the second is the binary (0 or 1 valued) dataset to
fill holes in.
invert
Invert an unsigned integer dataset. This is the only operator that ignores blank values (which are set to be the maximum values in the unsigned integer types).
This is useful in cases where the target(s) has(have) been imaged in absorption as raw formats (which are unsigned integer types). With this option, the maximum value for the given type will be subtracted from each pixel value, thus “inverting” the image, so the target(s) can be treated as emission. This can be useful when the higherlevel analysis methods/tools only work on emission (positive skew in the noise, not negative).
lt
Less than: If the second popped (or left operand in infix notation, see
Reverse polish notation) value is smaller than the first popped
operand, then this function will return a value of 1, otherwise it will
return a value of 0. If both operands are images, then all the pixels will
be compared with their counterparts in the other image. If only one operand
is an image, then all the pixels will be compared with the the single value
(number) of the other operand. Finally if both are numbers, then the output
is also just one number (0 or 1). When the output is not a single number,
it will be stored as an unsigned char
type.
le
Less or equal: similar to lt
(‘less than’ operator), but returning 1
when the second popped operand is smaller or equal to the first.
gt
Greater than: similar to lt
(‘less than’ operator), but
returning 1 when the second popped operand is greater than the first.
ge
Greater or equal: similar to lt
(‘less than’ operator), but
returning 1 when the second popped operand is larger or equal to the first.
eq
Equality: similar to lt
(‘less than’ operator), but returning 1 when
the two popped operands are equal (to double precision floating point
accuracy).
ne
NonEquality: similar to lt
(‘less than’ operator), but returning 1
when the two popped operands are not equal (to double precision
floating point accuracy).
and
Logical AND: returns 1 if both operands have a nonzero value and 0 if both are zero. Both operands have to be the same kind: either both images or both numbers.
or
Logical OR: returns 1 if either one of the operands is nonzero and 0 only when both operators are zero. Both operands have to be the same kind: either both images or both numbers.
not
Logical NOT: returns 1 when the operand is zero and 0 when the operand is nonzero. The operand can be an image or number, for an image, it is applied to each pixel separately.
isblank
Test for a blank value (see Blank pixels). In essence, this is very similar to the conditional operators: the output is either 1 or 0 (see the ‘less than’ operator above). The difference is that it only needs one operand. Because of the definition of a blank pixel, a blank value is not even equal to itself, so you cannot use the equal operator above to select blank pixels. See the “Blank pixels” box below for more on Blank pixels in Arithmetic.
where
Change the input (pixel) value where/if a certain condition
holds. The conditional operators above can be used to define the
condition. Three operands are required for where
. The input
format is demonstrated in this simplified example:
$ astarithmetic modify.fits binary.fits iftrue.fits where
The value of any pixel in modify.fits that corresponds to a nonzero and nonblank pixel of binary.fits will be changed to the value of the same pixel in iftrue.fits (this may also be a number). The 3rd and 2nd popped operands (modify.fits and binary.fits respectively, see Reverse polish notation) have to have the same dimensions/size. iftrue.fits can be either a number, or have the same dimension/size as the other two.
The 2nd popped operand (binary.fits) has to have uint8
(or
unsigned char
in standard C) type (see Numeric data types). It
is treated as a binary dataset (with only two values: zero and nonzero,
hence the name binary.fits
in this example). However, commonly you
won’t be dealing with an actual FITS file of a condition/binary image. You
will probably define the condition in the same run based on some other
reference image and use the conditional and logical operators above to make
a true/false (or one/zero) image for you internally. For example the case
below:
$ astarithmetic in.fits reference.fits 100 gt new.fits where
In the example above, any of the in.fits pixels that has a value in
reference.fits greater than 100
, will be replaced with the
corresponding pixel in new.fits. Effectively the
reference.fits 100 gt
part created the condition/binary image which
was added to the stack (in memory) and later used by where
. The
command above is thus equivalent to these two commands:
$ astarithmetic reference.fits 100 gt output=binary.fits $ astarithmetic in.fits binary.fits new.fits where
Finally, the input operands are read and used independently, so you can use the same file more than once as any of the operands.
When the 1st popped operand to where
(iftrue.fits) is a
single number, it may be a NaN value (or any blank value, depending on its
type) like the example below (see Blank pixels). When the number is
blank, it will be converted to the blank value of the type of the 3rd
popped operand (in.fits
). Hence, in the example below, all the
pixels in reference.fits that have a value greater than 100, will
become blank in the natural data type of in.fits (even though NaN
values are only defined for floating point types).
$ astarithmetic in.fits reference.fits 100 gt nan where
bitand
Bitwise AND operator: only bits with values of 1 in both popped operands
will get the value of 1, the rest will be set to 0. For example (assuming
numbers can be written as bit strings on the commandline): 00101000
00100010 bitand
will give 00100000
. Note that the bitwise operators
only work on integer type datasets.
bitor
Bitwise inclusive OR operator: The bits where at least one of the two popped
operands has a 1 value get a value of 1, the others 0. For example
(assuming numbers can be written as bit strings on the commandline):
00101000 00100010 bitand
will give 00101010
. Note that the
bitwise operators only work on integer type datasets.
bitxor
Bitwise exclusive OR operator: A bit will be 1 if it differs between the
two popped operands. For example (assuming numbers can be written as bit
strings on the commandline): 00101000 00100010 bitand
will give
00001010
. Note that the bitwise operators only work on integer type
datasets.
lshift
Bitwise left shift operator: shift all the bits of the first operand to the
left by a number of times given by the second operand. For example
(assuming numbers can be written as bit strings on the commandline):
00101000 2 lshift
will give 10100000
. This is equivalent to
multiplication by 4. Note that the bitwise operators only work on integer
type datasets.
rshift
Bitwise right shift operator: shift all the bits of the first operand to
the right by a number of times given by the second operand. For example
(assuming numbers can be written as bit strings on the commandline):
00101000 2 rshift
will give 00001010
. Note that the bitwise
operators only work on integer type datasets.
bitnot
Bitwise not (more formally known as one’s complement) operator: flip all
the bits of the popped operand (note that this is the only unary, or single
operand, bitwise operator). In other words, any bit with a value of
0
is changed to 1
and viceversa. For example (assuming
numbers can be written as bit strings on the commandline): 00101000
bitnot
will give 11010111
. Note that the bitwise operators only
work on integer type datasets/numbers.
uint8
Convert the type of the popped operand to 8bit unsigned integer type (see Numeric data types). The internal conversion of C will be used.
int8
Convert the type of the popped operand to 8bit signed integer type (see Numeric data types). The internal conversion of C will be used.
uint16
Convert the type of the popped operand to 16bit unsigned integer type (see Numeric data types). The internal conversion of C will be used.
int16
Convert the type of the popped operand to 16bit signed integer (see Numeric data types). The internal conversion of C will be used.
uint32
Convert the type of the popped operand to 32bit unsigned integer type (see Numeric data types). The internal conversion of C will be used.
int32
Convert the type of the popped operand to 32bit signed integer type (see Numeric data types). The internal conversion of C will be used.
uint64
Convert the type of the popped operand to 64bit unsigned integer (see Numeric data types). The internal conversion of C will be used.
float32
Convert the type of the popped operand to 32bit (single precision) floating point (see Numeric data types). The internal conversion of C will be used.
float64
Convert the type of the popped operand to 64bit (double precision) floating point (see Numeric data types). The internal conversion of C will be used.
setAAA
Set the characters after the dash (AAA
in the case shown here) as a
name for the first popped operand on the stack. The named dataset will be
freed from memory as soon as it is no longer needed, or if the name is
reset to refer to another dataset later in the command. This operator thus
enables reusability of a dataset without having to reread it from a file
every time it is necessary during a process. When a dataset is necessary
more than once, this operator can thus help simplify reading/writing on the
commandline (thus avoiding potential bugs), while also speeding up the
processing.
Like all operators, this operator pops the top operand off of the main processing stack, but unlike other operands, it won’t add anything back to the stack immediately. It will keep the popped dataset in memory through a separate list of named datasets (not on the main stack). That list will be used to add/copy any requested dataset to the main processing stack when the name is called.
The name to give the popped dataset is part of the operator’s name. For
example the seta
operator of the command below, gives the name
“a
” to the contents of image.fits. This name is then used
instead of the actual filename to multiply the dataset by two.
$ astarithmetic image.fits seta a 2 x
The name can be any string, but avoid strings ending with standard filename suffixes (for example .fits)^{97}.
One example of the usefulness of this operator is in the where
operator. For example, let’s assume you want to mask all pixels larger than
5
in image.fits (extension number 1) with a NaN
value. Without setting a name for the dataset, you have to read the file
two times from memory in a command like this:
$ astarithmetic image.fits image.fits 5 gt nan where g1
But with this operator you can simply give image.fits the name
i
and simplify the command above to the more readable one below
(which greatly helps when the filename is long):
$ astarithmetic image.fits seti i i 5 gt nan where
tofileAAA
Write the top operand on the operands stack into a file called AAA
(can be any FITS file name) without changing the operands stack. If you
don’t need the dataset any more and would like to free it, see the
tofilefree
operator below.
By default, any file that is given to this operator is deleted before Arithmetic actually starts working on the input datasets. The deletion can be deactivated with the dontdelete option (as in all Gnuastro programs, see Input/Output options). If the same FITS file is given to this operator multiple times, it will contain multiple extensions (in the same order that it was called.
For example the operator tofilecheck.fits
will write the top
operand to check.fits. Since it doesn’t modify the operands stack,
this operator is very convenient when you want to debug, or understanding,
a string of operators and operands given to Arithmetic: simply put
tofileAAA
anywhere in the process to see what is happening
behind the scenes without modifying the overall process.
tofilefreeAAA
Similar to the tofile
operator, with the only difference that the
dataset that is written to a file is popped from the operand stack and
freed from memory (cannot be used any more).
Blank pixels in Arithmetic: Blank pixels in the image (see
Blank pixels) will be stored based on the data type. When the input
is floating point type, blank values are NaN. One aspect of NaN values is
that by definition they will fail on any comparison. Hence both
equal and notequal operators will fail when both their operands are NaN!
Therefore, the only way to guarantee selection of blank pixels is through
the One way you can exploit this property of the NaN value to your advantage is when you want a fully zerovalued image (even over the blank pixels) based on an already existing image (with same size and world coordinate system settings). The following command will produce this for you: $ astarithmetic input.fits nan eq output=allzeros.fits Note that on the commandline you can write NaN in any case (for example

A dataset name like
a.fits (which can be set with seta.fits
) will cause
confusion in the the initial parser of Arithmetic. It will assume this name
is a FITS file, and if it is used multiple times, Arithmetic will abort,
complaining that you haven’t provided enough HDUs.
Next: Invoking astarithmetic, Previous: Reverse polish notation, Up: Arithmetic [Contents][Index]
JavaScript license information
GNU Astronomy Utilities 0.10 manual, August 2019.