GNU Astronomy Utilities



10.8.5 Invoking astscript-psf-scale-factor

This installed script will compute the multiplicative factor (scale) that is necessary to match the PSF to a given star. The match in flux is done within a ring of pixels. It can also be used to compute the scale factor to multiply the inner part of the PSF with the outer part during the creation of a PSF. 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-scale-factor, with the following general template:

$ astscript-psf-scale-factor [OPTION...] FITS-file

Examples:

## Compute the scale factor for the object at (x,y)=(53,69) for
## the PSF (psf.fits). Compute it in the ring 20-30 pixels.
$ astscript-psf-scale-factor image.fits --mode=img \
      --center=53,69 --normradii=20,30 --psf=psf.fits

## Iterate over a catalog with RA,Dec positions of stars that are in
## the input image to compute their scale factors.
$ asttable catalog.fits | while read -r ra dec mag; do \
    astscript-psf-scale-factor image.fits \
        --mode=wcs \
        --psf=psf.fits \
        --center=$ra,$dec --quiet \
        --normradii=20,30 > scale-"$ra"-"$dec".txt; done

The input should be an image containing the star that you want to match in flux with the PSF. The output will be a single number that is printed on the command-line. That number is the multiplicative factor to scale the PSF image (given to --psf) to match in flux with the given star (which is located in --center coordinate of the input image). The scale factor will be calculated within the ring of pixels specified by the option --normradii.

All the pixels within this ring will be separated from both the PSF and input images. For the input image, around the selected coordinate; while masking all other sources (see --segment). The finally selected pixels of the input image will then be divided by those of the PSF image. This gives us an image containing one scale factor per pixel. The finally reported value is the sigma-clipped median of all the scale factors in the finally-used pixels. To fully understand the process on first usage, we recommend that you run this script with --keeptmp and inspect the files inside of the temporary directory.

The most common use-cases of this scale factor are:

  1. To find the factor for joining two different parts of the same PSF, see Invoking astscript-psf-unite.
  2. When modeling a star in order to subtract it using the PSF, see Invoking astscript-psf-subtract.

For a full tutorial on how to use this script along with the other astscript-psf-* scripts in Gnuastro, please see Building the extended PSF. To allow full customizability, the following options are available with this script.

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

-c FLT,FLT
--center=FLT,FLT

The central position of the object to scale with the PSF. This parameter is passed to Gnuastro’s Crop program make a crop for further processing (see Crop). The positions along each dimension must be separated by a comma (,). The units of the coordinates are interpreted based on the value to the --mode option (see below).

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 very far outer parts it may not too effective (should be checked), or the target object may have already been centered at the requested coordinate. In such cases, to avoid wasting time for the warping, you can simply use --nocentering to disable sub-pixel centering.

-d
--nocentering

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

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

-n INT,INT
--normradii=INT,INT

Inner (inclusive) and outer (exclusive) radii (in units of pixels) around the central position in which the scale factor is computed. The option takes two values separated by a comma (,). The first value is the inner radius, the second is the outer radius. These two radii define a ring of pixels around the center that is used for obtaining the scale factor value.

-W INT,INT
--widthinpix=INT,INT

Size (width) of the image stamp in pixels. This is an intermediate product computed internally by the script. By default, the size of the stamp is automatically set to be as small as possible (i.e., two times the external radius of the ring specified by --normradii) to make the computation fast. As a consequence, this option is only relevant for checking and testing that everything is fine (debugging; it will usually not be necessary).

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

-s FLT,FLT
--sigmaclip=FLT,FLT

Sigma clipping parameters used in the end to find the final scale factor from the distribution of all pixels used. 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.