Last modified: 14 Jan 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/examinepha2/

Examining Grating Spectra and Regions: PHA2 files

CIAO 4.16 Science Threads


Overview

Synopsis:

An overview of displaying grating data Type II PHA files and the source and background extraction regions.

Related Links:

Last Update: 14 Jan 2022 - Reviewed for CIAO 4.14. No changes.


Contents


What is a PHA2 File?

A Type II PHA file is a standard FITS format in which each row contains several columns. The PHA file is a product of standard data processing and is identified by the pha2.fits extension; note that the "2" in the filename refers to the fact that it is a level=2 data product, not that it is a Type II file. In the case that the user has to manually reprocess an event file (e.g. when applying an updated order sorting table), the PHA2 spectrum file is obtained from the level 2 event file by tgextract; see the HETG/ACIS-S Grating Spectra for an example of this.

The SPECTRUM block of a PHA2 file has 13 columns of data:

     ColNo Name                  Description

     1     SPEC_NUM              Spectrum Number
     2     TG_M                  Diffraction order (m)
     3     TG_PART               Spectral component (HEG, MEG, LEG, HESF parts)
     4     TG_SRCID              Source ID, output by tgdetect
     5     X                     X sky coord of source
     6     Y                     Y sky coord of source
     7     CHANNEL[8192]         Vector of spectral bin numbers.
     8     COUNTS[8192]          Counts array (a spectrum)
     9     STAT_ERR[8192]        Statistical uncertainty (error) on counts colum
     10    BACKGROUND_UP[8192]   Upper Background count vector.
     11    BACKGROUND_DOWN[8192] Lower Background count vector.
     12    BIN_LO[8192]          Bin boundary, left edge
     13    BIN_HI[8192]          Bin boundary, right edge

There are two columns that are especially relevant when doing analysis:

  • TG_M indicates the order of the spectrum (+/- 1, +/-2, +/- 3)
  • TG_PART indicates the spectral component / grating arm (1 = HEG, 2 = MEG, 3 = LEG)

Examining the Files

Download the sample data: 459 (HETG/ACIS-S 3C 273); 460 (LETG/HRC-S, 3C 273); 1198 (LETG/ACIS-S, 3C 273); 1800 (LETG/HRC-I, PKS2155-304)

unix% download_chandra_obsid 459,460,1198,1800 evt2,pha2

ACIS-S HETG/LETG Observations

We can use dmlist to examine the PHA2 file for ObsID 459:

unix% dmlist acisf00459N004_pha2.fits blocks,cols
 
--------------------------------------------------------------------------------
Dataset: 459/primary/acisf00459N004_pha2.fits.gz
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: SPECTRUM                       Table        13 cols x 12       rows
Block    3: REGION                         Table        10 cols x 36       rows
 
--------------------------------------------------------------------------------
Columns for Table Block SPECTRUM
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range            Null
   1   SPEC_NUM                          Int2           1:32767              -          Spectrum Number
   2   TG_M                              Int2           -62:62               99         Diffraction order (m)
   3   TG_PART                           Int2           0:99                 -          Spectral component (HEG, MEG, LEG, HESF parts)
   4   TG_SRCID                          Int2           1:32767              -          Source ID, output by detect
   5   X                    pixel        Real4          0.50:    65534.50    -          X sky coord of source
   6   Y                    pixel        Real4          0.50:    65534.50    -          Y sky coord of source
   7   CHANNEL[8192]                     Int2(8192)     1:32767              -          Vector of spectral bin numbers.
   8   COUNTS[8192]         count        Int2(8192)     0:32767              -1         Counts array (a spectrum)
   9   STAT_ERR[8192]       count        Real4(8192)    0:     3.402823466E+38 -          Statistical uncertainty (error) on counts colum
  10   BACKGROUND_UP[8192]  count        Int2(8192)     0:32767              -1         Background count vector.
  11   BACKGROUND_DOWN[8192] count        Int2(8192)     0:32767              -1         Background count vector.
  12   BIN_LO[8192]         angstrom     Real8(8192)    0:      400.0        -          Bin boundry, left edge
  13   BIN_HI[8192]         angstrom     Real8(8192)    0:      400.0        -          Bin boundry, right edge

