Skip to the navigation links
Last modified: 12 Jan 2010
Where are the PDFs?

Single Chip ACIS Exposure Map and Fluxed Image Step-by-Step

CIAO 4.2 Science Threads


Last Update: 12 Jan 2010 - updated for CIAO 4.2: calibration update - the ACIS QE contamination model has been upgraded to vN0005.


mkexpmap generates an exposure map which may be used to convert a counts image of a source to an image in flux units. The computed exposure map is essentially an image of the effective area at each sky position, accounting for the effects of dither motion which are especially important near the edges of the detector.

The exposure map is computed from the aspect histogram file - which contains information on the aspect motion during the observation - and an instrument map - which is essentially the product of the detector quantum efficiency and the mirror effective area projected onto the detector surface.


To build an exposure map for a single ACIS chip (ccd_id = 7), create a fluxed image, and find an approximation for the source flux.

Read this thread if:

you are working with an ACIS observation and would like to create an exposure map for one of the chips. If more than one chip is being used, follow the ACIS Exposure Map (Multiple Chips) and Fluxed Image thread instead.

Calibration Updates:

Related Links:


Get Started

Sample ObsID used: 1838 (ACIS-S, G21.5-09)

File types needed: evt2; asol1; msk1; pbk0

In this thread, we assume that all relevant files are in the same working directory.

Please ensure that you have set up ardlib to use the bad pixel file for your observation before following this thread.

In this example, the energy range was restricted from 0.5 keV to 7 keV:

unix% dmcopy "acisf01838N002_evt2.fits[energy=500:7000]" acis_1838_evt2.fits

Download get_sky_limits

This thread uses the get_sky_limits script; for information about the script, consult the help file ("ahelp get_sky_limits"). The script is part of the CIAO Scripts distribution. The CIAO scripts package should be the following version or newer:

17 Apr 2009

Please check that you have at least this version of the scripts package installed before continuing. If you do not have the scripts installed or need to update to a newer version, refer to the Scripts page.

Create An Image

First, we need to create the image which will ultimately be normalized by the exposure map.

1. Check Which Chips Are On

The list of chips used in the observation is stored in the DETNAM keyword of the event file:

unix% dmkeypar acis_1838_evt2.fits DETNAM echo+

In this case, six chips were on for the observation. Using ds9 to display acis_1838_evt2.fits, we know that the source we are interested in is at sky coordinates (called "physical coordinates" in ds9) close to x = 4072, y = 4249. We can use dmcoords to find out which chip the source is on.

In many cases, there will be more than one aspect solution file (pcad_asol1.fits) for an observation. All the files must be input, either as a list or as a stack. Here we use:

unix% cat pcad_asol1.lis

unix% dmcoords acis_1838_evt2.fits asolfile=@pcad_asol1.lis

dmcoords>: sky 4072 4249
(RA,Dec):     18:33:33.594    -10:34:06.34
(RA,Dec):      278.38998      -10.56843 deg
THETA,PHI          1.267'          5.93 deg
(Logical):        4072.00       4249.00
SKY(X,Y):         4072.00       4249.00
DETX,DETY         4250.13       4112.47
CHIP ACIS-S3       370.58        383.72
TDET              4287.58       2085.72
dmcoords>: q

This tells us that the chip we want is ACIS-S3, i.e. ccd_id = 7. A description of the layout of the ACIS focal plane can be found in The Chandra Proposers' Observatory Guide.

2. Bin the Event File

Here we decided to make a full resolution image (blocking by a factor of 1):

unix% cat chip_s3.reg 
# Region file format: CIAO version 1.0

unix% dmcopy "acis_1838_evt2.fits[sky=region(chip_s3.reg)][bin sky=1]" 1838_img_s3.fits 

This FAQ explains several ways of finding the chip boundaries. This creates a full resolution ACIS image (8192 x 8192); this information is used again in the Calculate the Exposure Map step. You may choose to use different binning, but make sure that you change the xygrid appropriately in that step.

Compute Exposure Map

1. Find Peak Energy Of Source

We selected a region around the central source, using ds9, and saved it as obj.reg:

