Last modified: 24 Jan 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/group_regions/

Creating Source and Background Files

CIAO 4.16 Science Threads


Overview

Synopsis:

The tool dmgroupreg takes a ds9 region file (which must contain grouping information) and creates source and background region files that the CIAO tools can understand. There is also the option to remove the source regions from the background within each group.

Related Links:

Last Update: 24 Jan 2022 - Reviewed for CIAO 4.14. Updated for Repro-5.


Contents


Getting Started

Download the sample data: 650 (ACIS-S, GK Persei)

unix% download_chandra_obsid 650 evt2

A Simple Example: One Group

1. Create a group of regions

First we define a single group that contains one source and four background regions.

  1. Display the Event File

    Load the event file in ds9:

    unix% ds9 acisf00650N005_evt2.fits &
    

    Unless stated otherwise, the images in this thread show the event file displayed with "Bin → block 2".

  2. Define a region around the source(s).

    For instructions on how to create regions in ds9, see the Using CIAO Region Files thread.

  3. Define the background region(s)

    We chose to create four background regions. After creating them, select all the background regions and use "Region → Properties → Background" to indicate it is a background region; hold down the <Shift> key to select multipled regions. The region outline will change to a dashed line in ds9.

    Be aware that any new regions created after this point will be defined as background. If you wish to create new source regions, make sure to change the property back to "Source" in the "Region → Properties" menu.

    At this point, the ds9 display will look similar to Figure 1.

    Figure 1: One group of regions defined

    [Thumbnail image: Four background regions and one source region are defined as green circles.]

    [Version: full-size]

    [Print media version: Four background regions and one source region are defined as green circles.]

    Figure 1: One group of regions defined

  4. Create a Group

    Select all of the regions, either with <Shift>-click or with ds9's "Region → Select All" option. Select the "Region → New Group" option and a "New Group" dialog box will be launched; either accept the default name ("Group 1") or choose a name for the group.

  5. Save the Regions

    To save the regions, follow these steps:

    1. Region → Save Regions... → Save As "simple_ds9.reg".
    2. After choosing "OK" in the region filename dialog, a format dialog is opened. Set the format to "ds9" and the coordinate system to "Physical".

    Note that in this case the region file must be saved in ds9 format in order for the necessary grouping information to be retained. This is contrary to the usual guideline that the CIAO region format always be used.

    The resulting region file looks like this:

    unix% cat simple_ds9.reg 
    # Region file format: DS9 version 4.0
    # Filename: /data/group_regions/acisf00650N005_evt2.fits[EVENTS]
    global color=green font="helvetica 10 normal" select=1 highlite=1 edit=1 move=1 delete=1 include=1 fixed=0 source
    physical
    circle(4106.0,4247.0,34) # tag={Group 1}
    circle(3765.5,4395.5,40) # background tag={Group 1}
    circle(3921.5,4503.5,40) # background tag={Group 1}
    circle(4105.5,4519.5,40) # background tag={Group 1}
    circle(4281.5,4483.5,40) # background tag={Group 1}
    

2. Run dmgroupreg

Now dmgroupreg is used to split the ds9 region file into separate source and background files:

unix% punlearn dmgroupreg
unix% pset dmgroupreg infile=simple_ds9.reg
unix% pset dmgroupreg srcoutfile=simple_src.reg
unix% pset dmgroupreg bkgoutfile=simple_bkg.reg
unix% pset dmgroupreg exclude=no
unix% dmgroupreg
DS9 region input file (simple_ds9.reg): 
Output file for CIAO source regions (simple_src.reg): 
Output file for CIAO background regions (simple_bkg.reg): 

In this simple case, we do not need to remove the source region from the background regions. Therefore, we set the exclude parameter to no (by default it is yes).

The contents of the parameter may be checked with plist dmgroupreg


3. Examine the Output

There are now two new region files, each of which contains a comment that it was created from Group 1:

unix% cat simple_src.reg 
# Group 1
circle(4106.0,4247.0,34)

unix% cat simple_bkg.reg 
# Group 1
circle(3765.5,4395.5,40)+circle(3921.5,4503.5,40)+circle(4105.5,4519.5,40)+circle(4281.5,4483.5,40)

These files, which are CIAO format, are ready to be used in the analysis session.

[TIP]
Tip: using with ds9

These region files are now technically stacks of CIAO regions, and as such, these files cannot be used directly in ds9. To visualize the region the file input to dmgroupreg must be used.


A Complex Example: Multiple Groups

1. Create several groups of regions

Following the procedure in the last example, it is possible to create multiple groups of regions. Simply repeat steps 1-4, forming a new group for every set of associated regions. Then save all the regions to a single file.

This region file shows a particularly complex set of groups:

