10.6.1 Invoking astscript-pointing-simulate ¶

This installed script will simulate a final stacked image from a certain pointing pattern (given as a table). A general overview of this script has been published in Akhlaghi (2023); please cite it if this script proves useful in your research. The executable name is astscript-pointing-simulate, with the following general template:

$ astscript-pointing-simulate [OPTION...] pointings.fits

Examples (for a tutorial, see Pointing pattern design):

$ astscript-pointing-simulate pointing.fits --output=stack.fits \
           --img=image.fits --center=10,10 --width=1,1

The default output of this script is a stacked image that results from placing the given image (given to --img) in the pointings of a pointing pattern. The Right Ascension (RA) and Declination (Dec) of each pointing is given in the main input catalog (pointing.fits in the example above). The center and width of the final stack (both in degrees by default) should be specified using the --width option. Therefore, in order to successfully run, this script at least needs the following four inputs:

Pointing positions

A table containing the RA and Dec of each pointing (the only input argument). The actual column names that contain them can be set with the --racol and --deccol options (see below).

An image

This is used for its distortion and rotation, its pixel values and position on the sky will be ignored. The file containing the image should be given to the --img option.

Stack’s central coordinate

The central RA and Dec of the finally produced stack (given to the --center option).

Stack’s width

The width (in degrees) of the final stack (given to the --width option).

This script will ignore the pixel values of the reference image (given to --img) and the Reference coordinates (values to CRVAL1 and CRVAL2 in its WCS keywords). For each pointing pointing, this script will put the given RA and Dec into the CRVAL1 and CRVAL2 keywords of a copy of the input (not changing the input in anyway), and reset that input’s pixel values to 1. The script will then warp the modified copy into the final pixel grid (correcting any rotation and distortions that are used from the original input). This process is done for all the pointing points in parallel. Finally, all the exposures in the pointing list are stacked together to produce an exposure map (showing how many exposures go into each pixel of the final stack.

Except for the table of pointing positions, the rest of the inputs and settings are configured through Options, just note the restrictions in Installed scripts.

-o STR

--output=STR

Name of the output. The output is an image of the requested size (--width) and position (--center) in the sky, but each pixel will contain the number of exposures that go into it after the pointing has been done. See description above for more.

-h STR/INT

--hdu=STR/INT

The name or counter (counting from zero; from the FITS standard) of HDU containing the table of pointing pointing positions (the file name of this table is the main input argument to this script). For more, see the description of this option in Input/Output options.

-i STR

--img=STR

The references image. The pixel values and central location in this image will be ignored by the script. The only relevant information within this script are the WCS properties (except for CRVAL1 and CRVAL2, which connect it to a certain position on the sky) and image size. See the description above for more.

-H STR/INT

--imghdu=STR/INT

The name or counter (counting from zero; from the FITS standard) of the HDU containing the reference image (file name should be given to the --img option). If not given, a default value of 1 is assumed; so this is not a mandatory option.

-r STR/INT

--racol=STR/INT

The name or counter (counting from 1; from the FITS standard) of the column containing the Right Ascension (RA) of each pointing to be used in the pointing pattern. The file containing the table is given to this script as its only argument.

-d STR/INT

--deccol=STR/INT

The name or counter (counting from 1; from the FITS standard) of the column containing the Declination (Dec) of each pointing to be used in the pointing pattern. The file containing the table is given to this script as its only argument.

-C FLT,FLT

--center=FLT,FLT

The central RA and Declination of the final stack in degrees.

-w FLT,FLT

--width=FLT,FLT

The width of the final stack in degrees. If --widthinpix is given, the two values given to this option will be interpreted as degrees.

--widthinpix

Interpret the values given to --width as number of pixels along each dimension), and not as degrees.

--ctype=STR,STR

The projection of the output stack (CTYPEi keyword in the FITS WCS standard). For more, see the description of the same option in Align pixels with WCS considering distortions.

--hook-warp-before='STR'

Command to run before warping each exposure into the output pixel grid. By default, the exposure is immediately warped to the final pixel grid, but in some scenarios it is necessary to do some operations on the exposure before warping (for example account for vignetting; see Accounting for non-exposed pixels). The warping of each exposure is done in parallel by default; therefore there are pre-defined variables that you should use for the input and output file names of your command:

$EXPOSURE

Input: name of file with the same size as the reference image with all pixels having a fixed value of 1. The WCS has also been corrected based on the pointing pattern.

$TOWARP

Output: name of the expected output of your hook. If it is not created by your script, the script will complain and abort. This file will be given to Warp to be warped into the output pixel grid.

For an example of using hooks with an extended discussion, see Pointing pattern design and Accounting for non-exposed pixels.

To develop your command, you can use --hook-warp-before='...; echo GOOD; exit 1' (where ... can be replaced by any command) and run the script on a single thread (with --numthreads=1) to produce a single file and simplify the checking that your desired operation works as expected. All the files will be within the temporary directory (see --tmpdir).

--hook-warp-after='STR'

Command to run after the warp of each exposure into the output pixel grid, but before the stacking of all exposures. For more on hooks, see the description of --hook-warp-before, Pointing pattern design and Accounting for non-exposed pixels.

$WARPED

Input: name of file containing the warped exposure in the output pixel grid.

$TOWARP

Output: name of the expected output of your hook. If it is not created by your script, the script will complain and abort. This file will be stacked from the same file for all exposures into the final output.

--stack-operator="STR"

The operator to use for stacking the warped individual exposures into the final output of this script. For the full list, see Stacking operators. By default it is the sum operator (to produce an output exposure map). For an example usage, see the tutorial in Pointing pattern design.

--mksrc=STR

Use a non-standard Makefile for the Makefile to call. This option is primarily useful during the development of this script and its Makefile, not for normal/regular usage. So if you are not developing this script, you can safely ignore this option. When this option is given, the default installed Makefile will not be used: the file given to this option will be read by make (within the script) instead.

-t STR

--tmpdir=STR

Name of directory containing temporary files. If not given, a temporary directory will be created in the running directory with a long name using some of the input options. By default, this temporary directory will be deleted after the output is created. You can disable the deletion of the temporary directory (useful for debugging!) with the --keeptmp option.

Using this option has multiple benefits in larger pipelines:

• You can avoid conflicts in case the used inputs in the default name are the same.
• You can put this directory somewhere else in the running file system to avoid mixing output files with your source, or to use other storage hardware that are mounted on the running file system.

-k

--keeptmp

Keep the temporary directory (and do not delete it).

-?

--help

Print a list of all the options, along with a short description and context for the program. For more, see Operating mode options.

-N INT

--numthreads=INT

The number of threads to use for parallel operations (warping the input into the different pointing points). If not given (by default), the script will try to find the number of available threads on the running system and use that. For more, see Operating mode options.

--cite

Give BibTeX and acknowledgment information for citing this script within your paper. For more, see Operating mode options.

-q

--quiet

Do not print the series of commands or their outputs in the terminal. For more, see Operating mode options.

-V

--version

Print the version of the running Gnuastro along with a copyright notice and list of authors that contributed to this script. For more, see Operating mode options.