Skip to the navigation links
Last modified: 19 Jul 2010
Where are the PDFs?

Applying Customized Background Regions to LETG/HRC-S Observations

CIAO 4.2 Science Threads



Overview

Last Update: 19 Jul 2010 - the S-Lang syntax has been removed from this thread as it is not supported in CIAO 4.2 Sherpa v2.

Synopsis:

This thread demonstrates the use of tgextract2 to apply customized background regions to an LETG/HRC-S observation of a field with two, close, bright sources. With LETGS, it is important to include backgrounds in the analysis since the HRC-S instrumental background is significant.

Each source in ObsID 29 falls into one of the default background regions for the other. The sources themselves are far enough apart that their spectra can be extracted cleanly. Creating a custom region will avoid background contamination by either of the sources.

Read this thread if:

LETG/HRC-S observations where some detailed and interactive analysis is required, involving some scientific judgement by the analyst, to determine the background region to apply.



Contents



Introduction to tgextract2

tgextract2 is an alternative to tgextract, the CIAO tool which filters and bins spectra. tgextract2 provides support for variable-shaped background regions which do not need to have a constant width ratio with the source region. tgextract2 computes a vector "backscale"—the scaling factor which relates the background count rate at any wavelegth to the source extraction region width at that wavelength. tgextract2 also sums the background extractions from each side of the spectrum, whereas tgextract writes two counts arrays, one from the "_UP" and one from the "_DOWN" sides of the spectrum.

Since tgextract2 is not backward-compatible with tgextract, it is not used in standard processing. It is instead recommended for special cases where some detailed and interactive analysis is required, involving some scientific judgement by the analyst.



Getting Started

Sample ObsID used: 29 (LETG/HRC-S, Alpha Cen)

File types needed: evt2

The standard HRC grating region file, found in CalDB, is also used: $CALDB/data/chandra/hrc/tgmask2/letgD1999-07-22regN0002.fits. It is assumed that all files are in the working directory.

Open the event file in DS9:

unix% ds9 hrcf00029N005_evt2.fits &

Next, we set the height and width to something convenient for grating spectra, and adjust the colorscale and colormap in the DS9 menu.

  • Frame → Set Display Size → X=1024, Y=400
  • Scale → Log
  • Color → BB
  • Color → Colormap Parameters → Contrast=5, Bias=0.4

Figure 1 shows the resulting image.

[Thumbnail image: CCD image of source after color parameters have been changed]

[Version: full-size]

[Print media version: CCD image of source after color parameters have been changed]

Figure 1: Source Image

Source image with BB colormap and log-scale selected, and colormap parameters applied.

Next, we set the binning parameters in the DS9 menu Bin → Binning Parameters (Figure 2):

[DS9 menu settings for binning the source image and converting it to grating dispersion coordinates to provide a grating spectrum.]
[Print media version: DS9 menu settings for binning the source image and converting it to grating dispersion coordinates to provide a grating spectrum.]

Figure 2: Grating Coordinates Binning Parameters

Binning parameter settings applied in DS9 by going to the menu and choosing Bin → Binning Parameters.

The binning was iteratively chosen such that the field fits the screen and it has enough counts/bin to give good statistics. Fiddling with parameters, we start off with knowing that the tg_r coordinate range is -1 to 1 degrees in about 10000 bins, or 0.0002 deg/bin. Binning by a factor of 10, we have a tg_d range of about -0.002 to 0.002 deg/bin.

After applying the binning parameters, the field image in grating dispersion coordinates shows two spectra (Figure 3):

[Thumbnail image: The grating spectrum of the two field sources after binning parameters are applied.]

[Version: full-size]

[Print media version: The grating spectrum of the two field sources after binning parameters are applied.]

Figure 3: Grating Spectrum of the Two Field Sources

This is the field image in grating dispersion coordinates with tg_r (in-dispersion) on the horizontal axis, and tg_d (cross-dispersion) on the vertical axis (both in degrees). We can clearly see the two sources zero-orders near physical coordinates (0,0) and their dispersed and line-rich spectra, with negative-orders to the left and positive-orders to the right. The vertical dark regions are gaps between the HRC-S microchannel plates.



