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

   

   [Version: full-size]

   

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

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

[Version: full-size]

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

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

[Version: full-size]

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.

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

[Version: full-size]

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.