Last modified: 13 Jan 2022

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

Calculate a Flux for a Position

CIAO 4.16 Science Threads


Overview

Synopsis:

The steps in this thread are performed automatically by the srcflux tool. This thread is retained for those users who want to understand the processing in more detail.

The tool eff2evt calculates the energy flux in ergs/cm2/sec for each input event, taking the quantum efficiency (QE) and effective area (EA) into account. The QE, EA, and flux values are recorded in new columns in the output file.

Run this thread if:

you wish to calculate the energy flux for an ACIS or HRC imaging observation.

eff2evt may also be used on the zeroth-order of grating data. In this case, the tool issues a warning and uses the zeroth-order grating efficiencies for the calculations. It cannot be used on the grating arms because the off-axis position for diffracted events does not correspond to the event position, but to the zeroth order position; therefore, the vignetting correction will be wrong.

Related Links:

  • The Chandra Source Catalog (CSC) - reference fluxes for most sources are available from the CSC with no analysis required. Note that the fluxes in the CSC are calculated for specific models (absorbed power law and blackbody) and with certain assumptions about conversion from counts to flux.

  • srcflux ahelp file

Last Update: 13 Jan 2022 - Review for CIAO 4.14. Updated numbers for CALDB 4.9.6.


Contents


Get Started

Download the sample data: 315 (ACIS-S, NGC 4038/39); 990 (HRC-S, VEGA)

unix% download_chandra_obsid 315,990 
[NOTE]
Early dataset

The data used in this thread was taken very early in the Chandra mission. It was not included in the bulk reprocessing metioned in the Watchout page. The keywords required for analysis with CIAO need to be added by running chandra_repro or r4_header_update.


About the Energy Flux Calculation

The energy flux is calculated as:

FLUX_E = (ENERGY / (QE*EA*DACORR*LIVETIME)) * (eV/erg)

where ENERGY is either a column in the input file (ACIS only) or the supplied monochromatic energy (ACIS or HRC). Remember that the ENERGY column is the scaled, gain-adjusted pulse height channel and represents an estimate of the mean energy of photons in that channel. The conversion factor from eV to erg is 1.60217646e-12.


ACIS Data

Filter the events (optional)

Apply any desired filters to the file before running eff2evt. For this example, only ccd_id=7 (ACIS-S3) is used and an energy range filter is applied:

unix% dmcopy "acisf00315_repro_evt2.fits[energy=300:7000][ccd_id=7]" acis_315_filt7.fits
[IMPORTANT]
Time Filtering

eff2evt uses the per-chip exposure time to compute the FLUX values. Therefore, any filtering on TIME must be done before running eff2evt.


Run eff2evt to calculate the energy flux

The value of the energy parameter controls at what energy the QE and EA are determined. This may be set to a monochromatic value. Most users, however, will want to leave it at the default of "INDEF", which tells eff2evt to use the ENERGY column in the input file to do the lookup for each event.

unix% punlearn eff2evt
unix% eff2evt acis_315_filt7.fits acis_315_flux7.fits

The output file, acis_315_flux7.fits, is a copy of the input file with four additional columns: QE, EA, DACORR, and FLUX.

unix% dmlist acis_315_flux7.fits cols
--------------------------------------------------------------------------------
Columns for Table Block EVENTS
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   time                 s            Real8          60413209.3141160011: 60489714.2918820009 S/C TT corresponding to mid-exposure
   2   ccd_id                            Int2           0:9                  CCD reporting event
   3   node_id                           Int2           0:3                  CCD serial readout amplifier node
   4   expno                             Int4           0:2147483647         Exposure number of CCD frame containing event
   5   chip(chipx,chipy)    pixel        Int2           1:1024               Chip coords
   6   tdet(tdetx,tdety)    pixel        Int2           1:8192               ACIS tiled detector coordinates
   7   det(detx,dety)       pixel        Real4          0.50:     8192.50    ACIS detector coordinates
   8   sky(x,y)             pixel        Real4          0.50:     8192.50    sky coordinates
   9   phas[5,5]            adu          Int2(5x5)      -4096:4095           array of pixel pulse heights
  10   pha                  adu          Int4           0:36855              total pulse height of event
  11   pha_ro               adu          Int4           0:36855              total read-out pulse height of event
  12   energy               eV           Real4          0:  1000000.0        nominal energy of event (eV)
  13   pi                   chan         Int4           1:1024               pulse invariant energy of event
  14   fltgrade                          Int2           0:255                event grade, flight system
  15   grade                             Int2           0:7                  binned event grade
  16   status[4]                         Bit(4)                              event status bits
  17   QE                                Real4          -Inf:+Inf            Detector QE/U
  18   EA                   cm**2        Real4          -Inf:+Inf            Mirror Effective Area
  19   FLUX                 ergs/cm**2/s Real4          -Inf:+Inf            Photon flux
  20   DACORR                            Real4          -Inf:+Inf            Dead area correction factor
 
