Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/sky2tdet.html
Jump to: Description · Example · Parameters · Bugs · See Also


AHELP for CIAO 4.16

sky2tdet


Synopsis

Project an image in SKY coordinates to TDET coordinates

Syntax

sky2tdet  infile asphistfile outfile [bin] [geompar] [clobber] [verbose]

Description

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

a. spectrumfile=none

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.

CAVEATS


Example

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]".


Parameters

name type ftype def min max reqd
infile file input       yes
asphistfile file input       yes
outfile file output       yes
bin integer   1 1    
geompar file   geom      
clobber boolean   no      
verbose integer   0 0 5  

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.


Bugs

Caveats

# 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 

Workaround:

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

See Also

calibration
ardlib
psf
psf
tools::aspect
asphist, dither_region
tools::background
acis_bkgrnd_lookup, hrc_bkgrnd_lookup, readout_bkg
tools::composite
combine_grating_spectra, combine_spectra, specextract
tools::coordinates
reproject_image, reproject_image_grid
tools::core
dmextract
tools::region
skyfov
tools::response
acis_fef_lookup, acis_set_ardlib, addresp, dmarfadd, eff2evt, find_mono_energy, fullgarf, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psf_project_ray, rmfimg
tools::statistics
aprates