.help hriexpmap Oct94 ftools.rosat
.ih
NAME
hriexpmap -- creates an exposure map for a given ROSAT HRI observational
dataset
.ih
USAGE
hriexpmap ltffil attfil gtifil dmapfil outfil rolof
.ih
DESCRIPTION

    
   This task creates an exposure map for a ROSAT HRI pointed 
observation.(The task is essentially an FTOOLized version of Steve Snowden's 
CAST_EXP_HRI code). A detector map created from the accumulated bright Earth
data is required. The output is a 512x512 FITS image of the whole HRI field
of view (with pixels 5.0 arcsec per side; representing a blocking factor of 10 
over the 0.5 arcsec sky pixelsize) of the effective exposure time (in seconds)
at that position.  The effects of vignetting  (for X-rays at 0.53 keV) and 
spatial variations in the efficiency of the detector are included (via the
detector map), along with detector deadtime effects (from the deadtime
correction file provided with the observation data set).
    
     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
digitizations in X and Y are in steps of 5 arcsec, the digitization in ROLL
angle is in steps of 0.004 radians.) The livetime correction file is then used 
to scale observation time 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
WARNINGS ON USAGE

  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.

  NOTE : This program takes a long time to cast the exposure, it is usefull
to have the chatter value >= 9 (see parameters section), as reassuring % 
completion values are printed.

.ih
PARAMETERS
.ls ltffil [character string]
 The name of the FITS file containing the livetime correction data for the
 observation. In the RDF format this is the ANCILLARY file, i.e. rh*_anc.fits.
.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 
ltffil parameter. If using the RDF ANCILLARY file the attfil value should be "%"
.le
.ls gtifil [character string]
The name of the FITS file containing the Good Time Intervals (GTIs) to be 
used. Users can specify the RDF BASIC file (rh*_bas.fits) if using RDF-formatted data. 
If the special strings 'NONE', 'none' or ' ' are given, then the 
task will assume that all times given in the LTF dataset should be used.
.le 
.ls dmapfil [character string]
 The name of the detector map file. If dmapfile="caldb" then the program will use the calibration database (CALDB)
.le
.ls outfil [character string]
 Output filename
.le 
.ls rolof [real]
 Roll offset. This is only needed for US Rev 0 data, for RDF data enter 0.
 This value should be entered in radians. In the US Rev 0 dataset the Roll
 offset value is given in the ATTITUDE extension header.
.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
.ls (clobber = false) [boolean]
 Flag specifying whether or not a pre-existing file with the same name as that
 requested as the output file from this task will be overwritten.
.le

.ih 
EXAMPLE:

This example uses the RDF dataset rh900385n00 and assumes that the HEASARC CALDB is being accessed remotely; see
http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_remote_access.html
for more information on how to access the HEASARC CALDB remotely
.nf
% printenv CALDB
% ftp://legacy.gsfc.nasa.gov/caldb
% hriexpmap
Please enter EVRATE/LIVETIME filename:[] rh900385n00_anc.fits
Please enter Attitude filename:[%] %
Please enter GTI filename:[none] rh900385n00_bas.fits
Please enter Detector map file:[caldb] 
 ...  using gtcalf 1.1.1
 ...  using caldb_info 1.2.1
 ...... environ-var/logical CALDB defined
 .........   CALDB path = ftp://legacy.gsfc.nasa.gov/caldb
 ...... environ-var/logical CALDBCONFIG defined
 .........   CALDBCONFIG file = /software/caldb/caldb.config
 ...... environ-var/logical CALDBALIAS defined
 .........   CALDBALIAS file = /software/caldb/alias_config.fits
 ...... CALDB is configured for the HRI instrument onboard ROSAT
 ......... Cal Index File: ftp://legacy.gsfc.nasa.gov/caldb/data/rosat/hri/caldb.indx
 ......... Data directory: ftp://legacy.gsfc.nasa.gov/caldb/data/rosat/hri
 ...  using cifsl2 5.0.4
 ......  Downloading be.fits
Please enter output filename[] rh900385n00_mex.fits
Please enter ROLL offset (for RDF enter 0) in radians:[0] 
 ** hriexpmap 1.1.4
 ......  ... LIST LENGTH =         1746
 ......  ... GOOD STEPS  =        11525
 ......  ... BAD STEPS   =          271
 ......  ... TOTALTIME   =  11525.00
 ......  ... TOTALEXP    =  11396.88
100% completed
 ** hriexpmap 1.1.4 completed successfully
.fi

.ih
BUGS
None known

.ih
NOTES
the output MEX file has a plate scale of 5"/pixel.

.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 v1.0.0 (1994 Oct)
.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