unix% cat obj.reg
# Region file format: CIAO version 1.0

We can use this file to extract a spectrum of the object in energy space and find the peak energy.

First, we use the CIAO tool dmextract to create a histogram of count-rate as a function of energy. Since we are not binning on pi or pha, we set opt=generic, and we use a bin size of 20 eV to improve the signal to noise:

unix% punlearn dmextract
unix% pset dmextract infile="acis_1838_evt2.fits[sky=region(obj.reg)][bin energy=500:7000:20]"
unix% pset dmextract outfile=obj_1838_histogram_energy.fits
unix% pset dmextract opt=generic
unix% dmextract 
Input event file  (acis_1838_evt2.fits[sky=region(obj.reg)][bin energy=500:7000:20]): 
Enter output file name (obj_1838_histogram_energy.fits): 

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

The dmstat tool is used to find the maximum count rate from the histogram, followed by dmlist to locate the corresponding energy:

unix% dmstat "obj_1838_histogram_energy.fits[cols count_rate]"
    min:        0             @:        3
    max:        0.015920916107        @:        62
   mean:        0.0055332286649
  sigma:        0.003904907356
    sum:        1.7982993161
   good:        325
   null:        0

unix% dmlist "obj_1838_histogram_energy.fits[count_rate > 0.015][cols energy,count_rate]" data,clean
#  ENERGY               COUNT_RATE
               1730.0     0.01592091610690
               1750.0     0.01579354877805
               1770.0     0.01592091610690
               1810.0     0.01566618144919
               1830.0     0.01579354877805
               1850.0     0.01515671213377

For this dataset, the peak of the measured spectrum is ~1.7 keV.

2. Compute The Aspect Histogram

With the aspect solution file we can create a binned histogram for the chip that was on, detailing the aspect history of the observation. The same aspect solution list file, pcad_asol1.lis, is used:

unix% cat pcad_asol1.lis

unix% punlearn asphist
unix% pset asphist infile=@pcad_asol1.lis
unix% pset asphist outfile=asphist_7.fits
unix% pset asphist evtfile="acis_1838_evt2.fits[ccd_id=7]"
unix% asphist
Aspect Solution List Files (@pcad_asol1.lis): 
Aspect Histogram Output File (asphist_7.fits[ccd_id=7]): 
Event List Files (acis_1838_evt2.fits): 

There are several things to notice here:

  • The ccd_id value may be different for your dataset.

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

3. Calculate the Instrument Map

Since the mirror effective area is used to create the instrument map, and that area is energy dependent, it is necessary to decide at what energy to perform the calculation (or whether to use a spectrum as weights). In this example we are going to assume a monoenergetic distribution of source photons of 1.7 keV (monoenergy parameter). The Calculating Spectral Weights for mkinstmap thread shows how to create a weighted instrument map using mkinstmap.

Note that it is not necessary for the instrument map to be congruent with the exposure map; the instrument map should describe the chip with full resolution.

unix% punlearn mkinstmap
unix% pset mkinstmap obsfile="asphist_7.fits[asphist]"
unix% pset mkinstmap outfile=instmap_7.fits
unix% pset mkinstmap maskfile=acisf01838_000N002_msk1.fits
unix% pset mkinstmap pbkfile=acisf084245776N002_pbk0.fits 
unix% pset mkinstmap dafile=CALDB
unix% pset mkinstmap detsubsys=ACIS-7
unix% pset mkinstmap pixelgrid="1:1024:#1024,1:1024:#1024"
unix% pset mkinstmap spectrumfile=NONE
unix% pset mkinstmap monoenergy=1.7

unix% mkinstmap
Output File Name (instmap_7.fits): 
Energy Spectrum File (see docs) (NONE): 
Energy for mono-chromatic map [keV] (0.1:10) (1.7): 
Pixel grid specification x0:x1:#nx,y0:y1:#ny (1:1024:#1024,1:1024:#1024): 
Name of fits file + extension with obs info (asphist_7.fits[asphist]): 
Detector Name (ACIS-7): 
Grating for zeroth order ARF (NONE|LETG|HETG) (NONE): 
NONE, or name of ACIS window mask file (acisf01838_000N002_msk1.fits):
NONE, or the name of the parameter block file (acisf084245776N002_pbk0.fits): 