Region Editing

The standard HRC region file must be edited for the current field. It is not possible to edit the file in DS9 because it is not precise enough for this application and DS9 cannot write the file back out into the correct format, retaining all the ancillary information about the region (grating type, order, region type).

However, DS9 is still useful to approximate the adjustments to be applied on the regions.

Visualizing the Modified Region with DS9

After loading the region into DS9 (Region → Load Regions → letgD1999-07-22regN0002.fits), we examine the wedge-shaped background region for the positive side (upper right), shown in Figure 4

[Thumbnail image: Getting a rough approximation of how we want to edit the regions]

[Version: full-size]

[Print media version: Getting a rough approximation of how we want to edit the regions]

Figure 4: Modified Standard HRC Regions

This is the modified HRC region, where the upper-right region has been modified, moving the bottom to tg_d=0.006 and the wedge inflection point to (tg_r,tg_d)≅(0.001,0.024). The changes are mirrored along both tg_r and tg_d axes. The source regions can be left unaltered. The choices were picked by fiddling with the regions until a (approximately) blocked region was formed, well separated from the source spectrum that encompassed a large background area.

We need to move the bottom to about tg_d=0.006 and the wedge inflection point to about (tg_r,tg_d)≅(0.001,0.024). Since the background regions are symmetric, we can do the same on the minus (upper left) side.

The lower background regions (for the second source) are not used in this thread. However, they are adjusted to be symmetric with the upper backgrounds in case of future extractions.


Download the Script

We provide a script written in Python to edit the FITS regions of the HRC-S grating region. Placing this script in your working directory, when executed, automatically copies and modifies the HRC-S region file found in CalDB to your working directory. The script accesses crates (S-Lang or Python help) to directly change the in-dispersion and cross-dispersion coordinates of the region vertices, while retaining the necessary ancillary information within the FITS region header.


Editing Region Files

From our experimentation in DS9, we want to shift our background region inflection points, with coordinates, (TG_R[1],TG_D[1]), within the FITS file, and move all the background regions, vertically, in the cross-dispersion direction away from the source regions.

Thus, the background region values will be changed as follows:

  • TG_R[1] will have a value of either +/-0.0057
  • TG_D[1] will have a value of either +/-0.024
  • All other TG_D values will be determined by adding (subtracting) 0.005 to (from) the cell.

The syntax for using our script is: tgextract2_crates TG_R[1] TG_D[1] TG_D outfile. So we will create the background region, hrc_0029_reg.fits:

unix% tgextract2_crates 0.0057 0.024 0.005 hrc_0029_reg.fits
Created: hrc_0029_reg.fits

We can clear the previous region definition from DS9 and load the new background definition (Figure 5).

[Thumbnail image: Edited background regions displayed in DS9]

[Version: full-size]

[Print media version: Edited background regions displayed in DS9]

Figure 5: Edited Background Regions

The edited background regions displayed in DS9 over the source field in grating dispersion coordinates.



Run tgextract2

With the background regions appropriately defined, we are now ready to run tgextract2. The opt parameter is set to "pha1" so that the tool creates separate files for the +1 and -1 spectra (Type 1 PHA file), rather than both spectra be written as rows in the same file (Type 2 PHA file). The files will also contain the background extractions and the "areas" (BACKSCAL) of the source and background regions for each spectral bin.

The outfile parameter value (a_) is used as the root name of the output files. The files will be named as "root<srcid><part><order>_pha2.fits", one for each source ID, part, and order combination.

unix% punlearn tgextract2
unix% pset tgextract2 infile=hrcf00029N005_evt2.fits
unix% pset tgextract2 outfile=a_ 
unix% pset tgextract2 region_file=hrc_0029_reg.fits
unix% pset tgextract2 opt=pha1

