NAME

USAGE

DESCRIPTION

The xaexpmap task creates an attitude histogram and either an exposure map, containing an integrated exposure time for each pixel (with 'outmaptype=EXPOSURE'), or a flat field image (with 'outmaptype=EFFICIENCY'). In the latter, effects such as detector quantum efficiency, filter transmission, and telescope vignetting are included. The option 'outmaptype=EXPOSURE' is needed for the xaarfgen task, because this option creates additional extensions that contain pixel partial exposure information for each attitude bin. The 'outmaptype=EFFICIENCY' option is more appropriate for correcting images for detector and exposure time effects.

For both 'outmaptype' modes, the task requires an EHK file ('ehkfile') and a GTI file ('gtifile') as input. The EHK file contains orbital and attitude information. The GTI file is the same as that used to screen the event file (these GTI are typically in the second extension of the event data file). In addition, two files, the bad image file ('badimgfile') and the pixel GTI file ('pixgtifile') may be optionally input. The task reads the input EHK file and calculates a residual of the satellite attitude relative to the mean optical axis for each time stamp. Then it determines a time interval for each off-axis wedge for which the size may be set by the parameters 'delta' and 'numphi'. When 'delta=A' and 'numphi=B' ("A" is a real number and "B" an integer), the off-axis wedges are populated as follows. First, the region in the sky centered on the optical axis is divided into a central circle and outer annuli with radii of A*(n+1) arcmin, where n=0 for the central circle, n=1,2,3.. for the subsequent annuli. The innermost and outermost radii over all of the annuli are equal to the minimum and maximum off-axis angle respectively, so that the number of annuli does not need to be specified. The innermost annulus (n=1) is divided into B wedges. Similarly, the n-th annulus is divided into B*n wedges.

If 'outmaptype=EXPOSURE', the output file contains an exposure map image in the primary extension (where each pixel contains the net exposure time in seconds) and an off-axis histogram table in the first extension. This table contains information such as the average attitude and exposure time of each off-axis wedge. The following extensions (from the second to the last) contain pixel lists for each attitude histogram bin (or off-axis wedge), in which each pixel that had less than the full exposure time for that bin has its coordinates and fractional exposure time listed.

The output exposure map image may be in either DET, FOC, or SKY coordinates, set by the parameter 'stopsys'. If 'stopsys=SKY', the task uses the attitude information in the EHK file for the coordinate transformation.

If 'outmaptype=EFFICIENCY', the output file contains a so-called flat field image in the primary extension, in which each pixel has a dimensionless efficiency value between 0 and 1. The image accounts for the smearing due to attitude variations, by means of the parameters 'delta' and 'numphi'. In this flat-field mode, the task reads CalDB files set by the parameters 'qefile', 'vigfile', 'contamifile', 'obffile', 'fwfile', and 'gvfile' (the last three are not needed for Xtend), and multiplies all the efficiencies at the energy or energy range specified by the parameters 'specmode' and 'energy' (see below) to calculate the flat field image. Each of the efficiency components may be turned off by setting the parameter to NONE (e.g., 'vigfile=NONE' means vignetting is not taken into account). There are two ways to set the energy or energy range for which the efficiencies are used. When 'specmode=MONO', the parameter 'energy' should be a single value and the efficiency at this energy is read from the CalDB files. When 'specmode=SPEC', an input spectrum is used to calculate efficiencies weighted by the spectrum over a specified energy range. The 'energy' parameter indicates the minimum and maximum of the desired energy range (two values separated by a comma, e.g., 'energy=1.0,5.0'). The name and format of the spectrum file must be specified by the parameters 'specfile' and 'specform', respectively.

Note that flat-fielding is only valid for telescopes that have a point spread function (PSF) that is smaller or comparable in size to one pixel in the image. This is not the case for XRISM. Flat-fielding does not correct for the extended spatial structure of the XRISM PSF. The flat-fielding functionality of xaexpmap is provided as an exploratory tool, whereas a more accurate approach would be to construct models of the intrinsic spatial distribution in the image and use raytracing to compare simulated images with the data, in an iterative process. Further, the vignetting CalDB file is based on emprical fits to telescope ground calibration data at a few discrete energies, in the range 1.5 to 17.5 keV, and the fits have systematic deviations from the data. For Resolve, the vignetting functions agree with the ground data within 5% at all energies in the 1.5-11 keV range, and within +/-9 arcmin of the Resolve optical axis. For Xtend, the fits are good to better than 5% up to 8 keV, within +/-10 arcmin of the Xtend optical axis. However, above 9.4 keV, the deviation can exceed 25%. Outside of the +/-15 arcmin range, the deviation between data and model is at least 10% for all the energies used, and is as much as 82% at 11 keV.