Including the maskfile parameter is particularly important if you are interested in having an accurate exposure map at the very edge of a CCD, subarray or window. The pixelgrid paramter should not be changed for the case of a subarray or window; the mask file will account for the detector range being different. For more information, see the dictionary entry on mask files.

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

4. Calculate the Exposure Map

Now we use mkexpmap and the aspect information stored in the histogram to project the instrument map onto the sky. We need to set the xygrid parameter to produce an exposure map that is the same size as the image created from the event list. The get_sky_limits script can be used to easily calculate this information from the existing image:

unix% get_sky_limits 1838_img_s3.fits verbose="1"
Checking binning of image: 1838_img_s3.fits
  Image has 1080 x 1080 pixels
  Pixel size is 1 by 1
   Lower left (0.5,0.5) corner is x,y= 3643.1, 3853.4
  Upper right (1080.5,1080.5) corner is x,y= 4723.1, 4933.4
  DM filter is:
  mkexpmap xygrid value is:

You can then set the xygrid parameter using the information provided by the script, either manually or via

unix% pset mkexpmap xygrid=")get_sky_limits.xygrid"

(if the latter, do not run get_sky_limits again until after running mkexmap).

Note: If you are computing a low-resolution exposure map and speed is more important than accuracy, set useavgaspect=yes. In doing so, only the average aspect pointing will be used to derive the exposure map; otherwise all points in the aspect histogram will be used. The time required to compute the exposure map is proportional to the number of bins in the aspect histogram; if the aspect histogram contains 100 bins, then the use of this option reduces the run time by a factor of 100, approximately (you may also want to set verbose to 2, since this causes mkexpmap to output percentage-completed information). Using the full aspect solution will help accurately account for chip edges, bad pixels, etc.

unix% punlearn mkexpmap
unix% pset mkexpmap instmapfile=instmap_7.fits
unix% pset mkexpmap outfile=expmap_7.fits
unix% pset mkexpmap xygrid="3643.1:4723.1:#1080,3853.4:4933.4:#1080"
unix% pset mkexpmap asphistfile=asphist_7.fits
unix% pset mkexpmap useavgaspect=no
unix% pset mkexpmap normalize=no

unix% mkexpmap
Aspect Histogram File (asphist_7.fits): 
Output File Name (expmap_7.fits): 
Name of Instrument Map (instmap_7.fits): 
grid specification syntax x0:x1:#nx,x0:x1:ny (3643.1:4723.1:#1080,3853.4:4933.4:#1080): 
Use Average Aspect Pointing (no): 
Exposure map limits: 0.000000e+00, 4.986713e+06
Writing exposure map to expmap_7.fits

The exposure map may be displayed in ds9 (Figure 1).

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

Since we set the normalize parameter = no, the exposure map has units of [cm2*s*counts/photon]. This allows us to simply divide the image by the exposure map to derive an image in units of flux [photons/cm2/s/pixel]. If the setting had been left as yes (the default), the units of the exposure map would be [cm2*counts/photon]. Please see the help file for mkexpmap for more details on this.

[Thumbnail image: The exposure map of the chip shows several bad columns.]

[Version: full-size]

[Print media version: The exposure map of the chip shows several bad columns.]

Figure 1: Exposure map for the ACIS-S3 chip

The almost-horizontal stripes are due to bad columns in the instrument map.

Normalize the Image by the Exposure Map

The strongly variable exposure near the edge of a dithered field may produce "hot" pixels when divided into an image. While technically proper, these hot pixels can be an eyesore, drawing attention to a noisy, uninteresting portion of the image. The dmimgthresh tool is used to make a "threshold cut" before dividing the image by the exposure map, thus removing the hot pixels:

