.help a2lcurve Aug 99 ftools.heao1 
.ih
NAME
a2lcurve --  A2LCURVE extracts a background subtracted lightcurve 
from the HEAO1 A2 raw rate data for a given sky position.
.ih
USAGE
equinox ra dec infile rootname strtdate strtime enddate endtime 
detector scalar1_1 scalar1_2 scalar1_3 scalar1_4 anglim1_1 anglim1_2
mcfilter mcilwainl backmode backrate1 backerr1 (tchat) (lchat) (clobber) (mode)
.ih
DESCRIPTION

    A2LCURVE extracts a background subtracted lightcurve for a given 
    source position using data taken either the MED or HEDs detectors,
    part of the A2 experiment on board HEAO1.
    The lightcurve is extracted using the 5.12 seconds data and the
    count rate is the sum of the count rate obtained in different
    "discovery scalars" (minimum of two, maximum of four).


    The input file is one of the file lists output from A2SOURCE. This
    list contains the names of the raw data files corresponding to
    when the source position was most likely in the field of view. 

    
    #  discovery  scalars  #  A   "discovery  scalar"  is  a  count-rate 
    accumulated  in  various  combinations  of  spectral   and   spatial 
    windows.  There were 8 discovery scalars for each detector, of which
    the first four were fixed and unchanging throughout  the  course  of
    the  mission  and  were  defined  to  be L1, R1, L2, and R2 in order
    (where the latter are anode signals recorded  in  different  regions
    of  the  detector  -  anodes under the 3.0 deg x 3.0 deg collimators
    were known as L1 (for layer one) and L2  (for  layer  two).   Anodes
    under   the  other  collimator  were  called  R1  and  R2  ).    The 
    definitions for discovery scalars 5-8 changed throughout the  course
    of   the   missions   and  were  formed  from  combinations  of  six 
    pre-designed spectral windows: Layer 1 - 1A, 1B, 1C, and  1D;  Layer
    2  - 2A and 2B.  Discovery scalars 5 and 7 are for the left; scalars
    6 and  8  are  for  the  right.
.nf                    
	            Table 1 (Allen, Jahoda, and Whitlock 1994)
    
                     Window   MED  energy (keV)  HED energy (keV)
                       1A        1.5 - 6              2 - 6 
                       1B          6 - 8              6 - 8 
                       1C          8 - 10             8 - 32 
                       1D         10 - 20            32 - 60 
                       2A          2 - 3.9            9 - 32 
                       2B        3.9 - 20            32 - 60
    
                           Table III.2 (Marshall 1983)
    
                    MED           HED-1         HED-2        HED-3
        Day    DS5,6  DS7,8  DS5,6  DS7,8  DS5,6  DS7,8  DS5,6  DS7,8
       232.04  1A      Veto   1A     Veto   1A    Veto   1A     Veto
       234.94   "       "     1B    1D+2B   1B   1D+2B   1B    1D+2B
       238.89  1B      2B     "      "      "      "      "      "  
       242.20   "      1D     "      "      "      "      "      "
       248.15   "      2B     "      "      "      "      "      "
       304.93   "      "      "     1C      "     1C      "     1C
       321.79   "      "      "    1C+1D    "    1C+1D    "    1C+1D
       476.20   "      "      "      "      "      "     1A      "
       488.82   "      "      "      "      "      "     1B      "
       615.27   "    1C+1D    "      "      "      "      "      "
.fi    
    The appropriate discovery scalars to use to obtain the large field
    of view or the small field of view varies among the detectors. 
.nf
	         HED-1 & HED-2	       HED-3 & MED
    Large FOV     R1 & R2	        L1 & L2
    Small FOV     L1 & L2	       	R1 & R2       	       
.fi    
    For example the Large FOV for the HED-3 detector would correspond
    to selecting discovery scalars 1 and 3. The small FOV would
    correspond to 2 and 4. 

    A user may supply up to 4 discovery scalars. The "+" and "-" signs
    in the prompt indicate whether the discovery scalar data should be
    added or subtracted from the total. 

    Note: When a discovery scalar of 0 is input the program does not
    prompt for the remaining discovery scalars.

    # background  #   The   user  may  select  either  (i)  a  background
    generated   from  scans in the neighborhood of the source  OR (ii) a
    background based  on background model  provided  by  Frank  Marshall
    (this  is  only  appropriate for  the standard discovery scalars) OR
    (iii) a fixed standard background rate (with  errors) determined  by
    the  user  from  the  Standard  Background  Table  for  the   chosen 
    detector configuration  (see the  A2  User  guide for details or the
    HEASARC HEAO-1 Software Web page).
    
    Dr. McIlwain mapped the Earth's magnetosphere in coordinates of L
    and B which are roughly similar to radius and angle in spherical
    coordinates. It turns out that the best conditions for the X-ray
    environment are for small values of L (less than 1.2).

     A2lcurve goes  through  a  raw  data  file  row  by  row  and  will
    determine   if  each  row  contains 'good' background data  based on
    various data quality  checks. A row will be rejected  as  BAD  if  :
