---

6.2.3.9 Dimensionality changing operators

Through these operators you can change the dimensions of the output through certain statistics on the dimensions that should be removed. For example, let’s assume you have a 3D data cube that has 300 by 300 pixels in the RA and Dec dimensions (first two dimensions), and 3600 slices along the wavelength (third dimension), so the whole cube is \(300\times300\times3600\) voxels (volume elements). To create a narrow-band image that only contains 100 slices around a certain wavelength, you can crop that section (using Crop), giving you a \(300\times300\times100\) cube. You can now use the collapse-sum operator below to “collapse” all the 100 slices into one 2D image that has \(300\times300\) pixels. Every pixel in this 2D image will have the flux of the sum of the 100 slices.

stitch

Stitch (connect) any number of given images together along the given dimension. The output has the same number of dimensions as the input, but the number of pixels along the requested dimension will be different from the inputs. The stitch operator takes at least three operands:

• The first popped operand (placed just before stitch) is the direction (dimension) that the images should be stitched along. The first FITS dimension is along the horizontal, therefore a value of 1 will stitch them horizontally. Similarly, giving a value of 2 will result in a vertical stitch.
• The second popped operand is the number of images that should be stitched.
• Depending on the value given to the second popped operand, stitch will pop the given number of datasets from the stack and stitch them along the given dimension. The popped images have to have the same number of pixels along the other dimension. The order of the stitching is defined by how they are placed in the command-line, not how they are popped (after being popped, they are placed in a list in the same order).

For example, in the commands below, we will first crop out fixed sized regions of \(100\times300\) pixels of a larger image (large.fits) first. In the first call of Arithmetic below, we will stitch the bottom set of crops together along the first (horizontal) axis. In the second Arithmetic call, we will stitch all 6 along both dimensions.

## Crop the fixed-size regions of a larger image ('-O' is the
## short form of the '--mode' option).
$ astcrop large.fits -Oimg --section=1:100,1:300     -oa.fits
$ astcrop large.fits -Oimg --section=101:200,1:300   -ob.fits
$ astcrop large.fits -Oimg --section=201:300,1:300   -oc.fits
$ astcrop large.fits -Oimg --section=1:100,301:600   -od.fits
$ astcrop large.fits -Oimg --section=101:200,301:600 -oe.fits
$ astcrop large.fits -Oimg --section=201:300,301:600 -of.fits

## Stitch the bottom three crops into one image.
$ astarithmetic a.fits b.fits c.fits 3 1 stitch -obottom.fits

# Stitch all the 6 crops along both dimensions
$ astarithmetic a.fits b.fits c.fits 3 1 stitch \
                d.fits e.fits f.fits 3 1 stitch \
                2 2 stitch -g1 -oall.fits

The start of the last command is like the one before it (stitching the bottom three crops along the first FITS dimension, producing a \(300\times300\) image). Later in the same command, we then stitch the top three crops horizontally (again, into a \(300\times300\) image) This leaves the the two \(300\times300\) images on the stack (see Reverse polish notation). We finally stitch those two along the second (vertical) dimension. This operator is therefore useful in scenarios like placing the CCD amplifiers into one image.

collapse-sum

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 double-precision floating point type irrespective of the input dataset’s type. Doing the operation in double-precision (64-bit) floating point will help the collapse (summation) be affected less by floating point errors. But afterwards, single-precision 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 axes: all non-diagonal elements in the WCS matrix are zero.

One common application of this operator is the creation of pseudo broad-band or narrow-band 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 single-precision floating point (as discussed above).

$ astarithmetic cube.fits 3 collapse-sum float32

collapse-mean

Similar to collapse-sum, but the returned dataset will be the mean value along the collapsed dimension, not the sum.

collapse-number

Similar to collapse-sum, but the returned dataset will be the number of non-blank values along the collapsed dimension. The output will have a 32-bit signed integer type. If the input dataset does not 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.

collapse-min

Similar to collapse-sum, 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.

