10.8.6 Invoking astscript-psf-subtract ¶

This installed script will put the provided PSF into a given position within the input image (implementing sub-pixel adjustments where necessary), and then it will subtract it. It is aimed at modeling and subtracting the scattered light field of an input image. It is also possible to obtain the modeled star with the PSF (and not make the subtraction of it from the original image).

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-subtract, with the following general template:

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

Examples:

## Multiply the PSF (psf.fits) by 3 and subtract it from the
## input image (image.fits) at the pixel position (x,y)=(53,69).
$ astscript-psf-subtract image.fits \
    --psf=psf.fits \
    --mode=img \
    --scale=3 \
    --center=53,69 \
    --output=star-53_69.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
         scale=$(cat scale-"$ra"_"$dec".txt)
         astscript-psf-subtract image.fits \
             --mode=wcs \
             --psf=psf.fits \
             --scale=$scale \
             --center=$ra,$dec; done

The input is an image from which the star is considered. The result is the same image but with the star subtracted (modeled by the PSF). The modeling of the star is done with the PSF image specified with the option --psf, and flux-scaled with the option --scale at the position defined by --center. Instead of obtaining the PSF-subtracted image, it is also possible to obtain the modeled star by the PSF. To do that, use the option --modelonly. With this option, the output will be an image with the same size as the original one with the PSF situated in the star coordinates and flux-scaled. In this case, the region not covered by the PSF are set to zero values.

Note that this script works over individual objects. As a consequence, to generate a scattered light field of many stars, it is necessary to make multiple calls. A full description of each option is given below.

-h STR

--hdu=STR

The HDU/extension of the input image to use.

-p STR

--psf=STR

Filename of the PSF image. The PSF is assumed to be centered in this image.

-P STR

--psfhdu=STR

The HDU/extension of the PSF image.

-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 parameter is used in Crop to center and crop the image. The positions along each dimension must be separated by a comma (,). The number of values given to this option must be the same as the dimensions of the input dataset. The units of the coordinates are read based on the value to the --mode option, see above.

If the central position does not fall in the center of a pixel in the input image, the PSF is resampled with sub-pixel change in the pixel grid before subtraction.

-s FLT

--scale=FLT

Factor by which the PSF (--psf) is multiplied. This factor is necessary to put the PSF with the desired flux level. A convenient way of obtaining this value is by using the script astscript-scale-factor, see Invoking astscript-psf-scale-factor. For a full tutorial on using the astscript-psf-* scripts together, see Building the extended PSF.

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

-m

--modelonly

Do not make the subtraction of the modeled star by the PSF. This option is useful when the user wants to obtain the scattered light field given by the PSF modeled star.