10.8.3 Invoking astscript-psf-stamp ¶

This installed script will generate a stamp of fixed size, centered at the provided coordinates (performing sub-pixel re-gridding if necessary) and normalized at a certain normalization radius. Optionally, it will also mask all the other background sources. A complete tutorial is available to show the operation of this script as a modular component to extract the PSF of a dataset: Building the extended PSF. The executable name is astscript-psf-stamp, with the following general template:

$ astscript-psf-stamp [OPTION...] FITS-file

Examples:

## Make a stamp around (x,y)=(53,69) of width=151 pixels.
## Normalize the stamp within the radii 20 and 30 pixels.
$ astscript-psf-stamp image.fits --mode=img \
      --center=53,69 --widthinpix=151,151 --normradii=20,30 \
      --output=stamp.fits

## Iterate over a catalog with positions of stars that are
## in the input image. Use WCS coordinates.
$ asttable catalog.fits | while read -r ra dec mag; do \
    astscript-psf-stamp image.fits \
        --mode=wcs \
        --center=$ra,$dec \
        --normradii=20,30 \
        --widthinpix=150,150 \
        --output=stamp-"$ra"-"$dec".fits; done

The input is an image from which the stamp of the stars are constructed. The output image will have the following properties:

• A certain width (specified by --widthinpix in pixels).
• Centered at the coordinate specified by the option --center (it can be in image/pixel or WCS coordinates, see --mode). If no center is specified, then it is assumed that the object of interest is already in the center of the image.
• If the given coordinate has sub-pixel elements (for example, pixel coordinates 1.234,4.567), the pixel grid of the output will be warped so your given coordinate falls in the center of the central pixel of the final output. This is very important for building the central parts of the PSF, but not too effective for the middle or outer parts (to speed up the program in such cases, you can disable it with the --nocentering option).
• Normalized “normalized” by the value computed within the ring around the center (at a radial distance between the two radii specified by the option --normradii). If no normalization ring is considered, the output will not be normalized.

In the following cases, this script will produce a fully NaN-valued stamp (of the size given to --widthinpix). A fully NaN image can safely be used with the stacking operators of Arithmetic (see Stacking operators) because they will be ignored. In case you do not want to waste storage with fully NaN images, you can compress them with gzip --best output.fits, and give the resulting .fits.gz file to Arithmetic.

• The requested box (center coordinate with desired width) is not within the input image at all.
• If a normalization radius is requested, and all the pixels within the normalization radii are NaN. Here are some scenarios that this can happen: 1) You have a saturated star (where the saturated pixels are NaN), and your normalization radius falls within the saturated region. 2) The star is outside the image by more than your larger normalization radius (so there are no pixels for doing normalization), but the full stamp width still overlaps part of the image.

The full set of options are listed below for optimal customization in different scenarios:

-h STR

--hdu=STR

The HDU/extension of the input image to use.

-O STR

--mode=STR

Interpret the center position of the object (values given to --center) in image or WCS coordinates. This option thus accepts only two values: img or wcs.

-c FLT,FLT

--center=FLT,FLT

The central position of the object. This option is used for placing the center of the stamp. This parameter is used in Crop to center and crop the image. The positions along each dimension must be separated by a comma (,). The units of the coordinates are read based on the value to the --mode option, see the examples above.

The given coordinate for the central value can have sub-pixel elements (for example, it falls on coordinate 123.4,567.8 of the input image pixel grid). In such cases, after cropping, this script will use Gnuastro’s Warp to shift (or translate) the pixel grid by \(-0.4\) pixels along the horizontal and \(1-0.8=0.2\) pixels along the vertical. Finally the newly added pixels (due to the warping) will be trimmed to have your desired coordinate exactly in the center of the central pixel of the output. This is very important (critical!) when you are constructing the central part of the PSF. But for the outer parts it is not too effective, so to avoid wasting time for the warping, you can simply use --nocentering to disable it.

-d

--nocentering

Do not do the sub-pixel centering to a new pixel grid. See the description of the --center option for more.

-W INT,INT

--widthinpix=INT,INT