...

Calculate the photon flux

Since the QE and EA values are recorded in the output file, is it easy to calculate the photon flux in photons/cm2/s. The photon flux is defined as:

FLUX_P = 1 / (QE*EA*DACORR*LIVETIME)

Note that this is not the same as calculating a monchromatic energy flux at 1keV, because each QE and EA value was initially determined by the energy of the corresponding event in the input file.

The tool dmtcalc is used to perform the calculation; the resulting values are stored in the column PFLUX in the output file:

unix% punlearn dmtcalc
unix% dmtcalc acis_315_flux7.fits acis_315_pflux7.fits \
      expression="pflux=1/(QE*EA*DACORR*LIVETIME)"

unix% dmlist "acis_315_pflux7.fits[cols pflux]" data

--------------------------------------------------------------------------------
Data for Table Block EVENTS
--------------------------------------------------------------------------------

ROW    PFLUX
 
     1      3.742128492E-08
     2      2.236818852E-08
     3      3.076114553E-08
     4      2.295607408E-08
     5      1.163548589E-07
     6      5.075101892E-08
     7       2.03346769E-08
     8      1.106968786E-07
     9      3.507076917E-08
     ...

HRC Data

Run eff2evt to calculate the energy flux

When running eff2evt on HRC data, it is necessary to set the value of the energy parameter. This parameter controls at what energy the QE and EA are determined. Since energy is not explicitly resolved in HRC observations, the energy is determined at the discretion of the observer; this thread uses a value of 1.1 keV.

unix% punlearn eff2evt
unix% eff2evt hrcf00990_repro_evt2.fits hrc_990_flux.fits energy=1.1

The output file, hrc_990_flux.fits, is a copy of the input file with three additional columns: QE, EA, DACORR, and FLUX. For HRC, the DACORR is not applicable and the value is always 1.0.

unix% dmlist hrc_990_flux.fits cols
 
--------------------------------------------------------------------------------
Columns for Table Block EVENTS
--------------------------------------------------------------------------------
 
ColNo  Name                 Unit        Type             Range
   1   time                 s            Real8          97387353.0922120064: 97390363.0048280060 Time tag (TT)
   2   chip(chipx,chipy)    pixel        Int2           1:4096               Chip coords
   3   tdet(tdetx,tdety)    pixel        Int4           1:4096               Tdet coords
   4   det(detx,dety)       pixel        Real4          0.50:    65536.50    Det coords
   5   sky(x,y)             pixel        Real4          0.50:    65536.50    Sky coords
   6   pha                  chan         Int2           0:255                Pulse height
   7   pi                   chan         Int2           0:1023               Pulse Invariant
   8   chip_id                           Int2           1:3                  Chip ID
   9   status[4]                         Bit(4)                              Event status bits
  10   QE                                Real4          -Inf:+Inf            Detector QE/U
  11   EA                   cm**2        Real4          -Inf:+Inf            Mirror Effective Area
  12   FLUX                 ergs/cm**2/s Real4          -Inf:+Inf            Photon flux
  13   DACORR                            Real4          -Inf:+Inf            Dead area correction factor
...

Calculate the photon flux

Since the QE and EA values are recorded in the output file, is it easy to calculate the photon flux in photons/cm2/s. The photon flux is defined as:

FLUX_P = 1 / (QE*EA*LIVETIME)

The tool dmtcalc is used to perform the calculation; the resulting values are stored in the column PFLUX in the output file:

unix% punlearn dmtcalc
unix% dmtcalc hrc_990_flux.fits hrc_990_pflux.fits \
      expression="pflux=1/(QE*EA*LIVETIME)"

unix% dmlist "hrc_990_pflux.fits[cols pflux]" data
 
--------------------------------------------------------------------------------
Data for Table Block EVENTS
--------------------------------------------------------------------------------
 
ROW    PFLUX
 

     1      2.278334519E-06
     2      2.280694792E-06
     3       2.28029229E-06
     4      2.279849252E-06
     5      2.278984348E-06
     6      2.316264369E-06
     7      2.280378016E-06
     8      3.840318905E-06
     9      2.290962966E-06
...

Examining the Output

These methods of examining the output are independent of the instrument used (ACIS or HRC).

Sum the flux in a region

Adding the flux values withing a source or background region results in the total flux for that region. This is easy to do with dmstat since the flux is stored as a column in the event file.

