10.3.1 Invoking astscript-ds9-region ¶

This installed script will read two positional columns within an input table and generate an SAO DS9 region file to visualize the position of the given objects over an image. For more on installed scripts please see (see Installed scripts). This script can be used with the following general template:

## Use the RA and DEC columns of 'table.fits' for the region file.
$ astscript-ds9-region table.fits --column=RA,DEC \
                       --output=ds9.reg

## Select objects with a magnitude between 18 to 20, and generate the
## region file directly (through a pipe), each region with radius of
## 0.5 arcseconds.
$ asttable table.fits --range=MAG,18:20 --column=RA,DEC \
      | astscript-ds9-region --column=1,2 --radius=0.5

## With the first command, select objects with a magnitude of 25 to 26
## as red regions in 'bright.reg'. With the second command, select
## objects with a magnitude between 28 to 29 as a green region and
## show both.
$ asttable cat.fits --range=MAG_F160W,25:26 -cRA,DEC \
      | astscript-ds9-region -c1,2 --color=red -obright.reg
$ asttable cat.fits --range=MAG_F160W,28:29 -cRA,DEC \
      | astscript-ds9-region -c1,2 --color=green \
                    --command="ds9 image.fits -regions bright.reg"

The input can either be passed as a named file, or from standard input (a pipe). Only the --column option is mandatory (to specify the input table columns): two columns from the input table must be specified, either by name (recommended) or number. You can optionally also specify the region’s radius, width and color of the regions with the --radius, --width and --color options, otherwise default values will be used for these (described under each option).

The created region file will be written into the file name given to --output. When --output is not called, the default name of ds9.reg will be used (in the running directory). If the file exists before calling this script, it will be overwritten, unless you pass the --dontdelete option. Optionally you can also use the --command option to give the full command that should be run to execute SAO DS9 (see example above and description below). In this mode, the created region file will be deleted once DS9 is closed (unless you pass the --dontdelete option). A full description of each option is given below.

-h INT/STR

--hdu INT/STR

The HDU of the input table when a named FITS file is given as input. The HDU (or extension) can be either a name or number (counting from zero). For more on this option, see Input/Output options.

-c STR,STR

--column=STR,STR

Identifiers of the two positional columns to use in the DS9 region file from the table. They can either be in WCS (RA and Dec) or image (pixel) coordinates. The mode can be specified with the --mode option, described below.

-n STR

--namecol=STR

The column containing the name (or label) of each region. The type of the column (numeric or a character-based string) is irrelevant: you can use both types of columns as a name or label for the region. This feature is useful when you need to recognize each region with a certain ID or property (for example, magnitude or redshift).

-m wcs|img

--mode=wcs|org

The coordinate system of the positional columns (can be either --mode=wcs and --mode=img). In the WCS mode, the values within the columns are interpreted to be RA and Dec. In the image mode, they are interpreted to be pixel X and Y positions. This option also affects the interpretation of the value given to --radius. When this option is not explicitly given, the columns are assumed to be in WCS mode.

-C STR

--color=STR

The color to use for created regions. These will be directly interpreted by SAO DS9 when it wants to open the region file so it must be recognizable by SAO DS9. As of SAO DS9 8.2, the recognized color names are black, white, red, green, blue, cyan, magenta and yellow. The default color (when this option is not called) is green

-w INT

--width=INT

The line width of the regions. These will be directly interpreted by SAO DS9 when it wants to open the region file so it must be recognizable by SAO DS9. The default value is 1.

-r FLT

--radius=FLT

The radius of all the regions. In WCS mode, the radius is assumed to be in arc-seconds, in image mode, it is in pixel units. If this option is not explicitly given, in WCS mode the default radius is 1 arc-seconds and in image mode it is 3 pixels.

--dontdelete

If the output file name exists, abort the program and do not over-write the contents of the file. This option is thus good if you want to avoid accidentally writing over an important file. Also, do not delete the created region file when --command is given (by default, when --command is given, the created region file will be deleted after SAO DS9 closes).

-o STR

--output=STR

Write the created SAO DS9 region file into the name given to this option. If not explicitly given on the command-line, a default name of ds9.reg will be used. If the file already exists, it will be over-written, you can avoid the deletion (or over-writing) of an existing file with the --dontdelete.

--command="STR"

After creating the region file, run the string given to this option as a command-line command. The SAO DS9 region command will be appended to the end of the given command. Because the command will mostly likely contain white-space characters it is recommended to put the given string in double quotations.

For example, let’s assume --command="ds9 image.fits -zscale". After making the region file (assuming it is called ds9.reg), the following command will be executed:

ds9 image.fits -zscale -regions ds9.reg

You can customize all aspects of SAO DS9 with its command-line options, therefore the value of this option can be as long and complicated as you like. For example, if you also want the image to fit into the window, this option will be: --command="ds9 image.fits -zscale -zoom to fit". You can see the SAO DS9 command-line descriptions by clicking on the “Help” menu and selecting “Reference Manual”. In the opened window, click on “Command Line Options”.