Using the Output of Detect Tools

Edit the List of Sources

Once the source list is overlaid on the image, you may see some sources that you want to exclude from the analysis. Currently, ds9 does not number the sources in the field of view. However, double-clicking on a source region brings up the region info box, which lists the region "ID". In Figure 2, the source on the left side of the field of view was chosen - the ID is 12. This number corresponds to the row the region occupies in the FITS file.

NOTE: this technique only works with the first region file loaded into ds9. After that, the imager starts counting up. For example, if you load region_a.fits that has 10 sources, then region_b.fits that has 6, the regions of the second file will be counted from 11 onward. One may, of course, always examine the region file visually to determine which rows to delete.

Figure 2: Finding the ID of a source region

[Version: full-size]

Figure 2: Finding the ID of a source region

The selected source has an ID of 12.

To create a new region file that doesn't have row 12 in it, dmcopy is used:

unix% dmcopy "s3_src.fits[#row=1:11,13:15]" s3_1gone_src.fits

unix% dmlist s3_1gone_src.fits blocks
 
--------------------------------------------------------------------------------
Dataset: s3_1gone_src.fits
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: SRCLIST                        Table        31 cols x 14       rows

The dmlist command shows that there are only 14 rows in the file now. This new file may be displayed in ds9 (Figure 3) to ensure that the correct source was removed.

Figure 3: Confirming a removed source

[Version: full-size]

Figure 3: Confirming a removed source

The unwanted source (blue cross) is no longer present in the region file (green ellipses).

This filter was fairly simple. It is possible to make more complicated filters with the DM syntax. If you wanted to exclude rows (sources) 8, 12, and 14 from the original file:

unix% dmcopy "s3_src.fits[#row=1:7,9:11,13,15]" s3_3gone_src.fits

unix% dmlist s3_3gone_src.fits blocks
 
--------------------------------------------------------------------------------
Dataset: s3_3gone_src.fits
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: SRCLIST                        Table        31 cols x 12       rows

unix% dmlist s3_3gone_src.fits"[cols ra,dec,net_counts]" data

--------------------------------------------------------------------------------
Data for Table Block SRCLIST
--------------------------------------------------------------------------------
 
ROW    RA                   DEC                  NET_COUNTS
 
     1       212.8639501188        52.1921273978               63.250
     2       212.8474548928        52.2255111480                320.0
     3       212.8360726227        52.2021137798             33.43750
     4       212.8353651758        52.2027847341             87.81250
     5       212.8349227409        52.2031706722              67.6250
     6       212.8067722124        52.2280881209             29.31250
     7       212.8783563224        52.2399625097        31.4285717010
     8       212.8360692107        52.2365737442        20.4285717010
     9       212.8309806527        52.2335386574       125.5714263916
    10       212.7481005259        52.1982204514        51.1428565979
    11       212.7873357718        52.2792122394                 32.0
    12       212.8535943060        52.3232348586        54.7449989319

Sort on a Particular Column

The tool dmsort makes it possible to sort on any column in the FITS file. To order the rows by NET_COUNTS:

unix% dmlist "s3_src.fits[cols net_counts]" data
 
--------------------------------------------------------------------------------
Data for Table Block SRCLIST
--------------------------------------------------------------------------------
 
ROW    NET_COUNTS  
 
     1               63.250
     2                320.0
     3             33.43750
     4             87.81250
     5              67.6250
     6             29.31250
     7        31.4285717010
     8        23.4285717010
     9        20.4285717010
    10       125.5714263916
    11        51.1428565979
    12        25.3977279663
    13                 32.0
    14        76.7916641235
    15        54.7449989319


unix% dmsort s3_src.fits s3_sorted_src.fits keys=net_counts copyall=yes

unix% dmlist "s3_sorted_src.fits[cols net_counts]" data
 
--------------------------------------------------------------------------------
Data for Table Block SRCLIST
--------------------------------------------------------------------------------
 
ROW    NET_COUNTS  
 
     1        20.4285717010
     2        23.4285717010
     3        25.3977279663
     4             29.31250
     5        31.4285717010
     6                 32.0
     7             33.43750
     8        51.1428565979
     9        54.7449989319
    10               63.250
    11              67.6250
    12        76.7916641235
    13             87.81250
    14       125.5714263916
    15                320.0

The default behavior of dmsort is to organize the results in ascending order. To sort NET_COUNTS in descending order, add a dash ("-") before the column name:

unix% dmsort s3_src.fits s3_descend_src.fits keys=-net_counts copyall=yes