unix% tgextract2 
Input event file (output event file from L1.5 processing) (hrcf00029N005_evt2.fits):
Output pha file (for pha2, enter full file name or '.'; for pha1, enter rootname.) (a_):
Source ID's to process: 'all', comma list, @file (1):
Grating parts to process: HETG, HEG, MEG, LETG, header_value (HETG|HEG|MEG|LETG|header_value) (header_value):
Grating diffraction orders to process: 'default', comma list, range list, @file (default):

This produces two new files, a_01Lm1_pha2.fits and a_01Lp1_pha2.fits, which are -1 order and +1 order LEG spectra, respectively.

You can check the parameter file that was used with plist tgextract2.

After we run tgextract2, we will copy the background counts to a separate file, one for each order. This is because various analysis softwares typically need to have the background spectrum formatted the same way as the source (i.e. having the same column names).

unix% dmcopy 'a_01Lm1_pha2.fits[cols CHANNEL,BIN_LO,BIN_HI,COUNTS=bg_counts,BACKSCAL=bg_area]' a_01Lm1_pha2_bg.fits
unix% dmcopy 'a_01Lp1_pha2.fits[cols CHANNEL,BIN_LO,BIN_HI,COUNTS=bg_counts,BACKSCAL=bg_area]' a_01Lp1_pha2_bg.fits


Inspecting the Counts and Background Spectra with Sherpa

We will now inspect the counts and background spectra. Using Sherpa, we will create a strip-chart displaying the plus- and minus-order counts spectra, with background over-plotted. We begin by loading the data and background with the minus-order spectrum associated with dataset ID=1 and positive-order spectrum associated with dataset ID=2.

unix% sherpa
-----------------------------------------------------
Welcome to Sherpa: CXC's Modeling and Fitting Package
-----------------------------------------------------
CIAO 4.2 Sherpa version 2 Tuesday, July 6, 2010

sherpa> load_pha(1,"a_01Lm1_pha2.fits")
sherpa> load_pha(2,"a_01Lp1_pha2.fits")
sherpa> load_bkg(1,"a_01Lm1_pha2_bg.fits")
sherpa> load_bkg(2,"a_01Lp1_pha2_bg.fits")

Next we set Sherpa and ChIPS; plotting preferences. The key parameter is set_analysis, which plots the spectrum as counts vs. wavelength.

sherpa> set_analysis("wave",type="counts")

sherpa> prefs = get_data_plot_prefs()
sherpa> prefs["linestyle"] = chips_solid
sherpa> prefs["symbolstyle"] = chips_none
sherpa> prefs["yerrorbars"] = 0

Loading a two plot strip chart, we first add the minus-order counts spectrum to the upper plot:

sherpa> strip_chart (S-Lang or Python help)(2,0,0,[1,1],2,chips_closed,[0,180],[0,30])

sherpa> current_plot (S-Lang or Python help)("plot1")
sherpa> add_curve (S-Lang or Python help)(get_data_plot(1).x,get_data_plot(1).y,["symbol.style",0])

Next, we over-plot the minus-order count spectrum with the minus-order background in red:

sherpa> bs1=get_backscal(1)
sherpa> et1=get_exposure(1)
sherpa> bsbg1=get_backscal(1,bkg_id=1)
sherpa> etbg1=get_exposure(1,bkg_id=1)
sherpa> ct1=get_counts(1,bkg_id=1)

sherpa> add_curve (S-Lang or Python help)(get_data_plot(1).x,(ct1*(bs1*et1)/(bsbg1*etbg1)),\
        ["line.color","red","symbol.style",0])
sherpa> set_plot_ylabel (S-Lang or Python help)("Counts") 
sherpa> add_label (S-Lang or Python help)(1.05,0.75,"Negative-Order",["coordsys",PLOT_NORM,"angle",270])

Now we populate the lower plot with the plus-order counts and background spectra in the same manner, by first setting current_plot (S-Lang or Python help)("plot2").