unix% punlearn dmimgthresh
unix% pset dmimgthresh infile=1838_img_s3.fits
unix% pset dmimgthresh outfile=1838_img_s3_clean.fits
unix% pset dmimgthresh expfile=expmap_7.fits
unix% pset dmimgthresh cut=1.5%
unix% pset dmimgthresh value=0.0
unix% dmimgthresh
Input dataset/block specification (1838_img_s3.fits): 
Output dataset/block specification (1838_img_s3_clean.fits): 

Here we set our threshold at 1.5% of the maximum value of the exposure map. All image pixels with values of exposure less than this value will be set to 0.0 in the output file. You may want to adjust these values for your own observation.

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

The exposure map is in units of [cm2*s*counts/photon] since it was created by projecting the instrument map (in [cm2*counts/photon]) onto the tangent plane of the observation. To create an image in units of [photon/cm2/s/pixel], we simply need to divide by the exposure map. This is done by the tool dmimgcalc.

unix% punlearn dmimgcalc
unix% pset dmimgcalc infile=1838_img_s3_clean.fits
unix% pset dmimgcalc infile2=expmap_7.fits
unix% pset dmimgcalc outfile=1838_img_s3_norm.fits
unix% pset dmimgcalc operation=div
unix% dmimgcalc
Input file #1 (1838_img_s3.fits): 
Input file #2 (expmap_7.fits): 
output file  (1838_img_s3_norm.fits): 
arithmetic operation (div): 
warning: CONTENT has 1 different values.
warning: DETNAM has different value...Merged...

The messages are related to how the tool merges the header information in the input files. The merging_rules ahelp file explains the rules and how they affect the output file header.

The units of 1838_img_s3_norm.fits (Figure 2) are [photon/cm2/s/pixel].

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

Calculate the Source Flux

Since the units of the fluxed image are [photon/cm2/s/pixel], adding up the pixel values around a source results in the source flux in [photon/cm2/s]. Note that this flux is an approximation - as discussed in An Introduction to Exposure Maps (PS, 12pp) - since a spectral shape was assumed when using mkinstmap (in this example, a monochromatic source).

Using the source region "flux.reg":

unix% cat flux.reg
# Region file format: CIAO version 1.0

the flux can be calculated with either dmstat:

unix% punlearn dmstat
unix% dmstat infile="1838_img_s3_norm.fits[sky=region(flux.reg)]" centroid=no
    min:	0 	      @:	( 4061.6402575 4138.9302575 )
    max:	1.4912709958e-05 	      @:	( 4072.6402575 4246.9302575 )
   mean:	1.2102792884e-07 
  sigma:	4.0614779755e-07 
    sum:	0.0047698317035 
   good:	39411 
   null:	11214 

or dmextract:

unix% dmextract infile="1838_img_s3_norm.fits[bin sky=@flux.reg]" outfile="source_flux.fits"

unix% dmlist source_flux.fits"[cols COUNTS]" data
Data for Table Block HISTOGRAM


     1     0.00476983170347

Since the input to dmextract was a fluxed image, not an event list, the COUNTS column actually reports the total flux (in [photon/cm2/s]) for the source region. While slightly more involved, the dmextract method can be used on multiple sources in a single command, and the results are conveniently stored in a table.

To compute robust source intensity quantities (net counts, source rate, photon flux, energy flux) and the related confidence intervals, use the aprates tool. The Compute Net Counts, Rate, or Flux for Point Sources thread shows how to run aprates.

If you are working with event lists, the eff2evt tool can be used to compute the approximate flux, and calculate the QE and Effective Area for sources. The Calculate the Flux for a Position thread describes how to use this tool.

Analysis Caveats

