---

6.2.4.21 Operand storage in memory or a file ¶

In your early days of using Gnuastro, to do multiple operations, it is likely that you will simply call Arithmetic (or Table, with column arithmetic) multiple times: feed the output file of the first call to the second call. But as you get more proficient in the reverse polish notation, you will find yourself combining many operations into one call. This greatly speeds up your operation, because instead of writing the dataset to a file in one command, and reading it in the next command, it will just keep the intermediate dataset in memory!

But adding more complexity to your operations, can make them much harder to debug, or extend even further. Therefore in this section we have some special operators that behave differently from the rest: they do not touch the contents of the data, only where/how they are stored. They are designed to do complex operations, without necessarily having a complex command.

swap

Swap the top two operands on the stack. For example the index operator doesn’t pop with the top operand (the input to index), it just adds the index image to the stack. In case you want your next operation to be on the input to index, you can simply call swap and continue the operations on that image, while keeping the indexed pixels for later steps. In the example below we are using the --writeall option to write the full stack and if you open the outputs you will see that the stack order has changed.

## Index image is written in HDU 1.
$ astarithmetic image.fits index      --writeall \
                --output=ind-first.fits

## image.fits in HDU 1.
$ astarithmetic image.fits index swap --writeall \
                --output=img-first.fits

repeat

Add N copies of the second popped operand to the stack of operands. N is the first popped operand. For example, let’s assume image.fits is a \(100\times100\) image. The output of the command below will be a 3D data cube of size \(100\times100\times20\) voxels (volume-pixels):

$ astarithmetic image.fits 20 repeat 20 add-dimension-slow

free

Free the top operand from the stack and memory. This is useful in cases where the operator adds more than one operand on the stack. For example operators that do stacking by clipping in Stacking operators; see the examples there for more.

set-AAA

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 command-line (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 will not 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 set-a 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 set-a a 2 x

The name can be any string, but avoid strings ending with standard filename suffixes (for example, .fits)¹⁶³.

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 set-i i i 5 gt nan where

tofile-AAA

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 do not 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 tofile-check.fits will write the top operand to check.fits. Since it does not 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 tofile-AAA anywhere in the process to see what is happening behind the scenes without modifying the overall process.

tofilefree-AAA

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).