NAME

a2lcurve -- A2LCURVE extracts a background subtracted lightcurve from the HEAO1 A2 raw rate data for a given sky position.


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)

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.

                         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    "      "      "      "      "      "

The appropriate discovery scalars to use to obtain the large field of view or the small field of view varies among the detectors.

                      HED-1 & HED-2               HED-3 & MED
         Large FOV     R1 & R2                L1 & L2
         Small FOV     L1 & L2                       R1 & R2                      

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 :

          (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.

A2lcurve conducts the above 'data rejection' criteria independently of the user-selected background.


PARAMETERS

equinox [real]
The equinox of the input sky position (default value 1950)

ra [character string]
The source R.A. given in hh mm ss.s or degrees.

dec [character string]
The source Dec. given in dd mm ss.s or degrees.

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.

rootname [character string]
The rootname for the generated lightcurve.

strtdate [character string]
The observation start date (dd/mm/yy).

strtime [character string]
The observation start time (hh:mm:ss).

enddate [character string]
The observation end date (dd/mm/yy).

endtime[character string]
The observation end time (hh:mm:ss).

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)

scalar1_1 [integer]
First discovery scalar for input detector (+/- 1 - 8).

scalar1_2 [integer]
Second discovery scalar (+/- 1 - 8).

scalar1_3 [integer]
Third discovery scalar (+/- 1 - 8).

scalar1_4 [integer]
Fourth discovery scalar (+/- 1 - 8).

anglim1_1 [real]
Start scan angle limit for input detector (degrees).

anglim1_2 [real]
Stop scan angle limit for input detector (degrees).

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.

mcilwain [real]
Upper limit of Mcilwain L value (in earth radii).

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.

backrate1 [real]
Background rate for the light-curve (for user-input background model only) in COUNTS/SEC.

backerr1 [real]
Background error rate for the light curve (for user-input background model only) in COUNTS/SEC (0 for 3% of background rate).

(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.

(lchat = 10) [integer]
Same as above but for the level of chatiness to the output log file.

(clobber=no) [boolean]
Flag to overwrite light curve if it already exists.

(mode = "ql") [character string]


BUGS

None known

CATEGORY

Aug99 ftools.heao1