Users should be cautious about analyzing the data for sources near the edges of the ACIS CCDs.

  1. For X-rays passing through the mirrors, the very bottom of each CCD is obscured by the frame store. As a result, some of the events in rows with CHIPY <= 8 are not detected. (The set of rows affected varies from CCD to CCD.) Since the CIAO tools do not compensate for this effect, the ARFs and exposure maps for sources in these regions may be inaccurate.

  2. For sources within about thirty-two pixels of any edge of a CCD, the source may be dithered off the CCD during part of an observation. The aspect histogram, which is used to create ARFs and exposure maps, is designed to compensate for this effect.

  3. An ARF calculated at the edge of a chip will not be accurate. The response tools for spectral extraction (specifically the ARF) assume that 100% of the PSF is enclosed - i.e. on the chip - all the time, which may not be the case. The amount of error introduced depends on how close the source is to the edge, the morphology of the source, and the characteristics of the PSF, which depends on the source spectrum.

  4. A contaminant has accumulated on the optical-blocking filters of the ACIS detectors, as described in the ACIS QE Contamination why topic. Since there is a gradient in the temperature across the filters (the edges are colder), there is a gradient in the amount of material on the filters. (The contaminant is thicker at the edges.) Within about 100 pixels of the outer edges of the ACIS-I and ACIS-S arrays, the gradient is relatively steep. Therefore, the effective low-energy (' 1 keV) detection efficiency may vary within the dither pattern in this region. The ARF and instrument map tools are designed to read a calibration file which describes this spatial dependence.

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

# DMEXTRACT -- extract columns or counts from an event list
        infile = acis_1838_evt2.fits[sky=region(obj.reg)][bin energy=300:10000:20] Input event file 
       outfile = obj_1838_histogram_energy.fits Enter output file name
          (bkg = )                Background region file or fixed background (counts/pixel/s) subtraction
        (error = gaussian)        Method for error determination(poisson|gaussian|<variance file>)
     (bkgerror = gaussian)        Method for background error determination(poisson|gaussian|<variance file>)
      (bkgnorm = 1.0)             Background normalization
          (exp = )                Exposure map image file
       (bkgexp = )                Background exposure map image file
      (sys_err = 0)               Fixed systematic error value for SYS_ERR keyword
          (opt = generic)         Output file type: pha1 
     (defaults = ${ASCDS_CALIB}/cxo.mdb -> /soft/ciao-4.0/data/cxo.mdb) Instrument defaults file
         (wmap = )                WMAP filter/binning (e.g. det=8 or default)
      (clobber = no)              OK to overwrite existing output file(s)?
      (verbose = 0)               Verbosity level
         (mode = ql)              

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

#       Parameter file for the ASPECT HISTOGRAM Tool
        infile = @pcad_asol1.lis  Aspect Solution List Files
       outfile = asphist_7.fits   Aspect Histogram Output File
       evtfile = acis_1838_evt2.fits[ccd_id=7]   Event List Files
       dtffile =                  Live Time Correction List Files for HRC
      (geompar = geom)            Parameter file for Pixlib Geometry files
       (res_xy = 0.5)             Aspect Resolution x and y in arcsec
     (res_roll = 600.)            Aspect Resolution roll in arcsec
      (max_bin = 10000.)          Maximal number of bins
      (clobber = no)              Clobber output
      (verbose = 0)               Verbose
         (mode = ql)              

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

       outfile = instmap_7.fits Output File Name
# Energy Band Info
# Currently, this file is a simple ascii file with two columns
  spectrumfile = NONE             Energy Spectrum File (see docs)
    monoenergy = 1.7              Energy for mono-chromatic map [keV]
     pixelgrid = 1:1024:#1024,1:1024:#1024 Pixel grid specification x0:x1:#nx,y0:y1:#ny
       obsfile = asphist_7.fits[asphist] Name of fits file + extension with obs info
     detsubsys = ACIS-7           Detector Name
       grating = NONE             Grating for zeroth order ARF
      maskfile = acisf01838_000N002_msk1.fits NONE, or name of ACIS window mask file
       pbkfile = acisf084245776N002_pbk0.fits NONE, or the name of the parameter block file
       (mirror = HRMA)            Mirror Name
       (dafile = CALDB)           NONE, CALDB, or name of ACIS dead-area calibration file
(ardlibparfile = ardlib.par)      name of ardlib parameter file
      (geompar = geom)            Parameter file for Pixlib Geometry files
      (verbose = 0)               Verbosity
      (clobber = no)              Overwrite existing files?
         (mode = ql)              Enter mode for parameter file.

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

   asphistfile = asphist_7.fits   Aspect Histogram File
       outfile = expmap_7.fits Output File Name
   instmapfile = instmap_7.fits Name of Instrument Map
        xygrid = 3643.1:4723.1:#1080,3853.4:4933.4:#1080 grid specification syntax x0:x1:#nx,x0:x1:ny
  useavgaspect = no               Use Average Aspect Pointing
#  Aspect Histogram Parameters
#  If UseAvgAspect is set to yes, then only the average pointing derived from
#  the many pointings in the aspect histogram will be used.
#asphistfile,f,a,"../data/aciss_asphist.fits",,,"Aspect Histogram File"
    (normalize = no)              Normalize exposure map by exposure time
      (geompar = geom)            Parameter file for Pixlib Geometry files
      (verbose = 0)               Verbosity
      (clobber = no)              Overwrite existing files?
         (mode = ql)              Enter mode for parameter file.

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

        infile = 1838_img_s3.fits      Input dataset/block specification
       outfile = 1838_img_s3_clean.fits Output dataset/block specification
      (expfile = expmap_7.fits) Exposure map file
          (cut = 1.5%)            Threshold value
        (value = 0)               Replacement value
      (verbose = 0)               Debug Level(0-5)
      (clobber = no)              Clobber existing file
         (mode = ql)              

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

# parameter file for dmimgcalc
        infile = 1838_img_s3_clean.fits      Input file #1
       infile2 = expmap_7.fits Input file #2
       outfile = 1838_img_s3_norm.fits output file 
     operation = div              arithmetic operation
       (weight = 1)               weight for first image
      (weight2 = 1)               weight for second image
    (lookupTab = ${ASCDS_CALIB}/dmmerge_header_lookup.txt -> /soft/ciao/data/dmmerge_header_lookup.txt) lookup table
      (clobber = no)              delete old output
      (verbose = 0)               output verbosity
         (mode = ql)              


23 Dec 2004 updated for CIAO 3.2: minor changes to parameter files, added Caveats section; include dmcoords asolfile parameter
23 Jun 2005 CIAO 3.2.2 patch: change to asphist parameter file
19 Dec 2005 updated for CIAO 3.3: default value of dmextract error and bkgerror parameters is "gaussian"; updated syntax for asphist (GTI filter is associated with the event file rather than the aspect solution); corresponding changes to screen output
24 May 2006 changed "det" abbreviation to full parameter name ("detsubsys") in mkinstmap call
01 Dec 2006 updated for CIAO 3.4: CIAO version in warning; parameter file update for mkinstmap
06 Mar 2007 added ACIS dead area correction section and example of setting the pbkfile and dafile parameters
18 Jan 2008 updated for CIAO 4.0: ACIS QE contamination link added to "Related Links" section; apply the ACIS dead area correction in the mkinstmap step (application of the dead area correction is turned on by default), updated screen output to match; added download get_sky_limits section; filenames and screen output updated for reprocessed data (version N002 files); removed outdated calibration updates
15 May 2008 changed energy filter to 0.5 to 7 keV (500:7000)
24 Oct 2008 get_sky_limits v1.13 (fixes a rare segmentation fault and adds the pixel size in sky coordinates to the screen output.)
03 Feb 2009 updated for CIAO 4.1: images are inline; minor update to flux value in screen output; input data must have a CTI_APP keyword
13 Feb 2009 run dmimgthresh before dmimgcalc in Normalize the Image by the Exposure Map section
16 Mar 2009 added link to aprates thread in Calculate the Source Flux section, removed listing of ERR_COUNTS column
06 May 2009 check the version of the CIAO scripts package instead of the individual script
03 Aug 2009 Added a link to the Calculating Spectral Weights for mkinstmap thread in the Calculate the Instrument Map step, and a link to the Calculate the Flux for a Position thread in the Calculate the Source Flux section.
12 Jan 2010 updated for CIAO 4.2: calibration update - the ACIS QE contamination model has been upgraded to vN0005.

Return to Threads Page: Top | All | Imag

Where are the PDFs?
Last modified: 12 Jan 2010