Size (width) of the output image stamp in pixels. The size of the output image will be always an odd number of pixels. As a consequence, if the user specify an even number, the final size will be the specified size plus 1 pixel. This is necessary to place the specified coordinate (given to --center) in the center of the central pixel. This is very important (and necessary) in the case of the centers of stars, therefore a sub-pixel translation will be performed internally to ensure this.

-n FLT,FLT

--normradii=FLT,FLT

Minimum and maximum radius of ring to normalize the image. This option takes two values, separated by a comma (,). The first value is the inner radius, the second is the outer radius.

-S STR

--segment=STR

Optional filename of a segmentation image from Segment’s output (must contain the CLUMPS and OBJECT HDUs). For more on the definition of “objects” and “clumps”, see Segment. If given, Segment’s output is used to mask all background sources from the large foreground object (a bright star):

• Objects that are not the central object.
• Clumps (within the central object) that are not the central clump.

The result is that all objects and clumps that contaminate the central source are masked, while the diffuse flux of the central object remains. The non masked object and clump labels are kept into the header of the output image. The keywords are CLABEL and OLABEL. If no segmentation image is used, then their values are set to none.

-T FLT

--snthresh=FLT

Mask all the pixels below the given signal-to-noise ratio (S/N) threshold. This option is only valid with the --segment option (it will use the SKY_STD extension of the Segment output. This threshold is applied prior to the possible normalization or centering of the stamp. After all pixels below the given threshold are masked, the mask is also dilated by one level to avoid single pixels above the threshold (which are mainly due to noise when the threshold is lower).

After applying the signal-to-noise threshold (if it is requested), any extra pixels that are not connected to the central target are also masked. Such pixels can remain in rivers between bright clumps and will cause problem in the final stack, if they are not masked.

This is useful for increasing the S/N of inner parts of each region of the finally stacked PSF. As the stars (that are to be stacked) become fainter, the S/N of their outer parts (at a fixed radius) decreases. The stack of a higher-S/N image with a lower-S/N image will have an S/N that is lower than the higher one. But we can still use the inner parts of those fainter stars (that have sufficiently high S/N).

-N STR

--normop=STR

The operator for measuring the values within the ring defined by the option --normradii. The operator given to this option will be directly passed to the radial profile script astscript-radial-profile, see Generate radial profile. As a consequence, all MakeCatalog measurements (median, mean, sigclip-mean, sigclip-number, etc.) can be used here. For a full list of MakeCatalog’s measurements, please run astmkcatalog --help. The final normalization value is saved into the header of the output image with the keyword NORMVAL. If no normalization is done, then the value is set to 1.0.

-Q FLT

--axis-ratio=FLT

The axis ratio of the radial profiles for computing the normalization value. By default (when this option is not given), the radial profile will be circular (axis ratio of 1). This parameter is used directly in the astscript-radial-profile script.

-p FLT

--position-angle=FLT

The position angle (in degrees) of the profiles relative to the first FITS axis (horizontal when viewed in SAO DS9). By default, it is --position-angle=0, which means that the semi-major axis of the profiles will be parallel to the first FITS axis. This parameter is used directly in the astscript-radial-profile script.

-s FLT,FLT

--sigmaclip=FLT,FLT

Sigma clipping parameters: only relevant if sigma-clipping operators are requested by --normop. For more on sigma-clipping, see Sigma clipping.

-t

--tmpdir

Directory to keep temporary files during the execution of the script. If the directory does not exist at run-time, this script will create it. By default, upon completion of the script, this directory will be deleted. However, if you would like to keep the intermediate files, you can use the --keeptmp option.

-k

--keeptmp

Do not remove the temporary directory (see description of --keeptmp). This option is useful for debugging and checking the outputs of internal steps.

-o STR

--output=STR

Filename of stamp image. By default the name of the stamp will be a combination of the input image name, the name of the script, and the coordinates of the center. For example, if the input image is named image.fits and the center is --center=33,78, then the output name wil be: image_stamp_33_78.fits The main reason of setting this name is to have an unique name for each stamp by default.