ASCAEXPO (Jun98)             ftools.asca             ASCAEXPO (Jun98)


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.
                                  -1-
ASCAEXPO (Feb96)             ftools.asca             ASCAEXPO (Feb96)


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.
    

                                  -2-
ASCAEXPO (Feb96)             ftools.asca             ASCAEXPO (Feb96)


    defATTpath [string] (hidden parameters)
        The path pointing to the Attitude file.
    
    verbose [logical] (hidden parameters)
        The verbose flag: run time information updates.
     
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
    
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.
       
SEE ALSO
    
    ASCALIN, ATTITUDE, CLEANSIS.