---

6.2.3.6 Stacking operators

The operators in this section are used when you have multiple datasets that you would like to merge into one, commonly known as “stacking” or “coaddition”. For example, you have taken ten exposures of your scientific target, and you would like to combine them all into one deep stacked image that is deeper.

When calling these operators you should determine how many operands they should take in (unlike the rest of the operators that have a fixed number of input operands). As described in the first operand below, you do this through their first popped operand (which should be a single integer number that is larger than one).

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 variable-operand operators similar to it that are discussed below) will work in multi-threaded mode unless Arithmetic is called with the --numthreads=1 option, see Multi-threaded 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 --output=min.fits

Important notes:

• NaN/blank pixels will be ignored, see Blank pixels.
• The output will have the same type as the inputs. This is natural for the min and max operators, but for other similar operators (for example, sum, or average) the per-pixel 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.
• The operation will be multi-threaded, greatly speeding up the process if you have large and numerous data to stack. You can disable multi-threaded operations with the --numthreads=1 option (see Multi-threaded operations).

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. For example

$ astarithmetic a.fits b.fits c.fits 3 max -omax.fits

number

For each pixel count the number of non-blank pixels in all given datasets. The output will be an unsigned 32-bit integer datatype (see Numeric data types). This operator is called similar to the min operator, please see there for more. For example

$ astarithmetic a.fits b.fits c.fits 3 number -onum.fits

Some datasets may have blank values (which are also ignored in all similar operators like min, sum, mean or median). Hence, the final pixel values of this operator will not, in general, be equal to the number of inputs. This operator is therefore mostly called in parallel with those operators to know the “weight” of each pixel (in case you want to only keep pixels that had the full exposure for example).

sum

For each pixel, calculate the sum in all given datasets. The output will have the a single-precision (32-bit) floating point type. This operator is called similar to the min operator, please see there for more. For example

$ astarithmetic a.fits b.fits c.fits 3 sum -ostack-sum.fits

mean

For each pixel, calculate the mean in all given datasets. The output will have the a single-precision (32-bit) floating point type. This operator is called similar to the min operator, please see there for more. For example

$ astarithmetic a.fits b.fits c.fits 3 mean -ocoadd-mean.fits

std

For each pixel, find the standard deviation in all given datasets. The output will have the a single-precision (32-bit) floating point type. This operator is called similar to the min operator, please see there for more. For example

$ astarithmetic a.fits b.fits c.fits 3 std -ostd.fits

median

For each pixel, find the median in all given datasets. The output will have the a single-precision (32-bit) floating point type. This operator is called similar to the min operator, please see there for more. For example

$ astarithmetic a.fits b.fits c.fits 3 median \
                --output=stack-median.fits

quantile

For each pixel, find the quantile from all given datasets. The output will have the same numeric data type and size as the input datasets. Besides the input datasets, the quantile operator also needs a single parameter (the requested quantile). The parameter should be the first popped operand, with a value between (and including) 0 and 1. The second popped operand must be the number of datasets to use.

In the example below, the first-popped operand (0.7) is the quantile, the second-popped operand (3) is the number of datasets to pop.

astarithmetic a.fits b.fits c.fits 3 0.7 quantile

sigclip-number

For each pixel, find the sigma-clipped number (after removing outliers) in all given datasets. The output will have the an unsigned 32-bit 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 sigma-clipping) 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, or equal to, 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 sigma-clipping. 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 sigclip-number

sigclip-median

For each pixel, find the sigma-clipped median in all given datasets. The output will have the a single-precision (32-bit) floating point type. This operator is called similar to the sigclip-number operator, please see there for more. For example

astarithmetic a.fits b.fits c.fits 3 5 0.2 sigclip-median

sigclip-mean

For each pixel, find the sigma-clipped mean in all given datasets. The output will have the a single-precision (32-bit) floating point type. This operator is called similar to the sigclip-number operator, please see there for more. For example

astarithmetic a.fits b.fits c.fits 3 5 0.2 sigclip-mean

sigclip-std

For each pixel, find the sigma-clipped standard deviation in all given datasets. The output will have the a single-precision (32-bit) floating point type. This operator is called similar to the sigclip-number operator, please see there for more. For example

astarithmetic a.fits b.fits c.fits 3 5 0.2 sigclip-std