.help pcexpmap Jan96 ftools.rosat
.ih
NAME
pcexpmap -- creates an exposure map for a given ROSAT PSPC 
dataset with an option to use devignetted detector map 
.ih
USAGE
pcexpmap evrfil attfil gtifil yes outfil

                   or 

pcexpmap evrfil attfil gtifil no dmapfil outfil 
.ih
DESCRIPTION

  This task creates the band-correct exposure map for a ROSAT PSPC pointed
observation. (The task is essentially an FTOOLized version of Steve
Snowden's CAST_EXP code). Detector maps created from the ROSAT All-Sky
Survey data are required. The output is a 512x512 FITS image of the whole
PSPC field of view (with pixels 14.94733 arcsec per side; representing a
blocking factor of 16 over the raw [0.9341875 arcsec] pixelsize) of the
effective exposure time (in seconds) at that position. The effects of
vignetting (for a spectrum equal to the mean spectrum of the X-ray
background in the PSPC band) and spatial variations in the efficiency of
the detector are included (via the detector maps), along with detector
deadtime effects (this code). 

  The program follows the suggestions of Snowden et al. (1992, ApJ, 393
819) and Plucinsky et al. (1993, ApJ, 418, 519) to exclude regions near the edges of the PSPC which are strongly affected by the particle
background, the "bright line" regions. These regions are set to have zero
exposure time. The program also assumes that a selection has been done on
the data to exclude all events which follow within 0.35 ms of a "precursor"
event. This excludes some of the low pulse-height "after-Pulse" signal
which affects data collected after 1992 May. 

  In brief, the attitude and GTI files are used to construct a matrix of
the time the instrument spent at each pointing position (X,Y relative to
the nominal pointing position defined by the optical axis) and roll angle.
(The X,Y are in units of 14.94733 arcsec (see below) and the ROLL steps are
in units of 0.2076 degrees.) The event-rates file is then used to calculate
the live-time fraction at each of these positions. Finally the output
exposure map is constructed by moving the detector map to each off-axis
position, rotated to each roll angle, and adding the detector map with the
appropriate weighting factor to the exposure map under construction. 

.ih
A MORE DETAILED DESCRIPTION OF THE MAPS

The detector efficiency maps have been constructed in 13 channel ranges for
each of the two PSPCs. The naming scheme is such that file
.br
.nj
                         det_n_m_x.fits
.br
.nj

contains the map for PSPC-x over the channel range n-m (out of a full
resolution of 256 PI channels).

The channel ranges are as follows:
.br
.nj
Band Name       PI range        Energy
.br
.nj
R1              8-19            0.11-0.284
.br
.nj
R1L             11-19           0.11-0.284
.br
.nj
R2              20-41           0.14-0.284
.br
.nj
R3              42-51           0.20-0.83
.br
.nj
R4              52-69           0.44-1.01
.br
.nj
R5              70-90           0.56-1.21
.br
.nj
R6              91-131          0.73-1.56
.br
.nj
R7              132-201         1.05-2.04
.br
.nj

    These detector efficiency maps were created by using events from the
ROSAT all-sky survey in detector coordinates to approximate a flat field.
Point sources, particle contamination and times of short-term noncosmic
background enhancements were excluded from the data set.  Furthermore, an
estimate of the residual particle background contribution to the data was
subtracted.

    Creating the maps from such a pseudo flat field has an advantage over
using the theoretical vignetting function in that it accurately reflects
all detector and telescope nonuniformities.  Specific examples of such
nonuniformities are the shadowing by the wires and ribs of the window
support structure, electronic ``ghost'' images in the R1L (and R1) band,
and variations in the window thickness and therefore the detector quantum
efficiency as a function of position. The maps depend on the X-ray spectrum
and their creation for each pulse-height band reflects the average spectrum
of the soft X-ray diffuse background.  This will create no problems in the
lowest pulse-height bands where the vignetting is little changed over the
energy range covered by the band.  However, for the highest pulse-height
band, if the spectrum of an extended object is much different from that of
the SXRB, the vignetting correction will lose accuracy.

    The maps for the two PSPCs are not the same.  Besides detector-specific
artifacts, there is a small shift in the position of the window support
structures and the windows have slightly different thickness distributions.
 The main survey was done with the first PSPC (~180 days), and there were
~11 days of survey with the second PSPC to extend the sky coverage in
exposure gaps of the main survey.  Because of this, data exist to create
maps for both detectors.  However, the statistics of the second PSPC data
are obviously significantly worse than those of the main survey, and are
inadequate for determining the fine structure in the maps for bands R3
through R7.  For these bands, templates were created by shifting the maps
of the first PSPC to correctly align the shadows of the window support
wires and ribs with the second PSPC.  The shifted maps were then normalized
to the maps of the second PSPC over overlapping 5'x5' regions to give the
correct telescope vignetting and detector quantum efficiency.
Unfortunately, the systematics of the detector artifacts in the R1 and R2
bands are sufficiently different between the two detectors to preclude
using the same scheme for these bands.  So, despite the worse statistics,
the maps for the second PSPC for these bands were created using only the 11
days of survey data taken with this detector.

    The pixel size of the maps is 14.947'' x 14.947''. The reason for this
somewhat obscure pixel size is that the PSPC detector position digitization
is 0.934208''and the detector coordinates were binned by 16 for the maps.
Note that this is not an integral number of SASS event-position intervals
(0.5''), or the same pixel size as the SASS event images (15''x15'').
The maps were normalized to the on-axis value by fitting the radial
distribution of the inner 18' radius region of the PSPC to the theoretical
vignetting function (Molendi 1993).  The *average* shadowing by the window
support wires is therefore not included in the exposure correction;
however, it is included in the window transmission for modelling purposes.
The spatial structure of the shadowing caused by the window support wires
and the window support ribs is included in the exposure correction produced
by the maps.

    The effects of electronic ghost images are very obvious in the
regularly spaced bright spots and somewhat less-bright lines.  The PSPC is
an imaging proportional counter that makes use of induced charge on crossed
cathode wires to obtain the position of accepted events.  The
two-dimensional position determination is done using the largest signals on
the crossed cathodes, essentially interpolating the event position between
the two nearest cathode wires in each direction.  For very low pulse-height
events, there is the possibility that only one cathode in one or both
directions will have signals above the lower level discriminator of the
analog electronics chain.  In this case, the position determination
degenerates to the center of the nearest cathode, yielding a line (if only
one axis has a single nonzero cathode value) or a point (if both axes have
only one nonzero cathode value each).


      Also visible in the detector_maps is a slight bending of the
electronic ghost-image lines.  This detector artifact is due to the
position correction algorithm.  The algorithm corrects the event position
based on the assumption that the X-ray was absorbed in the counter gas near
the window.  The bulging of the window support structure by the pressure of
the counter gas bends the electric field lines in the electron drift region
of the PSPC.  This causes a displacement of the event position, an effect
which has been calibrated and is included in the SASS event
position-correction procedure.  Since the low pulse-height events which
contribute to the electronic ghost images have detected positions shifted
to the wire positions, this correction is not the appropriate one.

    Electronic ghost images strongly affect only the R1 and R1L band maps,
although the R2 band map also shows some irregularities.  However, since
the electronic ghost images are pulse height and not energy dependent, the
R1 map created from the high-gain data is reasonably appropriate for
correcting the R1L band data collected in the low-gain state (where no
survey data exist to produce a flat field).  This works because the R1L
band at low gain includes the same pulse heights at its low end as the R1
band at high gain.  The weighting by the source spectrum is of course
slightly different, but this is a small effect in this energy range.  The
R1 maps should be used for R1 band analysis for data collected during
high-gain operation.  The R1 map should also be used for R1L band analysis
for data collected during low-gain operation.  We have created R1L maps for
both detectors to be used in R1L band analysis *only* for data collected
during high-gain operation.  (Note that the R1L band nomenclature refers to
the 11-19 channel band, which must be used for observations taken at low
gain. However, the R1L band can also be used for observations taken at high
gain. This is even preferable if an image derived from high-gain data will
be compared with an image derived from low-gain data.  To make sense of all
this, remember that the PI channels are adjusted to always correspond to
the same energy, so the corresponding pulse height will change with gain.)

The maps are described in more detail in Snowden et al 1994 (ApJ 424, 728),
Snowden et al. (1992,  ApJ, 393  819)  and  Plucinsky  et  al. (1993, ApJ,
418, 519) and details of how to use these maps in data analysis are
provided in Snowden, et al 1994, ApJ, 424, 714. 

.ih
WARNINGS ON USAGE

  It should be noted that the o/p data array is written as REALS in the 
Primary extension of the o/p FITS file. The image display & manipulation 
task, saoimage (v1.06), is unable to correctly read such datasets on DEC 
VMS & ultrix platforms.

  The current version of this task will only operate on i/p datasets in US 
Rev0 format or RDF format (ie cannot read German/UK Rev0 datasets). 
Furthermore all i/p datasets must be in the same format.

.ih
PARAMETERS
.ls evrfil [character string]
 The name of the FITS file containing the qualified event rate data for the 
 observation.For RDF format this is usually the *_anc.fits file, and for
 US Rev0, it is the *.evr file.
.le
.ls attfil [character string]
 The name of the FITS file containing the attitude data for the observation.
 The special character % can be used to indicate that the extension 
 containing the attitude dataset is in the same file as specified via the 
 evrfil parameter, this is usually the case for RDF data. For RDF format,
 this is usually the *_anc.fits file, for US Rev0 it is the *.cas file.
.le
.ls gtifil [character string]
 The name of the FITS file containing the Good Time Intervals (GTIs) to be 
 used. If the special strings 'NONE', 'none' or ' ' are given, then the 
 task will assume that all times given in the EVR dataset should be used.
 For RDF format this is usually the *_bas.fits file, and for US Rev0 it is
 the *.fits file.
.le
.ls (evtfil=%) [character string]
 The name of the FITS file containing the EVENTS data. This is only used
 for US Rev 0 data. The sky coordinate values are read from this file.
 If the special string "none" is entered and the input datasets are in
 US Rev 0 format then the user will be explicitly prompted for the
 pointing values.
.le
.ls qdetmap [boolean]
 whether devignetted detector map to be used.  If yes, it chooses 
automatically which (hi or low) gain to be used.
.le
.ls dmapfil [character string]
 The name of the detector map file.
.le 
.ls outfil [character string]
 The name of output file.
.le
.ls (clobber=no) [boolean]
 Overwrite existing file ?
.le
.ls (chatter=9) [Integer]
 Flag to indicate how chatty the task is at execution. A value of 9 is the
 default, with lower/higher values producing quieter/verbose output 
 respectively.
.le

.ih
EXAMPLE
.nf
% pcexpmap 
Enter Event rate filename[] rp900176n00_anc.fits
Enter Attitude filename[] %
Enter GTI filename[] rp900176n00_bas.fits
Enter output filename[] rp900176n00_pcexpmap.fits
Want to use devignetted detector map?[yes] yes
 ** pcexpmap 2.3.2
 ...  Number of unique detector positions         930
 ...  Number of entries when Detector ON        24333
 ...  Number of entries when Detector OFF           9 (ALL c/rate<10)
 ...  Total ONTIME            24332.00000 s
 ...  Total LIVETIME          23684.80664 s
 ...  Average MV c/rate          81.82201 count/s
100% completed
 ** pcexpmap 2.3.2 completed successfully
.fi
 
.ih
BUGS
None known

.ih
SEE ALSO
.br
.nj
 Snowden et al. (1992, ApJ, 393 819) 
.br
.nj
 Plucinsky et al. (1993, ApJ, 418, 519)
.ju

.ih
LOG OF SIGNIFICANT CHANGES

.ls v2.1.0 (1996 Aug) Banashree Mitra Seifert
    Added option to use devignetted map
.le
.ls v2.0.5 (1996 Jan)
    Added parameters - ra_nom, dec_nom and evtfil
.le
.ls v2.0.0 (1994 Mar)
    Added dynamic memory allocation, and renamed task from PSPCEXPM
.le
.ls v1.0.0 (1993 Nov)
    Beta-test version
.le

.ih
PRIMARY AUTHOR

.nj
Rehana Yusaf
.br
.nj
HEASARC
.br
.nj
NASA/GFSC
.br
.nj
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
.br
.nj
(301) 286-6115
.ju

.endhelp