unix% dmlist "s3_descend_src.fits[cols net_counts]" data
 
--------------------------------------------------------------------------------
Data for Table Block SRCLIST
--------------------------------------------------------------------------------
 
ROW    NET_COUNTS  
 
     1                320.0
     2       125.5714263916
     3             87.81250
     4        76.7916641235
     5              67.6250
     6               63.250
     7        54.7449989319
     8        51.1428565979
     9             33.43750
    10                 32.0
    11        31.4285717010
    12             29.31250
    13        25.3977279663
    14        23.4285717010
    15        20.4285717010

It is also possible to have several sort priorities (i.e. sort by NET_COUNTS, then NET_COUNTS_ERR); see ahelp dmsort for more information on how to sort files.

Filtering the Source List

If you are interested in only using a certain range of data in your analysis, use the DM filtering syntax to create a new source list with only those items.

To keep the sources that have 40 or more net counts:

unix% dmcopy "s3_src.fits[net_counts=40:]" s3_40cts_src.fits
unix% dmlist "s3_40cts_src.fits[cols net_counts]" data
 
--------------------------------------------------------------------------------
Data for Table Block SRCLIST
--------------------------------------------------------------------------------
 
ROW    NET_COUNTS  

     1               63.250
     2                320.0
     3             87.81250
     4              67.6250
     5       125.5714263916
     6        51.1428565979
     7        76.7916641235
     8        54.7449989319

or those with NET_COUNTS between 25 and 80:

unix% dmcopy "s3_src.fits[net_counts=25:80]" s3_25-80cts_src.fits
unix% dmlist "s3_25-80cts_src.fits[cols net_counts]" data
 
--------------------------------------------------------------------------------
Data for Table Block SRCLIST
--------------------------------------------------------------------------------
 
ROW    NET_COUNTS  
 
     1               63.250
     2             33.43750
     3              67.6250
     4             29.31250
     5        31.4285717010
     6        51.1428565979
     7        25.3977279663
     8                 32.0
     9        76.7916641235
    10        54.7449989319

See ahelp dmfiltering for other variations on the filtering syntax.

Converting Coordinates to Sexagesimal

Often it is desirable to have the list of sources in sexagesimal format, i.e. (RA,Dec) = (hms,dms). This can be done in ds9, with prop_precess, or using the in CIAO 4.13 regphystocel script.

• The regphystocel script can be used to convert regions in physical coordinates to celestial coordinates.

  % regphystocel s3_src.fits s3_src_ds9.reg clob+
  regphystocel
            infile = s3_src.fits
           outfile = s3_src_ds9.reg
           wcsfile = 
              text = 
               tag = 
           clobber = yes
           verbose = 1
              mode = ql
  % cat s3_src_ds9.reg
  # Region file format: DS9 version 4.1
  global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
  fk5
  ellipse(14:11:27.3480,52:11:31.6586,1.13986",1.04162",105.875) #  
  ellipse(14:11:20.6574,52:12:7.6096,1.19459",1.01787",46.4835) #  
  ellipse(14:11:20.4876,52:12:10.0250,1.14609",1.00387",150.605) #  
  ellipse(14:11:20.3814,52:12:11.4144,1.16916",1.00168",58.3717) #  
  ellipse(14:11:30.8055,52:14:23.8650,2.29888",1.06689",38.4504) #  
  ellipse(14:11:29.1075,52:13:32.9885,1.62626",1.35886",149.574) #  
  ellipse(14:11:23.3928,52:13:31.9038,1.44264",1.20934",38.5049) #  
  ellipse(14:11:20.6566,52:14:11.6654,1.84725",1.58222",20.7717) #  
  ellipse(14:11:19.4383,52:14:0.6877,1.63179",1.03905",29.4662) #  
  ellipse(14:11:13.6108,52:13:41.1906,1.59571",1.09014",30.1276) #  
  ellipse(14:10:59.5441,52:11:53.5936,2.47202",1.38874",162.832) #  
  ellipse(14:10:57.3916,52:11:30.6992,2.68163",2.53277",86.0687) #  
  ellipse(14:11:14.4804,52:16:11.3231,4.25802",2.73418",170.309) #  
  ellipse(14:11:8.9605,52:16:45.1640,4.08829",3.7775",165.325) #  
  ellipse(14:11:4.2612,52:17:54.7220,7.1976",4.75093",19.4732) #  
  ellipse(14:11:4.0251,52:17:55.3782,7.65908",5.67733",17.9386) #  
  ellipse(14:11:24.7655,52:19:23.6054,8.85711",6.83045",0.264078) #  
  

