Using DS9 Regions

Using DS9 Regions To Exclude Sources

In this example we show how to use DS9 regions with TweakReg in order to exclude spurious detections and parts of the input images that might trouble a proper identification of sources for alignment.

Observations

This example is based on observations of 'MACSJ1149.5+2223-HFFPAR' (proposal ID: 13504, files 'jcdua3f4q_flc.fits' and 'jcdua3f8q_flc.fits').

We provide the ACS/WFC FLC files so that the user can re-create our results.

Procedure

With almost default parameters, TweakReg will find plenty of sources with most of them being either cosmic rays, extended sources, or point-like sources located inside large extended sources.

>>> from drizzlepac import tweakreg 
>>> from stsci.tools import teal 
>>> teal.unlearn('tweakreg')
>>> teal.unlearn('imagefindpars')
>>> tweakreg.TweakReg('*flc.fits',\
                          imagefindcfg=dict(threshold=50,conv_width=4.5),\
                          updatehdr=False)

In Figure 1 we show a part of the 'SCI,1' image of the FITS file 'jcdua3f4q_flc.fits'. The red points show the sources found by TweakReg when run with the above command. TweakReg found 13758 sources in the SCI,1 extension alone in the 'jcdua3f4q_flc.fits' image. We can reduce the number of cosmic rays detected as sources by enabling TweakReg to use DQ flags associated with image pixels.

In order to do this, we set the TweakReg parameter 'qdbits' within 'imagefindpars' to 0:

>>> tweakreg.TweakReg('*flc.fits',\
                      imagefindcfg=dict(threshold=50,conv_width=4.5,dqbits=0),\
                      updatehdr=False)

This has reduced the number of sources detected in 'jcdua3f4q_flc.fits[sci,1]' by almost a third to 5305 (from 13758). These sources are shown as green dots in Figure 1.

However, there are still many sources detected either as cosmic rays or located inside extended galaxies (which could affect the accuracy of positions of these sources). We can still adjust detection threshold, use roundness/sharpness parameters, etc. to reduce the number of false detections even further, however, if these parameters are too restrictive, this may lead to some "good" sources not being found. The include/exclude DS9 regions can be used to tell TweakReg to look for sources only in specific parts of the image, or to exclude some parts of the image from sources finding without using very restrictive parameters for source finding. Below we will show how to use TweakReg include/exclude DS9 regions.

In the previous version of TweakReg, only circular regions could be used and these regions were treated as "exclude" regions, that is, sources inside these regions were excluded from the source list. The new version (Drizzlepac 2.0) allows the following additional DS9 regions: circle, ellipse, polygon, and box. All other regions are ignored. In *addition* to the old interpretation of regions as "exclude" regions, TweakReg now allows the use of both "include" and "exclude" regions (a property of regions in DS9) that can be used to tell TweakReg to find sources only within the "include" regions or not to find sources in the "exclude" regions (or a combination of the two). NOTE: all region files must comply with the DS9 region file format and all the regions must be provided in *image* coordinates.

Using region files to exclude detected sources

Let's assume that we want to exclude some regions of the SCI,1 extension of the 'jcdua3f4q_flc.fits' file from being used for sources finding. This can be achieved by providing TweakReg an exclusion file (through the 'exclusions' parameter). This file must list region files for ALL input images and ALL 'SCI' extensions in these files. When we do not want to provide a DS9 region file for some images and/or extensions, 'None' (without apostrophes) can be entered instead of the DS9 region file name. Also, if we do not want to use region files with the *last* extensions then we do not even need to use 'None' with those extensions. A more complete description of the 'exclusions' file can be found in the Notes section of the TweakReg task.

For our particular example we create a file 'exclusions.txt' with the following two lines:
jcdua3f4q_flc.fits jcdua3f4q_sci1_exclude.reg None
jcdua3f8q_flc.fits None None

This file indicates that TweakReg should exclude sources in extension SCI,1 of file 'jcdua3f4q_flc.fits' based on the region file 'jcdua3f4q_sci1_exclude.reg'. No sources will be excluded (based on DS9 regions) from the SCI,2 extension of this file or from both extensions of the second input file 'jcdua3f8q_flc.fits'.

According to rules for building the exclusions file, we can simplify the above file as:
jcdua3f4q_flc.fits jcdua3f4q_sci1_exclude.reg
jcdua3f8q_flc.fits

NOTE: this simplified syntax cannot be used if it is the last 'SCI' extension that needs a region file (and not the first one). In that case the use of 'None' is *required*!

The regions that will be used for excluding sources are shown in yellow in Figure 2a. The content of the DS9 file is:

# Region file format: DS9 version 4.1
global color=yellow dashlist=8 3 width=2 font="helvetica 10 normal roman" 
select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
image
polygon(3702,845,3819,890,3804,797,3734,720,3671,745,3592,735,3602,770,3660,782)
ellipse(3512,809,26,67,0)
circle(3613,396,75)
box(3541,393,113,96,0)

To run TweakReg with "exclude" regions, simply set 'exclusions' to 'exclusions.txt':

>>> tweakreg.TweakReg('*flc.fits',\
                         imagefindcfg=dict(threshold=50,\
                         conv_width=4.5, dqbits=0),\
                         exclusions='exclusions.txt',\
                         updatehdr=False)

As a result, TweakReg will not find sources in the "exclude" regions as shown in Figure 2 (Right).

Using DS9 Regions to Include and Exclude Sources

In this example we show how to use both include and exclude regions (using DS9 nomenclature). The use of "include" regions is particularly useful for images that have few good sources that can be used for image alignment and all other sources not contained within these regions should be ignored.

Using region files to include/exclude detected sources

The format of the "exclusions" file is essentially the same, the only difference being that now we have to add the text [ConformDS9] at the end of each line containing region files which we want to be interpreted in this more advanced way. For example, now the 'exclusions.txt' file will look like this:

jcdua3f4q_flc.fits jcdua3f4q_sci1_include_exclude.reg [ConformDS9]
jcdua3f8q_flc.fits

NOTE: [ConformDS9] should not follow each region file but rather it must be specified only once at the end of the line for each input file.

To make a region to be an 'exclude' region we write it with a negative sign (-) in the DS9 region file following the DS9 convention. For example, let's consider the rectangular ('box' region) in the previous example to be a region of "exclude" type. The the region file ('jcdua3f4q_sci1_include_exclude.reg') will therefore look like this:

            
# Region file format: DS9 version 4.1
global color=yellow dashlist=8 3 width=2 font="helvetica 10 normal roman" 
select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
image
polygon(3702,845,3819,890,3804,797,3734,720,3671,745,3592,735,3602,770,3660,782)
ellipse(3512,809,26,67,0)
circle(3613,396,75)
-box(3541,393,113,96,0)

In Figure 3 (Left) we show the sources found without "include/exclude" regions and the include/exclude regions that we want to be used with TweakReg. In Figure 3 (Middle) we show the result of running TweakReg with the include/exclude regions described above.

NOTE: the order of include and exclude regions is important! The regions are applied in the order in which they appear in the DS9 region file. If in the last example we switch the order of the include region (circle) with the exclude region (-box), then the result will be different from the result shown fin Figure 3 (Middle) (see the Right panel in Figure 3).