sherpa> current_plot (S-Lang or Python help)("plot2")
sherpa> add_curve (S-Lang or Python help)(get_data_plot(2).x,get_data_plot(2).y,["symbol.style",0])

sherpa> bs2=get_backscal(2)
sherpa> et2=get_exposure(2)
sherpa> bsbg2=get_backscal(2,bkg_id=1)
sherpa> etbg2=get_exposure(2,bkg_id=1)
sherpa> ct2=get_counts(2,bkg_id=1)

sherpa> add_curve (S-Lang or Python help)(get_data_plot(2).x,(ct2*(bs2*et2)/(bsbg2*etbg2)),["line.color","red","symbol.style",0])

sherpa> set_plot_xlabel (S-Lang or Python help)(r"\lambda (\AA)")
sherpa> set_plot_ylabel (S-Lang or Python help)("Counts")
sherpa> add_label (S-Lang or Python help)(1.05,0.75,"Positive-Order",["coordsys",PLOT_NORM,"angle",270])

sherpa> limits (S-Lang or Python help)(X_AXIS,0,180)
sherpa> limits (S-Lang or Python help)(Y_AXIS,0,35)

And adding the plot title:

sherpa> current_plot("plot1")
sherpa> set_plot_title (S-Lang or Python help)('Counts and Background (red) for Negative- and Positive-Orders')

The results of this plot can be see in Figure 6.

[Thumbnail image: minus- and plus-order counts and background spectra of field]

[Version: full-size]

[Print media version: minus- and plus-order counts and background spectra of field]

Figure 6: Spectra of Field Sources with Background Spectra over-plotted in red

Strip chart of the spectra of counts (white) and background (red) with negative orders in the upper frame and postive orders in the lower frame.

Before exiting Sherpa, you may want to write the plot to a file. In this example, we use the interactive print dialog.

sherpa> print_window (S-Lang or Python help)("letgs_spec_bg",["printdialog",1])

Note that print_window (S-Lang or Python help) automatically inverts black and white for PDF and postscript formatted files.



Events in Wavelength Coordinates

To confirm that the edits made to the region were well-chosen, we inspect the events in wavelength coordinates. With the event file displayed in DS9:

unix% ds9 hrcf00029N005_evt2.fits &

we change the parameters to bin on wavelength coordinates (tg_lam,tg_d) (Bin → Binning Parameters). Again, we have to fiddle with our binning parameters, but we have some starting points. We can keep the tg_d binning of 0.00015 since the cross-dispersion ranges between -1 to 1 degree over about 10000 bins. The nominal wave-band coverage for the LETGS when using HRC-S is ≅150-175 Å. In wavelength, LETGS has 0.015 Å/bin; binning up by a factor of 10, we can get a good plot.

[DS9 menu settings for binning the source image and converting it to wavelength coordinates.]
[Print media version: DS9 menu settings for binning the source image and converting it to wavelength coordinates.]

Figure 7: Wavelength Coordinates Binning Parameters

Binning parameter settings applied in DS9 by going to the menu and choosing Bin → Binning Parameters.

Changing the Colormap parameters to:

  • Color → Colormap Parameters → Contrast=3.5, Bias=0.85

Then load the region which is stored in the PHA file, a_01Lp1_pha2.fits. Figure 8 shows the events and extraction regions in wavelength coordinates.

[Thumbnail image: The grating spectrum of the two field sources after new binning parameters are applied, region from pha2 file overlayed.]

[Version: full-size]

[Print media version: The grating spectrum of the two field sources after new binning parameters are applied, region from pha2 file overlayed.]

Figure 8: Grating Spectrum of the Two Field Sources in Wavelength Coordinates

This is the field image in wavelength coordinates with tg_lam (wavelength) on the horizontal axis, and tg_d (cross-dispersion) on the vertical axis. The region from a_01Lp1_pha2.fits is overlaid, showing the source and background.



Scripting It

The file, tgextract2.py, performs the Sherpa commands used above.




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



Parameters for /Users/home/cxcds_param4/tgextract2.par