• In ds9: load the event file and display the source list on top of it. To save the regions in another format:

  1. Region → Save Regions... → Save As "s3_src_ds9.reg".
  2. After choosing "OK" in the region filename dialog, a format dialog is opened. Set the format to "CIAO" and the coordinate system to "WCS" and "Equatorial J2000".

  The output (an ASCII region file) still contains the shape definitions, but the coordinates are now given as sexagesimal:

  unix% cat s3_src_ds9.reg
  # Region file format: CIAO version 1.0
  ellipse(14:11:27.347,+52:11:31.66,0.0189976',0.0173604',105.875)
  ellipse(14:11:23.389,+52:13:31.84,0.0189597',0.0151168',31.9394)
  ellipse(14:11:20.657,+52:12:07.61,0.0199099',0.0169644',46.4835)
  ellipse(14:11:20.487,+52:12:10.03,0.0191015',0.0167311',150.605)
  ellipse(14:11:20.381,+52:12:11.42,0.019486',0.0166947',58.3717)
  ellipse(14:11:13.625,+52:13:41.12,0.0163116',0.0149855',114.407)
  ellipse(14:11:30.805,+52:14:23.87,0.0383147',0.0177815',38.4504)
  ellipse(14:11:29.107,+52:13:32.99,0.0271043',0.0226476',149.574)
  ellipse(14:11:20.656,+52:14:11.67,0.0307874',0.0263703',20.7717)
  ellipse(14:11:19.435,+52:14:00.74,0.0259394',0.0182104',26.632)
  ellipse(14:10:59.544,+52:11:53.60,0.0412003',0.0231457',162.832)
  ellipse(14:11:14.446,+52:16:11.20,0.0585538',0.0422066',0.0725874)
  ellipse(14:11:08.960,+52:16:45.17,0.0681381',0.0629584',165.325)
  ellipse(14:11:03.981,+52:17:56.12,0.107363',0.0757421',18.5694)
  ellipse(14:11:24.862,+52:19:23.65,0.12849',0.10075',9.90983)
  

  The file may be redisplayed in ds9, as it retains the CIAO region format.

• With prop_precess: prop_precess is a proposal tool that may be used to convert the (RA,Dec) in the FITS source list from decimal to sexagesimal format.

  unix% dmlist s3_src.fits"[cols ra,dec]" data,clean > decimal.txt
  
  unix% prop_precess f j2000/deg t j2000/hms : decimal.txt : hms.txt
  Opened input file decimal.txt
  Opened output file hms.txt
  
  unix% cat hms.txt
  RA,Dec J2000.0                          RA,Dec J2000.0
  212.863950    52.192127                 14 11 27.35 +52 11 31.66
  212.847455    52.225511                 14 11 23.39 +52 13 31.84
  212.836073    52.202114                 14 11 20.66 +52 12 07.61
  212.835365    52.202785                 14 11 20.49 +52 12 10.03
  212.834923    52.203171                 14 11 20.38 +52 12 11.41
  212.806772    52.228088                 14 11 13.63 +52 13 41.12
  212.878356    52.239963                 14 11 30.81 +52 14 23.87
  212.871281    52.225830                 14 11 29.11 +52 13 32.99
  212.836069    52.236574                 14 11 20.66 +52 14 11.67
  212.830981    52.233539                 14 11 19.44 +52 14 00.74
  212.748101    52.198220                 14 10 59.54 +52 11 53.59
  212.810193    52.269778                 14 11 14.45 +52 16 11.20
  212.787336    52.279212                 14 11 08.96 +52 16 45.16
  212.766588    52.298921                 14 11 03.98 +52 17 56.11
  212.853594    52.323235                 14 11 24.86 +52 19 23.65
  

Creating Individual Spectra

It is possible to create a spectrum from any of the regions in the source list without having to divide up the file. To extract a PI spectrum of the second source in the file and bin it by a factor of 5:

unix% punlearn dmextract
unix% dmextract "s3_evt2.fits[sky=region(s3_src.fits[#row=2])][bin pi=::1]" \
      spectrum.fits

The contents of the parameter file may be checked using plist dmextract.

The resultant spectrum can be plotted in python using matplotlib.

$ python

from pycrates import read_file
import matplotlib.pyplot as plt

tab = read_file("spectrum.fits")
xcol = tab.get_column("channel")
ycol = tab.get_column("counts")

def mklabel(col):
    lab = col.name
    if hasattr(col, "unit") and len(col.unit)>0:
        lab = lab + ' [{}]'.format(col.unit)
    return(lab)