In this example, there are twelve rows - all the +/- orders for both HEG and MEG - for the observation. The columns CHANNEL, COUNTS, BIN_LO, etc. are all so-called "vector columns"; each contains a vector of elements which, in this example, is 8192 elements long.

An ACIS-S/LETG observation (ObsID 1198) looks similar but only contains 6 rows (+/- orders for the LEG).

unix% dmlist 1198/primary/acisf01198N004_pha2.fits.gz blocks,cols
 
--------------------------------------------------------------------------------
Dataset: 1198/primary/acisf01198N004_pha2.fits.gz
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: SPECTRUM                       Table        13 cols x 6        rows
Block    3: REGION                         Table        10 cols x 18       rows
 
--------------------------------------------------------------------------------
Columns for Table Block SPECTRUM
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range            Null
   1   SPEC_NUM                          Int2           1:32767              -          Spectrum Number
   2   TG_M                              Int2           -62:62               99         Diffraction order (m)
   3   TG_PART                           Int2           0:99                 -          Spectral component (HEG, MEG, LEG, HESF parts)
   4   TG_SRCID                          Int2           1:32767              -          Source ID, output by detect
   5   X                    pixel        Real4          0.50:    65534.50    -          X sky coord of source
   6   Y                    pixel        Real4          0.50:    65534.50    -          Y sky coord of source
   7   CHANNEL[8192]                     Int2(8192)     1:32767              -          Vector of spectral bin numbers.
   8   COUNTS[8192]         count        Int2(8192)     0:32767              -1         Counts array (a spectrum)
   9   STAT_ERR[8192]       count        Real4(8192)    0:     3.402823466E+38 -          Statistical uncertainty (error) on counts colum
  10   BACKGROUND_UP[8192]  count        Int2(8192)     0:32767              -1         Background count vector.
  11   BACKGROUND_DOWN[8192] count        Int2(8192)     0:32767              -1         Background count vector.
  12   BIN_LO[8192]         angstrom     Real8(8192)    0:      400.0        -          Bin boundry, left edge
  13   BIN_HI[8192]         angstrom     Real8(8192)    0:      400.0        -          Bin boundry, right edge

HRC-S/HRC-I LETG Observations

Examining an HRC-S/LETG observation (ObsID 460) is done in the same way as an ACIS grating observation:

unix% dmlist 460/primary/hrcf00460N005_pha2.fits.gz blocks,cols
 
--------------------------------------------------------------------------------
Dataset: 460/primary/hrcf00460N005_pha2.fits.gz
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: SPECTRUM                       Table        13 cols x 2        rows
Block    3: REGION                         Table        10 cols x 6        rows
 
--------------------------------------------------------------------------------
Columns for Table Block SPECTRUM
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range            Null
   1   SPEC_NUM                          Int2           1:32767              -          Spectrum Number
   2   TG_M                              Int2           -62:62               99         Diffraction order (m)
   3   TG_PART                           Int2           0:99                 -          Spectral component (HEG, MEG, LEG, HESF parts)
   4   TG_SRCID                          Int2           1:32767              -          Source ID, output by detect
   5   X                    pixel        Real4          0.50:    65534.50    -          X sky coord of source
   6   Y                    pixel        Real4          0.50:    65534.50    -          Y sky coord of source
   7   CHANNEL[16384]                    Int2(16384)    1:32767              -          Vector of spectral bin numbers.
   8   COUNTS[16384]        count        Int2(16384)    0:32767              -1         Counts array (a spectrum)
   9   STAT_ERR[16384]      count        Real4(16384)   0:     3.402823466E+38 -          Statistical uncertainty (error) on counts colum
  10   BACKGROUND_UP[16384] count        Int2(16384)    0:32767              -1         Background count vector.
  11   BACKGROUND_DOWN[16384] count        Int2(16384)    0:32767              -1         Background count vector.
  12   BIN_LO[16384]        angstrom     Real8(16384)   0:      400.0        -          Bin boundry, left edge
  13   BIN_HI[16384]        angstrom     Real8(16384)   0:      400.0        -          Bin boundry, right edge