.nf
     (i)  the  McIlwain  parameter  is  >  1.2  earth radii or  
     (ii) the  overall quality flag (QFLAG) is > 0 or  
     (iii) the logical flag for clean data (clnflag) is set to .FALSE. or
     (iv) the logical flag for no electron contamination (elcomflag) is set to
       .FALSE. or
     (v) the logical flag for the source being in the A2 instrument
	  pointing direction is set to .FALSE. or  
     (vi) the logical flag for the satellite scan angle being within the user
	  input ANGLIM range (QANG) is set to .FALSE. or   
     (vii) finally, the detector efficiency > 0.
.fi    
     A2lcurve    conducts    the   above   'data   rejection'   criteria  
    independently of the  user-selected background.
    


.ih
PARAMETERS
.ls equinox [real]
         The equinox of the input sky position (default value 1950)
.le
.ls ra [character string]
         The source R.A. given in hh mm ss.s or degrees.
.le
.ls dec [character string]
         The source Dec. given in dd mm ss.s or degrees.
.le
.ls infile [character string]
        The name of the file  containing the list  of raw
        data  files. These files were generated by a2source. The raw
        data files correspond to when the source was most likely to
        have been  scanned. The name of  the  file lists
        will     be    either    {srcename}_medfiles.lis     or   
        {srcename}_hedfiles.lis.
.le
.ls rootname [character string]
         The rootname for the generated lightcurve.
.le
.ls strtdate [character string]
         The observation start date (dd/mm/yy).
.le
.ls strtime [character string]
         The observation start time (hh:mm:ss).
.le
.ls enddate [character string]
         The observation end date (dd/mm/yy).
.le
.ls endtime[character string]
         The observation end time (hh:mm:ss).
.le
.ls detector [integer]
         An  integer  to  indicate  which HED detector of interest (i.e.
        HED-1, HED-2 or HED-3).  This  prompt  is  only  issued  if  the
        infile was {srcename}_hedfiles.lis. That is the if the input
        is the file listing of High Energy Detector (HED) raw data files.
        (2=HED-1,3=HED-2,4=HED-3)
.le
.ls scalar1_1 [integer]
          First discovery scalar for input detector (+/- 1 - 8).
.le
.ls scalar1_2 [integer]
  Second discovery scalar (+/- 1 - 8).
.le
.ls scalar1_3 [integer]
  Third discovery scalar  (+/- 1 - 8).
.le
.ls scalar1_4 [integer]
  Fourth discovery scalar (+/- 1 - 8).
.le
.ls anglim1_1 [real]
  Start scan angle  limit for input detector (degrees).
.le
.ls anglim1_2 [real]
  Stop scan angle  limit for input detector (degrees).
.le
.ls mcfilter [boolean]
          Filter data by McIlwain L parameter ? (yes/no). If yes, the
          program will prompt for the upper limit of the L
          value. Otherwise this parameter is skipped.
.le
.ls mcilwain [real]
  Upper limit of Mcilwain L value (in earth radii).
.le
.ls backmode [integer]
          Integer  to  select  background  model  to  be  used (0 =
	  scanned, 1 = Marshall or 2 = user-input). If the input is 2
	  for user-input the program will prompt for the background
	  rate and error otherwise these parameters are skipped.
.le
.ls backrate1 [real]
          Background  rate  for  the   light-curve   (for 
        user-input background model only) in COUNTS/SEC.
.le
.ls backerr1 [real]
          Background  error rate for the light curve (for
        user-input  background model only) in COUNTS/SEC (0 for 3%
          of background rate).
.le
.ls (tchat = 10) [integer]
 Flag to indicate how chatty the task is at execution. A value of 10 is the
 default, with lower/higher values producing quieter/verbose output 
 respectively. This is for TERMINAL chattiness.
.ls (lchat = 10) [integer] 
  Same as above but for the level of chatiness to the output log file.
.le
.ls (clobber=no) [boolean] 
  Flag to overwrite light curve if it already exists.
.le
.ls (mode = "ql") [character string]
  
.le 

           

.ih
BUGS
None known


.endhelp

