10.8.2 Invoking astscript-psf-select-stars ¶

This installed script will select good star candidates for constructing a PSF. It will consider stars within a given range of magnitudes without nearby contaminant objects. To do that, it allows to the user to specify different options described here. 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-select-stars, with the following general template:

$ astscript-psf-select-stars [OPTION...] FITS-file

Examples:

## Select all stars within 'image.fits' with magnitude in range
## of 6 to 10; only keeping those that are less than 0.02 degrees
## from other nearby stars.
$ astscript-psf-select-stars image.fits \
           --magnituderange=6,10 --mindistdeg=0.02

The input of this script is an image, and the output is a catalog of stars with magnitude in the requested range of magnitudes (provided with --magnituderange). The output catalog will also only contain stars that are sufficiently distant (--mindistdeg) from all other brighter, and some fainter stars. It is possible to consider different datasets with the option --dataset (by default, Gaia DR3 dataset is considered) All stars that are --faintmagdiff fainter than the faintest limit will also be accounted for, when selecting good stars. The --magnituderange, and --mindistdeg are mandatory: if not specified the code will abort.

The output of this script is a file whose name can be specified with the (optional) --output option. If not given, an automatically generated name will be used for the output. A full description of each option is given below.

-h STR/INT

--hdu=STR/INT

The HDU/extension of the input image to use.

-S STR

--segmented=STR

Optional segmentation file obtained by Segment. It should have two extensions (CLUMPS and OBJECTS). If given, a catalog of CLUMPS will be computed and matched with the Gaia catalog to reject those objects that are too elliptical (see --minaxisratio). The matching will occur on an aperture (in degrees) specified by --matchaperturedeg.

-a FLT

--matchaperturedeg=FLT

This option determines the aperture (in degrees) for matching the catalog from gaia with the clumps catalog that is produced by the segmentation image given to --segmented. The default value is 10 arc-seconds.

-c STR

--catalog=STR

Optional reference catalog to use for selecting stars (instead of querying an external catalog like Gaia). When this option is given, --dataset (described below) will be ignored and no internet connection will be necessary.

-d STR

--dataset=STR

Optional dataset to query (see Query). It should contain the database and dataset entries to Query. Its value will be immediately given to astquery. By default, its value is gaia --dataset=dr3 (so it connects to the Gaia database and requests the data release 3). For example, if you want to use VizieR’s Gaia DR3 instead (for example due to a maintenance on ESA’s Gaia servers), you should use --dataset="vizier --dataset=gaiadr3".

It is possible to specify a different dataset from which the catalog is downloaded. In that case, the necessary column names may also differ, so you also have to set --refcatra, --refcatdec and --field. See their description for more.

-r STR

--refcatra=STR

The name of the column containing the Right Ascension (RA) in the requested dataset (--dataset). If the user does not determine this option, the default value is assumed to be ra.

-d STR

--refcatdec=STR

The name of the column containing the Declination (Dec) in the requested dataset (--dataset). If the user does not determine this option, the default value is assumed to be dec.

-f STR

--field=STR

The name of the column containing the magnitude in the requested dataset (--dataset). The output will only contain stars that have a value in this column, between the values given to --magnituderange (see below). By default, the value of this option is phot_g_mean_mag (that corresponds to the name of the magnitude of the G-band in the Gaia catalog).

-m FLT,FLT

--magnituderange=FLT,FLT

The acceptable range of values for the column in --field. This option is mandatory and no default value is assumed.

-p STR,STR

--parallaxanderrorcolumn=STR,STR

With this option the user can provide the parallax and parallax error column names in the requested dataset. When given, the output will only contain stars for which the parallax value is smaller than three times the parallax error. If the user does not provide this option, the script will not use parallax information for selecting the stars. In the case of Gaia, if you want to use parallax to further limit the good stars, you can pass parallax,parallax_error.

-D FLT

--mindistdeg=FLT

Stars with nearby bright stars closer than this distance are rejected. The default value is 1 arc minute. For fainter stars (when constructing the center of the PSF), you should decrease the value.

-b INT

--brightmag=INT

The brightest star magnitude to avoid (should be brighter than the brightest of --magnituderange). The basic idea is this: if a user asks for stars with magnitude 6 to 10 and one of those stars is near a magnitude 3 star, that star (with a magnitude of 6 to 10) should be rejected because it is contaminated. But since the catalog is constrained to stars of magnitudes 6-10, the star with magnitude 3 is not present and cannot be compared with! Therefore, when considering proximity to nearby stars, it is important to use a larger magnitude range than the user’s requested magnitude range for good stars. The acceptable proximity is defined by --mindistdeg.

With this option, you specify the brightest limit for the proximity check. The default value is a magnitude of \(-10\), so you’ll rarely need to change or customize this option!

The faint limit of the proximity check is specified by --faintmagdiff. As the name suggests, this is a “diff” or relative value. The default value is 4. Therefore if the user wants to build the PSF with stars in the magnitude range of 6 to 10, the faintest stars used for the proximity check will have a magnitude of 14: \(10+4\). In summary, by default, the proximity check will be done with stars in the magnitude range \(-10\) to \(14\).

-F INT

--faintmagdiff

The magnitude difference of the faintest star used for proximity checks to the faintest limit of --magnituderange. For more, see the description of --brightmag.

-Q FLT

--minaxisratio=FLT

Minimum acceptable axis ratio for the selected stars. In other words, only stars with axis ratio between --minaxisratio to 1.0 will be selected. Default value is --minaxisratio=0.9. Recall that the axis ratio is only used when you also give a segmented image with --segmented.

-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

The output name of the final catalog containing good stars.