but there is an important difference in the results. As seen above, there are only two rows for the LEG observation. HRC-S cannot resolve orders and the COUNTS in the +/- 1 order are in fact the total counts of all orders combined. Also, the BIN_LO and BIN_HI columns should be considered for reference only; they actually represent the boundary wavelength of the +/- 1 order alone, while photons from all orders are included in the spectra.

The same holds true for HRC-I/LETG observations, as seen in the example of ObsID 1800.

unix% dmlist 1800/primary/hrcf01800N008_pha2.fits.gz block,cols
 
--------------------------------------------------------------------------------
Dataset: 1800/primary/hrcf01800N008_pha2.fits.gz
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: SPECTRUM                       Table        13 cols x 2        rows
Block    3: REGION                         Table        10 cols x 6        rows
 
--------------------------------------------------------------------------------
Columns for Table Block SPECTRUM
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range            Null
   1   SPEC_NUM                          Int2           1:32767              -          Spectrum Number
   2   TG_M                              Int2           -62:62               99         Diffraction order (m)
   3   TG_PART                           Int2           0:99                 -          Spectral component (HEG, MEG, LEG, HESF parts)
   4   TG_SRCID                          Int2           1:32767              -          Source ID, output by detect
   5   X                    pixel        Real4          0.50:    65534.50    -          X sky coord of source
   6   Y                    pixel        Real4          0.50:    65534.50    -          Y sky coord of source
   7   CHANNEL[16384]                    Int2(16384)    1:32767              -          Vector of spectral bin numbers.
   8   COUNTS[16384]        count        Int2(16384)    0:32767              -1         Counts array (a spectrum)
   9   STAT_ERR[16384]      count        Real4(16384)   0:     3.402823466E+38 -          Statistical uncertainty (error) on counts colum
  10   BACKGROUND_UP[16384] count        Int2(16384)    0:32767              -1         Background count vector.
  11   BACKGROUND_DOWN[16384] count        Int2(16384)    0:32767              -1         Background count vector.
  12   BIN_LO[16384]        angstrom     Real8(16384)   0:      400.0        -          Bin boundry, left edge
  13   BIN_HI[16384]        angstrom     Real8(16384)   0:      400.0        -          Bin boundry, right edge

Displaying the Spectrum

With matplotlib

To make it easier to display the spectrum with matplotlib we need to split out the desired row(s) with dmtype2split. The +1 order (tg_m=1) HEG (tg_part=1) spectrum for the observation, chosen by the "[tg_part=1,tg_m=1]" filter:

unix% dmtype2split "acisf00459N004_pha2.fits[tg_part=1,tg_m=1]" heg_p1.fits

unix% python
>>> import matplotlib.pyplot as plt
>>> from pycrates import read_file
>>> tab = read_file("heg_p1.fits")
>>> x = tab.get_column("bin_lo").values
>>> y = tab.get_column("counts").values
>>> plt.plot(x,y, marker='None')
>>> plt.xlabel("BIN_LO [angstrom]")
>>> plt.ylabel("COUNTS [count]")
>>> plt.title("ACIS+HEG order=+1")
>>> plt.savefig("plt_01.png")

These commands produce the plot shown in Figure 1.

Figure 1: Plot of +1 order spectrum with matplotlib

[Thumbnail image: A line plot of bin_lo vs counts.]

[Version: full-size]

[Print media version: A line plot of bin_lo vs counts.]

Figure 1: Plot of +1 order spectrum with matplotlib


With Sherpa

Sherpa can also be used to plot a PHA2 spectrum. Sherpa reads all the rows and allows you to specify individual ones for plotting or fitting purposes:

unix% sherpa

sherpa In []: load_pha("acisf00459N004_pha2.fits")
statistical errors were found in file 'acisf00459N004_pha2.fits'
but not used; to use them, re-read with use_errors=True
read background_up into a dataset from file acisf00459N004_pha2.fits
read background_down into a dataset from file acisf00459N004_pha2.fits
Multiple data sets have been input: 1-12

