GNU Astronomy Utilities



6.2.4.7 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). Below are Some important points for all the stacking operators described in this section:

min
max
sum
std
mad
mean
median
number

For each pixel, calculate the respective statistic from in all given datasets. For the min and max operators, the output will have the same type as the input. For the number operator, the output will have an unsigned 32-bit integer type and the rest will be 32-bit floating point.

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.

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

Regarding the number operator: 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).

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
madclip-fill-mad
madclip-fill-std
madclip-fill-mean
madclip-fill-median
madclip-fill-number

Find the respective statistic after median absolute deviation (MAD) filled re-clipping of the values of the same element (pixel in an image) of all the inputs. For a complete tutorial on clipping outliers see Clipping outliers (if you haven’t read it yet, we encourage you to read through it before continuing). For the particular case of filled re-clipping (the madclip-fill-* operators here) see Filled re-clipping. Spoiler alert: this is currently the most robust stacking operator in Gnuastro.

The output data type of all these operators is a 32-bit floating point number, except for madclip-fill-number, where an unsigned 32-bit integer is returned (see Numeric data types). This operator will combine the given inputs into a single output of the same dimension as one of the inputs. Each pixel of the output contains the requested statistic from the remaining values after filled MAD re-clipping. This operator is very similar to min, with the exception that it expects two extra operands (parameters for MAD-clipping) before the total number of inputs. The first popped operand is the termination criteria and the second is the multiple of the median absolute deviation.

For example, in the command below, the first popped operand (0.01) is the MAD-clipping termination criteria. If the termination criteria is larger than, or equal to, 1 it is interpreted as a pre-defined the number of clips. But if it is between 0 and 1, then it is the tolerance level on the change in the median absolute deviation (see MAD clipping). The second popped operand (5) is the multiple of the median absolute deviation to use in MAD-clipping. The third popped operand (3) 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.01 madclip-fill-std
madclip-mad
madclip-std
madclip-mean
madclip-median
madclip-number

Find the number of useful values after median absolute deviation (MAD) clipping of the values of the same element (pixel in an image) of all the inputs. These operators are called in an identical fashion to the madclip-fill-* operators described above; see the description there for more.

sigclip-fill-number

Find the number of useful values after filled sigma (\(\sigma\), which stands for the standard deviation) re-clipping of the values of the same element (pixel in an image) of all the inputs. For a complete tutorial on clipping outliers see Clipping outliers (if you haven’t read it yet, we encourage you to read through it before continuing). For the particular case of filled re-clipping (the sigclip-fill-* operators here) see Filled re-clipping. Spoiler alert: MAD filled re-clipping is currently most robust stacking operator in Gnuastro (the madclip-fill-* operators).

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-fill-number
sigclip-fill-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-fill-number operator, please see there for more. For example

astarithmetic a.fits b.fits c.fits 3 5 0.2 sigclip-fill-median
sigclip-fill-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-fill-number operator, please see there for more. For example

astarithmetic a.fits b.fits c.fits 3 5 0.2 sigclip-fill-mean
sigclip-fill-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-fill-number operator, please see there for more. For example

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

For each pixel, find the \(\sigma\)-clipped median absolute deviation (MAD) 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-fill-number operator, please see there for more. For example

astarithmetic a.fits b.fits c.fits 3 5 0.2 sigclip-fill-mad
sigclip-number

Find the number of useful values after sigma (\(\sigma\), which stands for the standard deviation) clipping of the values of the same element (pixel in an image) of all the inputs. For a complete tutorial on clipping outliers see Clipping outliers (if you haven’t read it yet, we encourage you to read through it before continuing). For the particular case of \(\sigma\)-clipping (the sigclip-* operators here) see Sigma clipping. Spoiler alert: MAD filled re-clipping is currently most robust stacking operator in Gnuastro (the madclip-fill-* operators).

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
sigclip-mad

For each pixel, find the \(\sigma\)-clipped median absolute deviation (MAD) 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-mad