The optional bad image file ('badimgfile') is a FITS image containing the following flag values for each pixel: 0: good pixels, 1: calibration source regions, 2: bad pixels and columns, and -1 (or NULL) indicates a position that is either out of the detector or in a region of area discrimination (non-active areas of the CCD). For Xtend, the bad image file is output from the xtdflagpix task ('outbadimg' parameter). If 'badimgfile=NONE', the active pixel location is found from the input 'instmap' from CalDB. However, the CalDB file does not contain the bad/hot pixel or calibration source location, and distinguishes only between inside and outside of the detector.

The optional pixel GTI file ('pixgtifile') contains the pixel location in DET coordinates with START and STOP times for each dead time interval (e.g., the pixel is "bad" between START and STOP). This file is needed to account for the time-dependent bad pixels (e.g., flickering pixels for Xtend).

In the default mode, the calibration source regions (for Xtend) are masked out. However, these regions may be regarded as good pixels by setting 'maskcalsrc=no'.

PARAMETERS

ehkfile [filename]

Name of input EHK file.

gtifile [filename]

Name of input GTI file.

instrume = XTEND [string XTEND|RESOLVE]

Name of the instrument.

badimgfile [filename NONE|file name]

Name of input bad pixel image file. This file should contain an image in the primary extension with the following flag values: 0: good pixels, 1: calibration source regions, 2: bad pixels and columns, and -1 (or NULL), which indicates a position that is either out of the detector or in a region of area discrimination.

pixgtifile [filename]

Name of input pixel GTI list. This file contains a binary table with columns of START, STOP, DETX, and DETY values, indicating the duration and location of each partial bad pixel.

outfile [filename]

Name of output file.

outmaptype = EXPOSURE [string EXPOSURE|EFFICIENCY]

Type of the output map.

delta = 0.5 [double]

Radial increment [arcmin] for the annular grid for which the attitude histogram will be calculated. The annuli are centered on the optical axis (off-axis angle = 0), and the central circle has a radius equal to 'delta'. To force the attitude histogram to have a single bin, simply set the parameter 'delta' to a value that is much larger than any expected attitude variation during an observation.

numphi = 4 [integer]

Number of azimuth (phi) bins in the first annular region over which attitude histogram bins will be calculated (i.e., this annular region lies between 'delta' and 2*'delta' arcmin from the center of the annuli). The zeroth annular region is a full circle of radius 'delta', and the nth annular region has an outer radius of (n+1)*'delta', and numphi*n azimuthal bins.

(stopsys = SKY) [string DET|FOC|SKY]

Output coordinate system for the exposure map image.

(instmap = CALDB) [filename CALDB|file name]

Name of input instrument map file. If the parameter is set to CALDB, the file is read from the calibration database. This file is required to execute the task.

(qefile = CALDB) [filename CALDB|NONE|file name]

Name of input quantum efficiency file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE' because it is only needed to create a flat-field image.

(contamifile = CALDB) [filename CALDB|NONE|file name]

Name of input contamination file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE' because it is only needed to create a flat-field image.

(vigfile = CALDB) [filename CALDB|NONE|file name]

Name of input vignetting coefficient file. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE' because it is only needed to create a flat-field image.

(obffile = CALDB) [filename CALDB|NONE|file name]

Name of input optical blocking filter file for Resolve. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE' or 'instrume' is not Resolve because it is only needed to create a flat-field image.

(fwfile = CALDB) [filename CALDB|NONE|file name]

Name of input filter wheel file for Resolve. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE' or 'instrume' is not Resolve because it is only needed to create a flat-field image.

(gvfile = CALDB) [filename CALDB|NONE|file name]

Name of input gate valve file for Resolve. If the parameter is set to CALDB, the file is read from the calibration database. If the parameter is set to NONE, the task does not use this calibration information. This parameter is ignored when 'outmaptype=EXPOSURE' or 'instrume' is not Resolve because it is only needed to create a flat-field image.

(maskcalsrc = yes) [boolean yes|no]

If this parameter is set to yes, calibration source regions in Xtend are regarded as bad pixels and excluded from the output exposure map. This parameter is ignored when 'badimgfile=NONE'.

(fwtype = FILE) [string FILE|OPEN|FE55|BE|ND|POLY]

Filter wheel type for Resolve. This parameter is ignored when 'outmaptype=EXPOSURE' or 'instrume' is not Resolve. If 'fwtype=FILE', the filter wheel type will be taken from the value of the keyword FILTER, in the header of the input 'gtifile'.

(specmode = MONO) [string MONO|SPEC]

Distribution of input energies: monochromatic energy (MONO), or a range of energies (SPEC) weighted by the spectrum in 'specfile'. This parameter is only relevant for creating flat-field images (outmaptype=EFFICIENCY).

