# Applying Customized Background Regions to LETG/HRC-S Observations

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

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.

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

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.

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

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

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

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.

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

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



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.

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.

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.

## Scripting It

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



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.