unix% cat complex_ds9.reg
# Region file format: DS9 version 4.0
# Filename: /data/group_regions/acisf00650N005_evt2.fits[EVENTS]
global color=green font="helvetica 10 normal" select=1 highlite=1 edit=1 move=1 delete=1 include=1 fixed=0 source
physical
box(3862.1559,3740.5971,154.50773,175.30802,340.91332) # background tag={Group2}
box(4363,4042,173,201,0) # background tag={Group1}
circle(4084.5,4058.5,18) # tag={Group1}
circle(4234.5,3886.5,22) # tag={Group1}
circle(3746.5,3768.5,22) # tag={Group2}
circle(3800.5,4442.5,16) # tag={Group1}
circle(3834.5,4458.5,18) # tag={Group1}
circle(3886.5,4556.5,16) # tag={Group1}
circle(4004.5,4542.5,36) # tag={Group1}
circle(4284.5,4482.5,22) # tag={Group1}
circle(4522.5,4442.5,32) # tag={Group1}
circle(4566.5,4550.5,28) # tag={Group1}
circle(3750.5,4536.5,18) # tag={Group1}
circle(3894.5,4420.5,18) # tag={Group1}
circle(3682.5,4560.5,18) # tag={Group1}
circle(3740.5,4178.5,32) # tag={Group1}
circle(4192.5,3806.5,10) # tag={Group2}
circle(4146.5,3642.5,8) # tag={Group2}
ellipse(3982.5,4032.5,46,20,324.07779) # tag={Group1}
box(4412,4376,101,311,0) # background tag={Group1}
circle(4106.0,4247.0,26) # tag={Group3}
polygon(4073.7819,4324.4495,4174.5,4334.5,4200.5,4268.5,4162.5,4186.5,4090.1562,4142.2854,4049.2205,4181.1743,4069.6884,4285.5605) # background tag={Group3}
-circle(4096.5,4186.5,12) # background tag={Group3}
circle(4288.5,3888.5,16) # tag={Group1}

Displaying the region file in ds9 creates Figure 2. The excluded region (marked so via the "Region → Properties" menu) is displayed with a red strike through it.

Figure 2: Complex region definitions

[Thumbnail image: Two dozen regions of different shapes and sizes are defined on the data.]

[Version: full-size]

[Print media version: Two dozen regions of different shapes and sizes are defined on the data.]

Figure 2: Complex region definitions

One region is marked as excluded, indicated by the red strike through it.


2. View Individual Groups

Since the ds9 format records the group in which each region belongs, it is possible to highlight each of them individually. Choose the "Groups..." option from the "Region" menu and the "Region Groups" dialog box (Figure 3) will be launched. This lists all of the groups defined in the region file.

Figure 3: The "Region Groups" dialog box

[Three groups are listed in the dialog box.]
[Print media version: Three groups are listed in the dialog box.]

Figure 3: The "Region Groups" dialog box

The ds9 "Region Groups" dialog box lists all of the groups defined in a region file.

Clicking on each of the group names will highlight the regions therein on the ds9 display, allowing the user to modify the properties - such as region color - of all the regions simultaneously. Figure 4 shows Group 1 in green, Group 2 in red, and Group 3 in white.

Figure 4: Three groups of regions

[Thumbnail image: The regions from the complex example have been color-coded to indicate the groups.]

[Version: full-size]

[Print media version: The regions from the complex example have been color-coded to indicate the groups.]

Figure 4: Three groups of regions

Group 1 is shown in green, Group 2 in red, and Group 3 in white.


3. Run dmgroupreg

Run dmgroupreg to split up the ds9 region file:

unix% punlearn dmgroupreg
unix% pset dmgroupreg infile=complex_ds9.reg
unix% pset dmgroupreg srcoutfile=complex_src.reg
unix% pset dmgroupreg bkgoutfile=complex_bkg.reg
unix% pset dmgroupreg exclude=no
unix% dmgroupreg
DS9 region input file (complex_ds9.reg): 
Output file for CIAO source regions (complex_src.reg): 
Output file for CIAO background regions (complex_bkg.reg): 

We again choose not to remove the source region from the background regions by setting exclude=no.

The contents of the parameter may be checked with plist dmgroupreg


4. Examine the Output

There are two new region files, one for the source regions and one for the background regions. Each group is preceded by a comment line that indicates which group it was in:

unix% cat complex_src.reg
# Group2
circle(3746.5,3768.5,22)+circle(4192.5,3806.5,10)+circle(4146.5,3642.5,8)
# Group1
circle(4084.5,4058.5,18)+circle(4234.5,3886.5,22)+circle(3800.5,4442.5,16)+circle(3834.5,4458.5,18)+circle(3886.5,4556.5,16)+circle(4004.5,4542.5,36)+circle(4284.5,4482.5,22)+circle(4522.5,4442.5,32)+circle(4566.5,4550.5,28)+circle(3750.5,4536.5,18)+circle(3894.5,4420.5,18)+circle(3682.5,4560.5,18)+circle(3740.5,4178.5,32)+ellipse(3982.5,4032.5,46,20,324.07779)+circle(4288.5,3888.5,16)
# Group3
circle(4106.0,4247.0,26)