An energy filter should be supplied to exclude particle background events at high energies. This was done in the first dmcopy step.

Here the region circle(4191.5,3857.5,158.74268) is used; it is displayed on the data in Figure 1.

Figure 1: Region for summing flux

[Thumbnail image: The ACIS data displayed in ds9 with a circular region defined]

[Version: full-size]

[Print media version: The ACIS data displayed in ds9 with a circular region defined]

Figure 1: Region for summing flux

The region circle(4191.5,3857.5,158.74268) is displayed on the data. The flux values calculated by eff2evt within this circle will be summed.

unix% dmstat "acis_315_flux7.fits[sky=circle(4191.5,3857.5,158.74268)][cols flux]"
FLUX[ergs/cm**2/s]
    min:	3.0131575825e-17 	      @:	6681 
    max:	1.6349624765e-15 	      @:	8244 
   mean:	8.4192410305e-17 
  sigma:	1.50313965e-16 
    sum:	2.5758667933e-12 
   good:	30595 
   null:	0 

The total flux within the region in the 0.3 to 7.0keV energy range - "sum" - is 2.5759e-12 ergs/cm2/s.

All the output values are stored in the dmstat parameter file, dmstat.par. The tool can be run with verbose=0 and any value obtained with pget, e.g. as part of a script:

unix% dmstat "acis_315_flux7.fits[sky=circle(4191.5,3857.5,158.74268)][cols flux]" \
      verbose=0

unix% pget dmstat out_sum
2.5758667933e-12

unix% pget dmstat out_max
1.6349624765e-15

Create an image of the flux

The Data Model has the ability to weight the binning of a file by any column. Weighting by the flux column creates an image where the pixel values are the energy flux per pixel.

The region from the previous example, circle(4191.5,3857.5,158.74268), is used in binning the image.

unix% dmcopy "acis_315_flux7.fits[sky=circle(4191.5,3857.5,158.74268)][bin x,y;flux]" acis_315_flux7.img

The output image, acis_315_flux7.img, is displayed in Figure 2.

Figure 2: Image of the data weighted by flux

[An image of the ACIS data filtered by a circular region where the values are the energy flux per pixel]
[Print media version: An image of the ACIS data filtered by a circular region where the values are the energy flux per pixel]

Figure 2: Image of the data weighted by flux

A region-filtered image of the ACIS data, weighted by the flux column. The pixel values are the energy flux per pixel.

The tool dmstat may be used to calculate statistics of the image. This may also be done from the CIAO analysis menu in ds9: "Analysis → CIAO → Statistics → All (no centroid)".

unix% dmstat acis_315_flux7.img cen-
EVENTS_IMAGE[ergs/cm**2/s]
    min:	0 	      @:	( 4179.25732 3699.25732 )
    max:	4.8260830418e-14 	      @:	( 4238.25732 3963.25732 )
   mean:	3.2537038141e-17 
  sigma:	3.9887514698e-16 
    sum:	2.575469254e-12 
   good:	79155 
   null:	21969 

The output values are stored in the dmstat parameter file, dmstat.par, by both the command-line and interactive ds9 methods. The tool can be run with verbose=0 and any value obtained with pget, e.g. as part of a script:

unix% dmstat acis_315_flux7.img cen- verbose=0

unix% pget dmstat out_sum
2.575469254e-12

unix% pget dmstat out_max
4.8260830418e-14

History

15 Dec 2008 New for CIAO 4.1
30 Mar 2009 added "Read this thread if" section to Synopsis: eff2evt is not appropriate for grating data, not even zeroth orders
05 Feb 2010 updated for CIAO 4.2: ObsID 315 file version; included the parameter block filename in the ACIS eff2evt run to apply the ACIS dead area correction; corresponding changes to output
09 Mar 2010 added a link to the Chandra Source Catalog, which contains reference fluxes for many sources
15 Dec 2010 updated for CIAO 4.3: if grating data is input, eff2evt issues a warning and uses the zeroth-order grating efficiencies for the calculations.
10 Jan 2012 reviewed for CIAO 4.4: updates to screen output, the FLUX_LO/HI/WEIGHTED columns are only created by eff2evt when the rmfimg parameter is set.
03 Dec 2012 Review for CIAO 4.5; added note about energy filter.
26 Nov 2013 Review for CIAO 4.6. Added info about srcflux. Added info about early data and need to run chandra_repro or r4_header_update.
04 Mar 2014 Final review for CIAO 4.6. Updated for new DACORR column and latest calibrations values.
17 Dec 2014 Review for CIAO 4.7. Added a note about TIME filtering.
13 Jan 2022 Review for CIAO 4.14. Updated numbers for CALDB 4.9.6.