Skip to the navigation links
Last modified: 10 Jun 2010
Where are the PDFs?

HRC-I Exposure Map and Fluxed Image

CIAO 4.2 Science Threads



Overview

Last Update: 10 Jun 2010 - updated for CALDB 4.3.0: the HRC-I background event files are now included in the CALDB; Background-subtract the image section was added

Synopsis:

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.

To create an exposure map, we will use an 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.

Purpose:

To build an exposure map for an HRC-I observation, create a fluxed image, and find an approximation for the source flux.

Read this thread if:

you are working with an HRC-I observation and would like to create an exposure map for it.

Related Links:




Contents



Get Started

Sample ObsID used: 144 (HRC-I, G21.5-0.9)

File types needed: evt2; dtf1; asol1

Please ensure that you have set up ardlib to use the bad pixel file for your observation before following this thread; see the Setting the Observation-specific Bad Pixel Files thread for more information.

Select a background events file

An HRC-I background events file that has been reprojected to match the data is required for the "background-subtract the image" step. Follow the HRC-I Background Event Files thread to create the background file.

The background event file used in this thread is called 144_reproj_bg.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:

unix% cat $ASCDS_CONTRIB/VERSION.CIAO_scripts
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. Here we decided to block the image by a factor of 32:

unix% dmcopy "hrcf00144N005_evt2.fits[bin x=32,y=32]" 144_img32.fits

This creates an image that is 1024 x 1024 (given that a full resolution HRC-I image is 32767 x 32767).



Background-subtract the Image

The final flux map may contain ring-shaped artifacts due to applying a HRMA vignetting correction to the particle background. Subtracting an estimate for the particle background from the observation before exposure correcting eliminates these artifacts.

Bin the HRC-I background events file by a factor of 32 to make an image that is congruent to the observation data:

unix% dmcopy "144_reproj_bg.fits[bin x=32,y=32]" 144_bg_img32.fits

The dmimgcalc tool is used to subtract the background from the data. The operation (op) parameter is set to use the exposure times to weight the background file:

unix% dmimgcalc 144_img32.fits,144_bg_img32.fits none \
      144_sub_img32.fits \
      op="imgout=img1-((img1_exposure/img2_exposure)*img2)"

The resulting subtracted image is named 144_sub_img32.fits.



Compute Exposure Map

1. Compute the Aspect Histogram

With the aspect offsets file, we can create a binned histogram, detailing the aspect history of the observation.

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

unix% cat pcad_asol1.lis
pcadf084154631N004_asol1.fits

unix% punlearn asphist
unix% pset asphist infile=@pcad_asol1.lis
unix% pset asphist outfile=asphist.fits
unix% pset asphist evtfile="hrcf00144N005_evt2.fits[chip_id=0]"
unix% pset asphist dtffile=hrcf00144_000N005_dtf1.fits
unix% asphist
Aspect Solution List Files (@pcad_asol1.lis): 
Aspect Histogram Output File (asphist.fits): 
Event List Files (hrcf00144N005_evt2.fits): 
Live Time Correction List Files for HRC (hrcf00144_000N005_dtf1.fits): 
# asphist (CIAO 4.2): WARNING: skipping 40 livetime correction records (from time: 84154850.639142 to time: 84154930.589145)

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


2. 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). Since energy is not explicitly resolved in HRC observations, the monoenergy parameter is determined at the discretion of the observer (the default value is 1 keV).

Note that it is not necessary for the instrument map to be congruent with the exposure map. We set the pixelgrid parameter to create a 1024 x 1024 pixel image that covers the entire detector area.

unix% punlearn mkinstmap
unix% pset mkinstmap obsfile="asphist.fits[asphist]"
unix% pset mkinstmap outfile=instmap_1.0kev.fits
unix% pset mkinstmap detsubsys=HRC-I
unix% pset mkinstmap pixelgrid="1:16384:#1024,1:16384:#1024"
unix% pset mkinstmap spectrumfile=NONE
unix% pset mkinstmap monoenergy=1.0
unix% mkinstmap
Output File Name (instmap_1.0kev.fits): 
Energy Spectrum File (see docs) (NONE): 
Energy for mono-chromatic map [keV] (0.1:10) (1): 
Pixel grid specification x0:x1:#nx,y0:y1:#ny (1:16384:#1024,1:16384:#1024): 
Name of fits file + extension with obs info (asphist.fits[asphist]): 
Detector Name (HRC-I): 
Grating for zeroth order ARF (NONE|LETG|HETG) (NONE): 
NONE, or name of ACIS window mask file (NONE): 

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