(specfile) [filename]

Name of input spectrum file. This parameter is ignored if 'specmode=MONO', and is only relevant for creating flat-field images (outmaptype=EFFICIENCY).

(specform = FITS) [string FITS|ASCII]

Format of the input spectrum file. This parameter is ignored if 'specmode=MONO', and is only relevant for creating flat-field images (outmaptype=EFFICIENCY). If 'specform=ASCII', the spectrum is an ASCII file with three columns: column 1 is the energy bin center (any units), column 2 is the flux, proportional to photons per unit energy, and column 3 is half of the energy bin width, in the same units as column 1. If 'specform=FITS' the spectrum is a FITS file that contains columns of counts versus channel, and the column names are required to be COUNTS and CHANNEL, respectively.

(energy = 6.0) [string]

An energy value [keV] or an energy range for the spectrum from which a flux-weighted efficiency is calculated. When 'specmode' is set to MONO, this parameter should be a single value (e.g., 'energy=6.0'). When 'specmode' is set to SPEC, this parameter should be two values separated by a comma (e.g., 'energy=1.0,5.0') to specify the input energy range. This parameter is only relevant for creating flat-field images (outmaptype=EFFICIENCY).

(evperchan = DEFAULT) [string]

Energy [eV] per channel of the input spectrum file. This parameter is ignored if 'specmode=MONO', and is only relevant for creating flat-field images (outmaptype=EFFICIENCY).. If this parameter is set to DEFAULT and 'instrume=XTEND', a value of 6.0 eV/channel is assumed so that the value matches a standard PHA file of Xtend. Similarly, if this parameter is set to DEFAULT and 'instrume=Resolve', a value of 0.5 eV/channel is assumed.

(abund = 1) [string]

Relative abundances of contaminants modifier. This parameter is only relevant for creating flat-field images (outmaptype=EFFICIENCY). Either several values, or a single value can be specified in the string 'abund'. If there is more than one value, the number of values must be equal to the number of contaminant components in the contamination CalDB file, and each value of the abundance modifier multiplies the abundance of the corresponding component, in the order that the component columns appear in the contamination file. If there is only one numerical value in the string 'abund', then that single value multiplies the abundances of all of the contaminant materials in the calibration file.

(cols = 0) [string]

Additional column densities for contaminants [1E18 cm^{-2}]. This parameter is only relevant for creating flat-field images (outmaptype=EFFICIENCY). The column densities of all of the contaminant materials in the calibration file are modified by adding values from this parameter to the value in contamifile. The number of numerical values in the parameter string must be the same as the number of values in the string for the 'abund' parameter. If there is only one value, that value is applied to all of the contaminant components.

(covfac = 1) [string]

Partial covering modifier for contaminant materials. This parameter is only relevant for creating flat-field images (outmaptype=EFFICIENCY). The partial covering factor of all of the contaminant materials in the calibration file are modified by multiplying them by values from this parameter. The number of numerical values in the parameter string must be the same as the number of values in the string for the 'abund' parameter. If there is only one value, that value is applied to all of the contaminant components.

(buffer = -1) [integer -1|0|N]

Rows to buffer (-1=auto, 0=none, N>0=numrows).

(clobber = no) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 1) [integer 0|1|2|3]

Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string DEFAULT|NONE|file name]

Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records tool parameters in HISTORY.

EXAMPLES

1. Create an exposure map for XRISM Resolve observation 100050020 with an off-axis bin size of 0.5 arcmin. No pixel GTI file is input. Treat pixels in the calibration source region as bad pixels.

   xaexpmap ehkfile=xa100050020.ehk gtifile=xa100050020rsl_p0px1010_cl.evt[GTI] instrume=Resolve badimgfile=NONE \
      pixgtifile=NONE outfile=outexpmap.fits outmaptype=EXPOSURE delta=0.5 numphi=4 maskcalsrc=yes

2. Create an efficiency map for XRISM Xtend observation 100050020 with an off-axis bin size of 1.0 arcmin. A flickering pixel file is input as a pixel GTI. A bad image file output from xtdflagpix is used as the input 'badimgfile'. Do not treat pixels in the calibration source region as bad pixels.

   xaexpmap ehkfile=xa100050020.ehk gtifile=xa100050020xtd_p0100004b0_cl.evt[GTI] instrume=XTEND \
       badimgfile=xa100050020_badpix_img.fits pixgtifile=xa100050020xtd_a0100004b0.fpix outfile=outflatfield.fits \
       outmaptype=EFFICIENCY delta=1.0 numphi=4 maskcalsrc=no

SEE ALSO

xaarfgen

LAST MODIFIED