xlab=mklabel(xcol)
ylab=mklabel(ycol)

plt.plot(xcol.values, ycol.values)
plt.xlim(0, 100)
plt.xlabel(xlab)
plt.ylabel(ylab)
plt.title("File: spectrum.fits")
plt.savefig("plot1.png")

Figure 4 shows the plot. This data may also be fit in Sherpa, once the proper response files have been created; see the Step-by-Step Guide to Creating ACIS Spectra for Pointlike Sources thread for more information.

Figure 4: Plot of the spectrum

[Version: full-size]

Figure 4: Plot of the spectrum

This spectrum was created from a single source in the event file (id=2).

Creating Multiple Spectra

To create an individual spectrum for each of the sources, use the igrid(1:n:steps) stack syntax, where n is the number of sources in the file.

For s3_src.fits, which has 15 sources in it:

unix% dmextract "s3_evt2.fits[sky=region(s3_src.fits[component=igrid(1:15:1)])][bin pi=::1]" \
      multi_spectra_phaII.fits op=pha2

The output file is a type II PHA file that has one spectrum per row:

unix% dmlist multi_spectra_phaII.fits blocks
 
--------------------------------------------------------------------------------
Dataset: multi_spectra_phaII.fits
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: SPECTRUM                       Table         7 cols x 15       rows
Block    3: GTI7                           Table         2 cols x 1        rows

For more information on working with this type of file, see the Displaying the Spectrum section of the Examining Grating Spectra and Regions: PHA2 files thread (the information in that section applies to imaging files as well).

Creating a Composite Spectrum

It is also possible to extract a composite spectrum of all the (faint) sources in a field for a single spectral analysis. This may be useful in the case where the sources might be of similar characteristics, but there are not enough counts in any given source to do individual spectra.

Here we have deleted the sources associated with 3C295 (IDs 3-5):

unix% dmcopy "s3_src.fits[#row=1:2,6:]" s3_nocore_src.fits

Now we can use dmextract to accept all the regions together and create a spectrum:

unix% dmextract "s3_evt2.fits[sky=region(s3_nocore_src.fits)][bin pi=::5]" \
      spectrum_faint.fits

Again, the resultant spectrum can be plotted :

$ python

from pycrates import read_file
import matplotlib.pyplot as plt

tab = read_file("spectrum_faint.fits")
xcol = tab.get_column("channel")
ycol = tab.get_column("counts")

def mklabel(col):
    lab = col.name
    if hasattr(col, "unit") and len(col.unit)>0:
        lab = lab + ' [{}]'.format(col.unit)
    return(lab)

xlab=mklabel(xcol)
ylab=mklabel(ycol)

plt.plot(xcol.values, ycol.values)
plt.xlim(0,100)
plt.xlabel(xlab)
plt.ylabel(ylab)
plt.title("File: spectrum_faint.fits")
plt.savefig("plot2.png")

Figure 5 shows the plot.

Figure 5: Composite spectrum

[Version: full-size]

Figure 5: Composite spectrum

The composite spectrum was created by combining counts from 14 sources.

As mentioned before, this data may also be fit in Sherpa, once the proper response files have been created; see the Step-by-Step Guide to Creating ACIS Spectra for Pointlike Sources thread for more information.

Removing Unwanted Point Sources

Often it is desirable to remove point sources from an image for both cosmetic and scientific reasons. For example, if you are analyzing an extended source, an unfortunately located point source may affect the count rates in the object.

Suppose that we want to remove all the point sources from our field of view, except for the three in the core (sources 3-5). First, create a source list that excludes these three regions:

unix% dmcopy "s3_src.fits[#row=1:2,6:15]" s3_holes_src.fits

Now filter the event file with those regions:

unix% dmcopy "s3_evt2.fits[exclude sky=region(s3_holes_src.fits)]" s3_holes_evt2.fits

unix% ds9 s3_holes_evt2.fits &

The resulting image, Figure 6, has holes where the sources used to be. The Obtain and Fit a Radial Profile thread illustrates another case in which you might use this syntax (see the Removing Contaminating Point Sources section).

Figure 6: Event file with sources removed

[Version: full-size]

Figure 6: Event file with sources removed

The source regions are replaced by areas of zero counts.

A more sophisticated means of removing point sources is to use dmfilth. This tool removes the point source and then fills in the hole where the source was. See ahelp dmfilth for more information and the Identify and Remove Point Sources section of the Image of Diffuse Emission thread for an example.