sherpa In []: import matplotlib.pylab as plt
sherpa In []: set_analysis("energy")
sherpa In []: plot("data",4,"data",3)
sherpa In []: plt.savefig("rate.png")

Figure 2 shows the plot of the HEG -1 order (row 3, upper drawing area) and +1 order (row 4, lower drawing area) that is created.

Figure 2: +/-1 order plot in Sherpa: count rate per keV

[Thumbnail image: Line plots of energy (keV) vs counts/s/keV.]

[Version: full-size, PNG]

[Print media version: Line plots of energy (keV) vs counts/s/keV.]

Figure 2: +/-1 order plot in Sherpa: count rate per keV

The HEG -1 order (row 3) is in the upper plot and the HEG +1 order (row 4) is in the lower plot.

To plot the data in CHANNEL vs. COUNTS:

sherpa In []: set_analysis("channel")
sherpa In []: plot("data",4,"data",3)
sherpa In []: plt.savefig("counts.png")

These commands create Figure 3.

Figure 3: +/-1 order plot in Sherpa: counts

[Thumbnail image: Line plots of channel vs counts.]

[Version: full-size, PNG]

[Print media version: Line plots of channel vs counts.]

Figure 3: +/-1 order plot in Sherpa: counts

The HEG -1 order (row 3) is in the upper plot and the HEG +1 order (row 4) is in the lower plot.

sherpa> quit

Displaying ACIS and HRC Extraction Regions

Each pha2 file has a second block, named REGION, which stores the regions used by tgextract to extract the source and background spectra.

There are three regions associated with each order: source, upper background, and lower background. For an ACIS/HETG observation, this gives 36 regions: 12 spectral components (+/- 3, +/- 2, and +/- 1 for HEG and MEG) times 3 regions apiece (source and two backgrounds).

To look at the columns of a REGION block:

unix% dmlist "acisf00459N004_pha2.fits[REGION]" cols

--------------------------------------------------------------------------------
Columns for Table Block REGION
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   SPEC_NUM                          Int2           1:32767              Spectrum number
   2   ROWID                             String[64]                          Source or a background
   3   SHAPE                             String[16]                          Shape of region
   4   TG_LAM               angstrom     Real4          0:      400.0        Dispersion coordinate 
   5   TG_D                 degrees      Real4          -2.0:        2.0     Cross-dispersion coordinate 
   6   R[2]                 (angstrom , degrees) Real4(2)       -Inf:+Inf    Raduis vector for SHAPE
   7   ROTANG               degrees      Real4          -360.0:      360.0   Rotation angle for SHAPE
   8   TG_PART                           Int2           0:9                  Grating part index (HEG=1, MEG=2, LEG=3)
   9   TG_SRCID                          Int2           1:32767              Source identification number
  10   TG_M                              Int2           -62:62               Diffraction order
  11   COMPONENT                         Int2           -                    Component number

ds9 cannot display these regions as they are written in the pha2 file. In order to view them, we need to rename the (TG_LAM,TG_D) columns to (X,Y) so that ds9 knows how to interpret them. We will also need to create images in (TG_LAM,TG_D) coordinates, on which we can display the regions.

The following dmcopy commands create image and region files for the 1st and 3rd orders of the MEG arm:

unix% dmcopy \
      "acisf00459N004_evt2.fits[bin tg_lam=0:30:0.08,tg_d=-0.01:0.01:0.00008][tg_m=-1,1,tg_part=2]" \
      459_order1.fits

unix% dmcopy \
      "acisf00459N004_evt2.fits[bin tg_lam=0:15:0.08,tg_d=-0.01:0.01:0.00008][tg_m=-3,3,tg_part=2]" \
      459_order3.fits 

unix% dmcopy \
      "acisf00459N004_pha2.fits[region][tg_m=1,tg_part=2][cols x=tg_lam,y=tg_d,*]" \
      region_order1.fits 