# Group2
rotbox(3862.1559,3740.5971,154.50773,175.30802,340.91332)
# Group1
rotbox(4363,4042,173,201,0)+rotbox(4412,4376,101,311,0)
# Group3
polygon(4073.7819,4324.4495,4174.5,4334.5,4200.5,4268.5,4162.5,4186.5,4090.1562,4142.2854,4049.2205,4181.1743,4069.6884,4285.5605)*!circle(4096.5,4186.5,12)

This file cannot be loaded into ds9 since it uses the CIAO Data Model syntax; see "ahelp dmregions" for information on the region syntax.


Subtracting the Source Region

In the previous cases, we chose not to subtract the source region(s) from the background region(s). If the source is within the desired background area, for instance, this approach is useful.

1. Create a source and background region

We have created a background region that encompasses the source region, shown in Figure 5. This was done by following the procedure in the first example.

Figure 5: Source region within background region

[Thumbnail image: The two regions are concentric and are centered on the source.]

[Version: full-size]

[Print media version: The two regions are concentric and are centered on the source.]

Figure 5: Source region within background region

The region file looks like:

unix% cat subtract_ds9.reg 
# Region file format: DS9 version 4.0
# Filename: /data/group_regions/acisf00650N005_evt2.fits[EVENTS]
global color=green font="helvetica 10 normal" select=1 highlite=1 edit=1 move=1 delete=1 include=1 fixed=0 source
physical
circle(4111.5,4251.5,102) # tag={Subtract Group}
circle(4113.5,4247.5,184) # background tag={Subtract Group}

In this case, the group was named "Subtract Group".


2. Run dmgroupreg

For this run of dmgroupreg, the default of exclude=yes is used:

unix% punlearn dmgroupreg
unix% pset dmgroupreg infile=subtract_ds9.reg
unix% pset dmgroupreg srcoutfile=subtract_src.reg
unix% pset dmgroupreg bkgoutfile=subtract_bkg.reg
unix% dmgroupreg
DS9 region input file (subtract_ds9.reg): 
Output file for CIAO source regions (subtract_src.reg): 
Output file for CIAO background regions (subtract_bkg.reg): 

The contents of the parameter may be checked with plist dmgroupreg


3. Examine the Output

The output region files look like:

unix% cat subtract_src.reg
# Subtract Group
circle(4111.5,4251.5,102)

unix% cat subtract_bkg.reg
# Subtract Group
circle(4113.5,4247.5,184)*!circle(4111.5,4251.5,102)

The background region definition explicitly excludes the source region from it. As mentioned before, the background file cannot be loaded into ds9; see "ahelp dmregions" for information on the region syntax.



Parameters for /home/username/cxcds_param/dmgroupreg.par


        infile = simple_ds9.reg   DS9 region input file
    srcoutfile = simple_src.reg   Output file for CIAO source regions
    bkgoutfile = simple_bkg.reg   Output file for CIAO background regions
      (exclude = no)              Explicitly exclude source regions from background regions?
      (verbose = 0)               Debug Level (0-5)
      (clobber = no)              Clobber existing files?
         (mode = ql)              
    


Parameters for /home/username/cxcds_param/dmgroupreg.par


        infile = complex_ds9.reg  DS9 region input file
    srcoutfile = complex_src.reg  Output file for CIAO source regions
    bkgoutfile = complex_bkg.reg  Output file for CIAO background regions
      (exclude = no)              Explicitly exclude source regions from background regions?
      (verbose = 0)               Debug Level (0-5)
      (clobber = no)              Clobber existing files?
         (mode = ql)              
    


Parameters for /home/username/cxcds_param/dmgroupreg.par


        infile = subtract_ds9.reg DS9 region input file
    srcoutfile = subtract_src.reg Output file for CIAO source regions
    bkgoutfile = subtract_bkg.reg Output file for CIAO background regions
      (exclude = yes)             Explicitly exclude source regions from background regions?
      (verbose = 0)               Debug Level (0-5)
      (clobber = no)              Clobber existing files?
         (mode = ql)              
    

History

03 Jan 2005 reviewed for CIAO 3.2: no changes
19 Dec 2005 updated for CIAO 3.3: ds9 v4.0b7 is packaged with CIAO 3.3, ds9 v4.0 region format is slightly different than v3.0
01 Dec 2006 reviewed for CIAO 3.4: no changes
16 Jan 2008 reviewed for CIAO 4.0: no changes
24 Jun 2008 updated image display to place figures inline with text
06 Feb 2009 updated for CIAO 4.1: shifted source region slightly to match N0003 data better
05 Feb 2010 updated for CIAO 4.2: changes to the ds9 region file format menu
13 Jan 2011 reviewed for CIAO 4.3: no changes
11 Jan 2012 reviewed for CIAO 4.4: no changes
03 Dec 2012 Review for CIAO 4.5; update file version.
02 Dec 2013 Review for CIAO 4.6; no changes
18 Dec 2014 Review for CIAO 4.7; minor edits.
01 Feb 2016 Updated ds9 links.
24 Jan 2022 Reviewed for CIAO 4.14. Updated for Repro-5.