ascaexpo HEADAS help file

NAME

ascaexpo -- Generate an exposure map for an ASCA observation.

USAGE

       ascaexpo evtfile calfile attfile ratefile instfile 
           expofile attstep rebin binoff

         where,

            datafile = name of event file for which an exposure map is to be made.
             calfile = name of input teldef file       (or CALDB).
             attfile = name of input attitude file     (or DEFAULT/NONE).
            ratefile = name of input rate file         (or NONE).
            instfile = name of input instrument file   (or NONE).
            expofile = name of output exposure map     (or DEFAULT).
            imapfile = name of output instrument map   (or DEFAULT).
             skyfile = name of output image sky map    (or DEFAULT).
             attstep = Maximum attitude deviation (arcsec) per step, or if 
                       negative, the number of attitude records to skip each step.
             rebin   = image rebin factor (if instfile=NONE; -1 for default)
             binoff  = pixel numbering convention offset ( 0.0 == 0.0<pixel<1.0 ).
                                                         ( 0.5 == 0.5<pixel<1.5 ).

DESCRIPTION

Routine to calculate the net exposure time per sky pixel for a given observation. The total time seen by each sky pixel on the detector is computed using an instrument map and the reconstructed aspect. The observation is sampled between GTIs and interpolated between the attitude records.

The resultant map depends on the type of input map supplied to this routine:

           INPUT INSTRUMENT MAP                   OUTPUT EXPOSURE MAP
     
       NONE (Uniform detector mask)            Net observation time per pixel
     
       Detector mask (0/1's shadow mask)       Geometric exposure time
     
       Detector efficiency                     Detector flat-field
     
       Detector + mirror efficiency            Observation flat-field

The output exposure map is created with the same dimensions as the input instrument map. If no instrument map is supplied (instfile=none), the program will generate a uniform mask with the dimensions of the input event file image size, and may be rebinned by an integral factor.

For the SIS, the hot pixel extension is read and used in the calculation. The address discrimination information is obtained from the header of the SIS observation file, which is assumed fixed over the duration of the file. If a rate file is given with the appropriate information, the number of SIS saturated frames and Address Discrimination changes will be computed.

This version does not include GIS dead time.

PARAMETERS

datafile [string]: The name of ASCA Science File for which the exposure map is to be made.
calfile [string]: The Telescope Definition file appropriate for the Science File instrument. If 'caldb' is entered, the appropriate file from the calibration data will be obtained (if available).
attitude [string]: The attitude file. If 'default' is entered, the path name stored in default parameters will be appended to the attitude file name stored in the file header. If 'none' or 'euler' is entered, a time independent exposure map will be created using the information in the event file header. This is a fast alternative to using the attitude file, which requires ASCALIN V0.9m or latter to be run on the Science File.
ratefile [string]: The file containing the necessary rate information for time dependent SIS frame saturation and address discrimination, and GIS deadtime [currently not implemented]. if 'none' is entered, these time dependent corrections are ignored.
instfile: Input ASCA instrument map filename. If 'none' is entered, an internally generated instrument map will be created and used. For the SIS, this map includes Area Discrimination and Hot Pixels, if they are available in the event file (see CLEANSIS). This map is written out to the file whose name is stored in the 'imapfile' parameter (unless it is set equal to 'none'). If imapmath='multiply', 'divide', add, 'subtract', the given instrument file will be calculated on by the internally generated instrument map.
expofile: Output exposure map filename (or default)
imapfile [string]: Output instrument map filename (or none/default).
skymap [string]: Output sky image filename (or none/default).
attstep [float]: Maximum deviation of attitude in arc-seconds between integration steps, or if negative, the number of attitude records to skip between steps. The speed of the program can be greatly increased using this option, but the accuracy of the exposure map may be reduced.
rebin [integer]: Rebin factor for computing the exposure, instrument, and sky files (-1 = default == SIS=4, GIS=1), if the instfile=none option is selected.
binoff [float]: Offset to add to the CRPIX keywords to follow a particular pixel convention - 0.0 for no offset, 0.5 for proposed FITS convention.
imath[string]: The input 'imapfile' instrument map may be multiplied, divided, added, or subtracted from the internally generated instrument map. Possible values of 'imapmath' are 'mul', div', 'add', 'sub', or 'none'.
atimecol [string] (hidden parameters): The attitude file time column name.
qcol [string] (hidden parameters): The attitude file Q-parameter column name.
qstat [string] (hidden parameters): The attitude file Q-stat column name.
gtiext [string] (hidden parameters)
xxxcol [string] (hidden parameters): Various rate file column names.
hpext [string] (hidden parameters): The event file HOT PIXEL extension name.
defATTpath [string] (hidden parameters): The path pointing to the Attitude file.

EXAMPLES

(also see USAGE) 1) Make exposure map for evtfile using teldef file from the CALBD, step through every tenth record of the default attitude file, and use an internally generated instrument map and no rate file information:

           ascaexpo evtfile caldb attfile none none default default 
                      default -10 -1 0.0

2) Make a time independent exposure map using an internally generated instrument map:

           ascaexpo evtfile teldef none none none default default 
                       default -1 0.0

.if BUGS GIS dead time not included in this version.

SIS frame saturation is under development in this version.

Compatible with ASCALIN V0.9m and higher.

AUTHOR

Eric Gotthelf.