##
## create 1D spectrum(a) table file(s) from the L1.5 output event list
##
        infile = 29/primary/hrcf00029N005_evt2.fits Input event file (output event file from L1.5 processing)
       outfile = a_               Output pha file (for pha2, enter full file name or '.'; for pha1, enter rootname.)
#
# tg_srcid_list parameter explanation:
#  - "all, blank or none" processes all the sources id's found in the event list.
#  - a comma list is a comma separated string list of all the sources to process. 
#          eg.  "1,2,5,7"
#  - @file is a pointer to an ascii file which contains the id's to process. 
#    Limit one id per line. no comma list is allowed in @file.
#
 tg_srcid_list = 1                Source ID's to process: 'all', comma list, @file
  tg_part_list = header_value     Grating parts to process: HETG, HEG, MEG, LETG, header_value
#
# tg_order_list parameter explanation :
#  - "default, blank or none" is set to process the following :
#          for ACIS :  1, 2, 3, -1, -2, -3
#          for HRC :   -1, 1
#  - a comma list is a comma separated string list of the orders
#    the user wants to process.
#          eg.  "-5, -1, 1, 3"
#  - a range list sets the min and max of the orders to process.
#    all the orders in between, will be processed. 
#          eg.  "-1..5"  will process orders from -1 to +5th order
#    a range list can be mixed with comma separated list
#  - @file is a pointer to an ascii file which contains 
#    the orders to process. Limit one order per line.
#    a range list is allowed in @file, but no comma list.
#
 tg_order_list = default          Grating diffraction orders to process: 'default', comma list, range list, @file
          (opt = pha1)            Output file type: pha1 (single spectrum) or pha2 (multiple spectra)
#
# If wav_grid is set to a binning specification (other than "use_header"), then 
# the following grating-specific parameters 'wav_grid_*' will be ignored.
#
     (wav_grid = use_header)      grid specification (use_header| min:max:step| min:max:#bins|pre-defined standard grid)
 (wav_grid_heg = 1.0:21.48:0.0025) pre-defined standard HEG grid
 (wav_grid_meg = 1.0:41.96:0.0050) pre-defined standard MEG grid
 (wav_grid_leg = 1.0:205.80:0.0125) pre-defined standard LETG grid
(wav_grid_leg_acis = 1.0:103.4:0.0125) pre-defined standard LETG/ACIS grid
   (evt_filter = none)            Filter to apply to events for counts spectra
(ignore_source_id = yes)             match source id between regionFile and evtFile?
        (error = gaussian)        Method for error determination (gaussian|gehrels)
  (region_file = hrc_0029_reg.fits) Input region file ( NONE | none | <filename>)
      (geompar = geom)            Parameter file for Pixlib Geometry files
     (min_tg_d = default)         Minimum tg_d for source spectrum, in degrees
     (max_tg_d = default)         Maximum tg_d for source spectrum, in degrees
(extract_background = yes)             Extract the local background spectrum?
(min_upbkg_tg_d = default)         Minimum tg_d for upper background spectrum, in degrees
(max_upbkg_tg_d = default)         Maximum tg_d for upper background spectrum, in degrees
(min_downbkg_tg_d = default)         Minimum tg_d for down background spectrum, in degrees
(max_downbkg_tg_d = default)         Maximum tg_d for down background spectrum, in degrees
(backscale_method = events)          Use events and region, or region-only for backscale
(backscale_resolution = 64)              Amount in pixels to bin in wavelength to improve statistics in backscale
      (clobber = no)              overwrite any existing output file?
      (verbose = 0)               Verbosity level (0 = no display)
         (mode = ql)              



History

20 Apr 2009 New for CIAO 4.1
01 Feb 2010 reviewed for CIAO 4.2: no changes
19 Jul 2010 the S-Lang syntax has been removed from this thread as it is not supported in CIAO 4.2 Sherpa v2.

Return to Threads Page: Top | All | Grating

Where are the PDFs?
Last modified: 19 Jul 2010