unix% dmcopy \
      "acisf00459N004_pha2.fits[region][tg_m=3,tg_part=2][cols x=tg_lam,y=tg_d,*]" \
      region_order3.fits
[NOTE]
Copy all blocks?

The above dmcopy commands will only copy the data from the requested blocks. Users who need the [REGION] extension copied from the evt2.fits file should use dmappend as prescribed in the dmcopy opt=all bug page.

In creating the images, the filter includes + and - orders to obtain more events in the image. Since the regions are the same for +/- orders, it is only necessary to copy one (the + orders were used here). The image limits are typical for ACIS/HETG observations, but will need to be adjusted for other configurations.

To display the event files with the regions overlaid:

unix% ds9 -tile 459_order1.fits -region region_order1.fits -cmap a -scale log \
      459_order3.fits -region region_order3.fits -cmap a -scale log 

which produces Figure 4. We can see that all events are contained within at least one extraction region.

Figure 4: ACIS/HETG data with source and background regions overlaid

[Thumbnail image: The images in wavelength coordinates are displayed side-by-side in ds9.]

[Version: full-size]

[Print media version: The images in wavelength coordinates are displayed side-by-side in ds9.]

Figure 4: ACIS/HETG data with source and background regions overlaid

The first order (left) and third order (right) images with extraction regions overlaid.

For HRC/LETG data, a bow-tie extraction region is used. Using similar dmcopy commands as for the ACIS data:

unix% dmcopy \
      "hrcf00460N005_evt2.fits[bin tg_lam=0:210:0.25,tg_d=-2:2:0.0008][tg_m=-1,1,tg_part=3]" \
      hrc_order1_img.fits 

unix% dmcopy \
      "hrcf00460N005_pha2.fits[REGION][tg_m=1,tg_part=3][cols x=tg_lam,y=tg_d,*]" \
      hrc_region_order1.fits  

To display the file and regions:

unix% ds9 hrc_order1_img.fits -region hrc_region_order1.fits -cmap b -scale log

which produces Figure 5.

Figure 5: HRC-S/LETG data with bow-tie extraction region

[Thumbnail image: The image in wavelength coordinates is displayed in ds9.]

[Version: full-size]

[Print media version: The image in wavelength coordinates is displayed in ds9.]

Figure 5: HRC-S/LETG data with bow-tie extraction region

The scale parameters have been adjusted to highlight the source counts along the center of the display. A pixel distribution of 19:404 is used.


History

01 Jun 2004 reviewed for CIAO 3.2: no changes
06 Dec 2005 updated for CIAO 3.3: version numbers
01 Dec 2006 updated for CIAO 3.4: ChIPS and Sherpa versions
24 Jan 2008 updated for CIAO 4.0: updated ChIPS and Sherpa syntax
06 Jun 2008 added "opt=all" to dmcopy commands so all blocks are kept in the grating files
06 Feb 2009 updated for CIAO 4.1: prism was rewritten in GTK, so some cosmetic changes (updated all thread images); images are inline; Python and S-Lang syntax included for ChIPS and Sherpa plotting
14 Jan 2009 updated for CIAO 4.2: ObsID 459 file versions
19 Jul 2010 the S-Lang syntax has been removed from this thread as it is not supported in CIAO 4.2 Sherpa v2.
12 Jan 2011 reviewed for CIAO 4.3: no changes
01 Mar 2012 reviewed for CIAO 4.4: use dmtype2split to split a type II spectrum file before displaying it with ChIPS
03 Dec 2012 Review for CIAO 4.5; updated dmtype2split syntax, need to review crates changes.
14 Jan 2013 Completed CIAO 4.5 review, minor edits only.
26 Nov 2013 Reviewed for CIAO 4.6; no changes.
17 Dec 2014 Review for CIAO 4.7. Minor edits only.
02 Apr 2019 Show how to plot spectrum using matplotlib
02 Dec 2020 Remove dmcopy opt=all due to bug. Link to work dmappend workaround if users need REGION extension.
15 Nov 2021 Remove prism for CIAO 4.14.
14 Jan 2022 Reviewed for CIAO 4.14. No changes.