collapse-max

Similar to collapse-sum, 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.

collapse-median

Similar to collapse-sum, but the returned dataset will have the same numeric type as the input and will contain the median value for each pixel along the collapsed dimension.

The median involves sorting, therefore collapse-median will do each calculation in different CPU threads to speed up the operation. By default, Arithmetic will detect and use all available threads, but you can override this with the --numthreads (or -N) option.

collapse-sigclip-mean

Collapse the input dataset (fourth popped operand) along the FITS dimension given as the first popped operand by calculating the sigma-clipped mean. The sigma-clipping parameters (namely, the multiple of sigma and termination criteria) are read as the third and second popped operands respectively. For more on sigma-clipping, see Sigma clipping.

For example, with the command below, the pixels of the input 2 dimensional image.fits will be collapsed to a single dimension output. The first popped operand is 2, so it will collapse all the pixels that are vertically on top of each other. Such that the output will have the same number of pixels as the horizontal axis of the input. During the collapsing, all pixels that are more than \(3\sigma\) (third popped operand) are rejected, and the clipping will continue until the standard deviation changes less than \(0.2\) between clips.

$ astarithmetic image.fits 3 0.2 2 collapse-sigclip-mean \
                --output=collapsed-vertical.fits

Printing output of collapse in plain-text: the default datatype of collapse-sigclip-mean is 32-bit floating point. This is sufficient for any observed astronomical data. However, if you request a plain-text output, or decide to print/view the output as plain-text on the standard output, the full set of decimals may not be printed in some situations. This can lead to apparently discrete values in the output of this operator when viewed in plain-text! The FITS format is always superior (since it stores the value in binary, therefore not having the problem above). But if you are forced to save the output in plain-text, use the float64 operator after this to change the type to 64-bit floating point (which will print more decimals).

collapse-sigclip-std

Collapse the input dataset along the given FITS dimension by calculating the sigma-clipped standard deviation. Except for returning the standard deviation after clipping, this function is similar to collapse-sigclip-mean, see the description of that operator for more.

collapse-sigclip-median

Collapse the input dataset along the given FITS dimension by calculating the sigma-clipped median. Except for returning the median after clipping, this function is similar to collapse-sigclip-mean, see the description of that operator for more.

collapse-sigclip-number

Collapse the input dataset along the given FITS dimension by calculating the number of elements that remain after sigma-clipped. Except for returning the number after clipping, this function is similar to collapse-sigclip-mean, see the description of that operator for more.

add-dimension-slow

Build a higher-dimensional dataset from all the input datasets stacked after one another (along the slowest dimension). The first popped operand has to be a single number. It is used by the operator to know how many operands it should pop from the stack (and the size of the output in the new dimension). The rest of the operands must have the same size and numerical data type. This operator currently only works for 2D input operands, please contact us if you want inputs to have different dimensions.

The output’s WCS (which should have a different dimensionality compared to the inputs) can be read from another file with the --wcsfile option. If no file is specified for the WCS, the first dataset’s WCS will be used, you can later add/change the necessary WCS keywords with the FITS keyword modification features of the Fits program (see Fits).

If your datasets do not have the same type, you can use the type transformation operators of Arithmetic that are discussed below. Just beware of overflow if you are transforming to a smaller type, see Numeric data types.

For example, let’s assume you have 3 two-dimensional images a.fits, b.fits and c.fits (each with \(200\times100\) pixels). You can construct a 3D data cube with \(200\times100\times3\) voxels (volume-pixels) using the command below:

$ astarithmetic a.fits b.fits c.fits 3 add-dimension-slow

add-dimension-fast

Similar to add-dimension-slow but along the fastest dimension. This operator currently only works for 1D input operands, please contact us if you want inputs to have different dimensions.

For example, let’s assume you have 3 one-dimensional datasets, each with 100 elements. With this operator, you can construct a \(3\times100\) pixel FITS image that has 3 pixels along the horizontal and 5 pixels along the vertical.