3. 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 set the xygrid parameter to produce a 1024 x 1024 pixel output map; this corresponds to a bin size of 32 for the sky axes, which was used when creating an image 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 144_sub_img32.fits verbose="1"
Checking binning of image: 144_sub_img32.fits
  Image has 1024 x 1024 pixels
  Pixel size is 32 by 32
  Lower left (0.5,0.5) corner is x,y= 0.5, 0.5
  Upper right (1024.5,1024.5) corner is x,y= 32768.5, 32768.5
  DM filter is:
    x=0.5:32768.5:#1024,y=0.5:32768.5:#1024
  mkexpmap xygrid value is:
    0.5:32768.5:#1024,0.5:32768.5:#1024

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

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_1.0kev.fits
unix% pset mkexpmap outfile=expmap_1.0kev.fits
unix% pset mkexpmap xygrid="0.5:32768.5:#1024,0.5:32768.5:#1024"
unix% pset mkexpmap asphistfile=asphist.fits
unix% pset mkexpmap normalize=no
unix% pset mkexpmap useavgaspect=no
unix% mkexpmap
Aspect Histogram File (asphist.fits): 
Output File Name (expmap_1.0kev.fits): 
Name of Instrument Map (instmap_1.0kev.fits): 
grid specification syntax x0:x1:#nx,x0:x1:ny (0.5:32768.5:#1024,0.5:32768.5:#1024): 
Use Average Aspect Pointing (no): 
Exposure map limits: 0.000000e+00, 6.758052e+06
Writing exposure map to expmap_1.0kev.fits

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

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

Since we set the normalize parameter to 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]; see the help file for mkexpmap for more details on this.



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 may be 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=144_sub_img32.fits
unix% pset dmimgthresh outfile=144_img32_clean.fits
unix% pset dmimgthresh expfile=expmap_1.0kev.fits
unix% pset dmimgthresh cut=1.5%
unix% pset dmimgthresh value=0.0
unix% dmimgthresh
Input dataset/block specification (144_sub_img32.fits): 
Output dataset/block specification (144_img32_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 can be performed in one step with dmimgcalc:

unix% punlearn dmimgcalc
unix% pset dmimgcalc infile=144_img32_clean.fits
unix% pset dmimgcalc infile2=expmap_1.0kev.fits
unix% pset dmimgcalc outfile=144_img32_norm.fits
unix% pset dmimgcalc operation=div
unix% dmimgcalc
Input file #1 (144_img32.fits): 
Input file #2 (expmap_1.0kev.fits): 
output file  (144_img32_norm.fits): 
arithmetic operation (add|sub|mul|div|tst) (div): 
warning: CONTENT has 1 different values.

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 144_img32_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% more flux.reg
# Region file format: CIAO version 1.0
circle(16312.5,16488.5,376)

the flux can be calculated with either dmstat:

unix% dmstat infile="144_img32_norm.fits[sky=region(flux.reg)]" centroid=no
144_img32_norm.fits
    min:        -6.9336494249e-07             @:        ( 16240.5 16208.5 )
    max:        0.00017300095081              @:        ( 16336.5 16496.5 )
   mean:        5.5762085626e-06
  sigma:        1.2986276118e-05
    sum:        0.0023921934734
   good:        429
   null:        147

or dmextract:

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

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

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.



Data Caveat: "rings" in the fluxed image

If the background subtraction step is skipped, the normalized image contains a pattern of rings. Viewing the image with ds9, using color map i8 makes these rings (Figure 3) most evident. The rings are the result of applying the HRMA vignetting correction in the exposure map to the un-vignetted particle background.

[Thumbnail image: The image is displayed in ds9 with color map i8.]

[Version: full-size]

[Print media version: The image is displayed in ds9 with color map i8.]

Figure 3: "Rings" in the fluxed image

The rings are the result of applying the HRMA vignetting correction in the exposure map to the un-vignetted particle background.




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.fits     Aspect Histogram Output File
       evtfile = hrcf00144N005_evt2.fits[chip_id=0]    Event List Files
       dtffile = hrcf00144_000N005_dtf1.fits 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_1.0kev.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                Energy for mono-chromatic map [keV]
#
     pixelgrid = 1:16384:#1024,1:16384:#1024 Pixel grid specification x0:x1:#nx,y0:y1:#ny
       obsfile = asphist.fits[asphist] Name of fits file + extension with obs info
     detsubsys = HRC-I            Detector Name
       grating = NONE             Grating for zeroth order ARF
      maskfile = NONE             NONE, or name of ACIS window mask file
#
       pbkfile =                  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.fits     Aspect Histogram File
       outfile = expmap_1.0kev.fits Output File Name
   instmapfile = instmap_1.0kev.fits Name of Instrument Map
#
        xygrid = 0.5:32768.5:#1024,0.5:32768.5:#1024 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 = 144_img32.fits       Input dataset/block specification
       outfile = 144_img32_clean.fits Output dataset/block specification
      (expfile = expmap_1.0kev.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 = 144_img32_clean.fits       Input file #1
       infile2 = expmap_1.0kev.fits Input file #2
       outfile = 144_img32_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)              
    

History

23 Dec 2004 reviewed for CIAO 3.2: no changes
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
18 Jan 2008 updated for CIAO 4.0: added download get_sky_limits section; directory name changed from expmap_hrc to expmap_hrci; filenames and screen output updated for reprocessed data (version N005 event file, N004 aspect solution)
09 Apr 2008 reordered image links; improved description of rings seen in fluxed image
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 change to flux in screen output
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
05 Feb 2010 updated for CIAO 4.2: linked to the HRC calibration page on how to incorporate a stowed background map to create a better HRC-I fluxed map.
10 Jun 2010 updated for CALDB 4.3.0: the HRC-I background event files are now included in the CALDB; Background-subtract the image section was added

Return to Threads Page: Top | All | Imag

Where are the PDFs?
Last modified: 10 Jun 2010