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:
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.
The HDU/extension of the input image to use.
Filename of the PSF image. The PSF is assumed to be centered in this image.
The HDU/extension of the PSF image.
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.
Do not do the sub-pixel centering to a new pixel grid. See the description of the --center option for more.
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.
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.
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).
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):
The result is that all objects and clumps that contaminate the central source are masked, while the diffuse flux of the central object remains.
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.
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.
Do not remove the temporary directory (see description of --keeptmp). This option is useful for debugging and checking the outputs of internal steps.
JavaScript license information
GNU Astronomy Utilities 0.23 manual, July 2024.