Project an image in SKY coordinates to TDET coordinates
sky2tdet infile asphistfile outfile [bin] [geompar] [clobber] [verbose]
`sky2tdet' projects an image for a region of interest in sky(x,y) coordinates to TDET coordinates. The TDET image is appropriate for use as a weight map (WMAP) to be input to the mkwarf and mkacisrmf tools.
The sky image is first mapped back to chip coordinates with the supplied aspect histogram. The chip coordinates are then converted to Tiled Detector coordinates, TDET, which is a non-physical coordinate system that approximates the instrument geometry but retains the true chip coordinates. The resulting TDET pixel values are then the fraction of the sky pixel counts multiplied by the fraction of the aspect duration.
The fraction of the counts in the sky image that map to valid chip pixels is stored in the FRACCTS keyword. This value is use to apply a global normalization to the ARF.
How to weight the WMAP
Ideally, the response function for a given region should be weighted by the fraction of the incident flux from the source that falls within that region. However, this is generally what we are looking to obtain from the observation! We instead know the distribution of counts (i.e. the incident flux after it has passed through the telescope mirror and been absorbed by the detector) across the regions.
Here we discuss two possible approaches to the problem used in the tool mkwarf; the choice of which - if either - is better depends on the characteristics of the data and the science objectives of the analysis.
The simplest approach is to use the raw counts to weight the response (in which the spectrumfile parameter should be set to none). This means that the weights will include the effect of the mirror response and detector QE (including bad pixels) - ie the effective area term - which may bias the spectral fits. One way to minimise this is to pick a restricted energy range over which to make the weight map, one over which the effective area (or, more correctly, the product of the source spectrum and the effective area) does not vary strongly.
b. using the spectrumfile parameter
Another approach is to use the spectrum of the source to correct the detected counts for the effective area of the telescope/instrument combination. Of course, we don't know the source spectrum to use to correct the model. One approach is therefore to use an iterative scheme, where the spectral model used to weight the WMAP is updated after each fit. The spectrumfile parameter is used to supply the an ASCII source model file to use in weighting the WMAP. Note that the energy range of the spectrum should be adjusted to match that used to create the WMAP.
Examples of creating weighted ARFs can be found in the CIAO science threads.
- A source (or aperture) that dithers off the edge of the chip cannot be mapped to TDET coordinates.
- While an image in TDET coordinates could be made directly from an event file, it would have zero counts in bad pixels and zero counts in pixels outside the source region. However, to properly weight the ARF, mkwarf needs to know how much of the source flux fell onto the bad pixels and which bad pixels are actually exposed. Thus the need to take the integrated sky image and de-blur it back to chips coordinates.
- To avoid aliasing effects in the coordinate transform, it is strongly suggested that the sky image be binned at single pixel resolution.
sky2tdet "evt2.fits[sky=circle(4356,4566,20)][bin sky]" asphist-7.fits "tdet.fits[wmap]"
Filter and bin an event file at single-pixel resolution. It gets mapped back to chip coordinates via the aspect histogram (asphist-7.fits). The resulting image is stored in the filename 'tdet.fits'; the image blocked is explicitly named 'wmap'.
If the event list has not been filtered on energy, one may want to include this in the input filename, e.g. "evt2.fits[sky=circle(4356,4566,20),energy=200:7000][bin sky]".
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input)
The input image.
The input 2D image in SKY (X,Y) coordinates. The image should be binned by 1 to avoid aliasing effects in the coordinate transform.
Parameter=asphistfile (file required filetype=input)
The input aspect histogram file.
The aspect histogram file should be made for the same CCD_ID as the sky region covers. If the sky region covers more than one CCD and if the GTIs are very similar, then users can pick one of the CCD_IDs. If the GTIs are very different, sky2tdet should be run on each CCD separately.
Parameter=outfile (file required filetype=output)
The output TDET WMAP file
Contains the reprojected image.
Parameter=bin (integer default=1 min=1)
Binning for chip coordinates
If the WMAP is suitable large (a region size on order of a full chip or more), the mkwarf tool may hit a memory limit when trying to process it.
This parameter rebins the WMAP in chip coordinates to reduce the overall size. The chip edge events are handled more accurately by doing the binning in chip coordinates instead of tdet coordinates.
Note that increasing the binning of the WMAP is recommended only for the cases where mkwarf cannot process the unbinned (bin=1) file. The binning is set to 1 by default to avoid aliasing effects in the coordinate transform.
Parameter=geompar (file default=geom)
The name of the Pixlib Geometry parameter file.
Parameter=clobber (boolean default=no)
Remove output if it exists?
Used to specify whether or not to clobber existing file that has the same name as the specified output file
Parameter=verbose (integer default=0 min=0 max=5)
The tool chatter level
Verbose can be from 0 to 5, generating different amounts of debugging output.
# sky2tdet (CIAO): ERROR: no non-null/0/nan pixels are in the input image
The most likely cause of this error is that the region and energy filter supplied to sky2tdet do not select any events:
unix% dmlist "evt2.fits[sky=region(ciao.reg)][energy=300:2000]" counts 0
Adjust the energy filter for the WMAP to match that of your events. The range of event energies in the region can be found with dmstat:
unix% dmstat "evt2.fits[sky=region(ciao.reg)][cols energy]" energy[eV] min: 2231.7507324 @: 61 max: 7980.6259766 @: 35 mean: 4012.0070413 sigma: 1252.6216735 sum: 429284.75342 good: 107 null: 0
- acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, addresp, aprates, asphist, combine_grating_spectra, combine_spectra, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, readout_bkg, reproject_image, reproject_image_grid, rmfimg, sky2tdet, skyfov, specextract