Creating Source and Background Files

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 acisf00650N002_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 .

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:

   • Region -> File Format-> DS9/FUNTOOLS
   • Region -> File Coordinate System -> Physical
   • Region -> Save Regions... -> Save As "simple_ds9.reg"

   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% more simple_ds9.reg 
   # Region file format: DS9 version 4.0
   # Filename: /data/group_regions/acisf00650N002_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(4109.5,4253.5,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% more simple_src.reg 
# Group 1
circle(4109.5,4253.5,34)

unix% more 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.

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% more complex_ds9.reg
# Region file format: DS9 version 4.0
# Filename: /data/group_regions/acisf00650N002_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={Group 2}
box(4363,4042,173,201,0) # background tag={Group 1}
circle(4084.5,4058.5,18) # tag={Group 1}
circle(4234.5,3886.5,22) # tag={Group 1}
circle(3746.5,3768.5,22) # tag={Group 2}
circle(3800.5,4442.5,16) # tag={Group 1}
circle(3834.5,4458.5,18) # tag={Group 1}
circle(3886.5,4556.5,16) # tag={Group 1}
circle(4004.5,4542.5,36) # tag={Group 1}
circle(4284.5,4482.5,22) # tag={Group 1}
circle(4522.5,4442.5,32) # tag={Group 1}
circle(4566.5,4550.5,28) # tag={Group 1}
circle(3750.5,4536.5,18) # tag={Group 1}
circle(3894.5,4420.5,18) # tag={Group 1}
circle(3682.5,4560.5,18) # tag={Group 1}
circle(3740.5,4178.5,32) # tag={Group 1}
circle(4192.5,3806.5,10) # tag={Group 2}
circle(4146.5,3642.5,8) # tag={Group 2}
ellipse(3982.5,4032.5,46,20,324.07779) # tag={Group 1}
box(4412,4376,101,311,0) # background tag={Group 1}
circle(4110.5,4250.5,26) # tag={Group 3}
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={Group 3}
-circle(4096.5,4186.5,12) # background tag={Group 3}
circle(4288.5,3888.5,16) # tag={Group 1}

Displaying the region file in ds9 creates Figure 2 . Notice that the excluded region (marked so via the "Region -> Properties" menu) is displayed with a 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  will be launched. This lists all of the groups defined in the region file.

Clicking on each of the group names will highlight the regions therein on the ds9 display. Figure 4  shows Group 1 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% more complex_src.reg
# Group 2
circle(3746.5,3768.5,22)+circle(4192.5,3806.5,10)+circle(4146.5,3642.5,8)
# Group 1
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)
# Group 3
circle(4110.5,4250.5,26)

unix% more complex_bkg.reg
# Group 2
rotbox(3862.1559,3740.5971,154.50773,175.30802,340.91332)
# Group 1
rotbox(4363,4042,173,201,0)+rotbox(4412,4376,101,311,0)
# Group 3
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.

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.

The region file looks like:

unix% more subtract_ds9.reg 
# Region file format: DS9 version 4.0
# Filename: /data/group_regions/acisf00650N002_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% more subtract_src.reg
# Subtract Group
circle(4111.5,4251.5,102)

unix% more 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.