.help eaddmap Aug97 gro
.ih
NAME
emapgen 
.ih
USAGE
emapgen evfile filnam csystm lonmin lonmax latmin latmax
.sp
xbinsiz ybinsiz timfmt stjd smsd smonth sday syr
.sp
smin ssec etjd emsd emonth eday eyr ehr emin esec
.sp
tscflg detmax pulflg lpulphase upulphase lbinphase
.sp
ubinphase albcut numlev eng1lv1 eng1lv2 eng1lv3 
.sp
eng1lv4 eng1lv5 eng1lv6 eng1lv7 eng1lv8 eng1lv9
.sp 
eng1lv10 eng2lv1 eng2lv2 eng2lv3 eng2lv4 eng2lv5
.sp 
eng2lv6 eng2lv7 eng2lv8 eng2lv9 eng2lv10 zenmax1 
.sp
zenmax2 zenmax3 zenmax4 zenmax5 zenmax6 zenmax7
.sp
zenmax8 zenmax9 zenmax10 timeline
.ih
DESCRIPTION
Emapgen converts a photon list (qvp file) to a counts map. The data are binned according to the event's arrival direction in a rectangular coordinate system. Finally the program stores the binned values in a data cube  with the energy level as the third dimension.
.sp
An ascii file called the timeline file is required by this ftool and has been store in the CGRO refdata directory.  The ftool will automatically pull this file.  The timeline file contains information on the state of EGRET (e.g. when the instrument is in calibratin mode ect.)
.sp
Please note that the start and end time specifications for the desired ouput data set (map) MUST BE bracketted by the start and endpoints of the input data set (Viewing Period event or QVP file). This is true irrespective of the choice of input time coordinates (i.e. TJD or calendar date). 
.ih
PARAMETERS
.le
.ls evfile [filename]
A fits file that contains a list of photon events.  This is a qvp fits file.
.le
.ls filnam [filename]
The name of the output counts map.
.le
.ls csystm [string]
The qvp file stores the coordinates of the data in eight different coordinate systems.  This variable allows the user to select a system:
.sp
'GALA' - galactic coordinates
.sp
'CELE' - celestial coordinates
.sp
'INST' - instrument centered coordinates
.sp
'ERTH' - earth centered coordinates
.sp
The default is 'GALA'
.sp
.le
.ls lonmin [real]
The minimum longitude coordinate in the coordinate system of csystm. No default value for this variable.
.le
.ls lonmax [real]
The maximum longitude coordinate in the coordinate system of csystm. No default value for this variable.
.le
.ls latmin [real]
The minimum latitude coordinate in the coordinate system of csystm. No default value for this variable.
.le
.ls latmax [real]
The maximum latitude coordinate in the coordinate system of csystm. No default value for this variable.
.le
.ls xbinsiz [real]
The bin size in the x direction. The default value for this variable is: 0.5
.le
.ls ybinsiz [real]
The bin size in the y direction. The default value for this variable is: 0.5
.le
.ls timfmt [string]
This is the time system to be used for the user limits on time. The user can set time limits that will constrain which events will be binned.
.sp
'CAL' - calender dates 
.sp
'TJD' - Truncated julian date
.sp
The default value for this variable is: 'CAL'
.le
.ls stjd [integer]
This is the starting tjd for the time period during which events should be kept.  This value should be set if timfmt 'TJD'. There is no default for this variable. This must be greater than or equal to the start time of the input data set.
.le
.ls smsd [integer]
The millesecond of the day at the beginning of the time period during which events should be kept.  This value should be set if timfmt is 'CAL'. The default is 0.
.le
.ls smonth [integer]
The month at the beginning of the time period during which events should be kept.  This value should be set if timfmt is 'CAL'. The default for this variable is: 1 (i.e. January)
.le
.ls sday [integer]
The day at the beginning of the time period during which events should be kept.  This value should be set if timfmt is 'CAL'. The default for this variable is: 1
.le
.ls syr [integer]
The year at the beginning of the time period during which events should be kept.  This is a 2 digit value.  Numbers above 65 will have 1900 added to them.  Numbers below 65 will have 2000 added to them.  This avoids year 2000 bugs.  This value should be used if timfmt is 'CAL'. The default for this variable is: 80  (i.e. 1980) With this choise of the default, all photons taken during the lifetime of EGRET will be used.
.le
.ls shr [integer]
The hour at the beginning of the time period during which events should be kept.  This value should be set if timfmt is 'CAL'. The default for this variable is: 0
.le
.ls smin [integer]
The hour at the beginning of the time period during which events should be kept.  This value should be set if timfmt is 'CAL'. The default for this variable is: 0
.le
.ls ssec [integer]
The hour at the beginning of the time period during which events should be kept. This value should be set if timfmt is 'CAL'. The default for this variable is: 0
.le
.ls etjd [integer]
This is the ending tjd for the time period during which events should be kept. This value should be set if timfmt 'TJD'. There is no default for this variable. This value should be less than or equal to the end time of the input events data set.
.le
.ls emsd [integer]
The millesecond of the day at the end of the time period during which events should be kept.  This value should be set if timfmt is 'CAL'. The default for this variable is: 0
.le
.ls emonth [integer]
The month at the of end the time period during which events should be kept. This value should be set if timfmt is 'CAL'. The default for this variable is: 1 (i.e. January)
.le
.ls eday [integer]
The day at the of end the time period during which events should be kept. This value should be set if timfmt is 'CAL'. The default for this variable is: 1 
.le
.ls eyr [integer]
The year at the of end the time period during which events should be kept. This is a 2 digit year.  Numbers above 65 will have 1900 added to them. Numbers below 65 will have 2000 added to them. This avoids year 2000 bugs. This value should be set if timfmt is 'CAL'. The default for this variable is: 50  (i.e. 2050) With this choise of the default, all photons taken during the lifetime of EGRET will be used.
.le
.ls ehr [integer]
The hour at the end of the time period during which events should be kept.  This value should be set if timfmt is 'CAL'. The default for this variable is: 0
.le
.ls emin [integer]
The hour at the end of the time period during which events should be kept.  This value should be set if timfmt is 'CAL'. The default for this variable is: 0
.le
.ls esec [integer]
The hour at the end of the time period during which events should be kept. This value should be set if timfmt is 'CAL'. The default for this variable is: 0
.le
.ls tscflg [boolean]
Y: Require that the event also have a 6 Mev event in the TASC. N: No requirement on TASC data. The default for this variable is: Y
.le
.ls detmax [integer]
This is the angle of acceptance from the pointing angle of the spacecraft in degrees. The default for this variable is: 30
.le
.ls pulflg [boolean]
Y: The data should be processed in pulsar mode. N: No special binning in time is done. The default for this variable is: N. If the user request pulsar mode then the qvp should have been processed by the program PULSAR which inserts phases.
.le
.ls lpulphase [real]
This is the lower cutoff for the pulsar phase. The pulsar phase must lie between this value and upulphase. The default for this variable is: 0
.le
.ls upulphase [real]
This is the upper cutoff for the pulsar phase. The pulsar phase must lie between this value and lpulphase. The default for this variable is: 1
.le
.ls lbinphase [real]
This is the lower cutoff for the binary phase. The binary phase must lie between this value and ubinphase. The default for this variable is: 0
.le
.ls upbinphase [real]
This is the upper cutoff for the binary phase. The binary phase must lie between this value and lbinphase. The default for this variable is: 1
.le
.ls albcut [real]
This variable is used to calculate zenith angle cutoffs eliminate the Earth's albedo.  If this number is zero the user inputs a series of maximum values for the zenith angle either at the command line or interactively as the program runs. 
.sp
If albcut is non-zero, it is used to calculate the zenith cutoff angles.
.sp
For this case albcut is multiplied by an energy dependent angle to determine the zenith cutoff.  The formula for the energy dependent angle can be found in: Thompson D.J. et al.,1993,ApJS,86,629. 
.sp
The default for this variable is: 2.5
.le
.ls numlev [integer]
This is the number of energy levels. For each energy level there are two mandatory inputs and a third optional input: a lower energy, ENRGY1_#, an upper energy level, ENRGY2_# and if albcut is set to zero a value for ZENMAX#, where # is the number of the level.  Emapgen will ignore any values set for energy levels that lie above numlev. Numlev can take on values from 1 to 10. The default for this variable is: 10
.le
.ls eng1lv1  [integer]
This is the lower energy for the first energy level. There is no default for this variable.
.le
.ls eng1lv2  [integer]
This is the lower energy for the second energy level. There is no default for this variable.
.le
.ls eng1lv3  [integer]
This is the lower energy for the third energy level. For this number to be passed into emapgen numlev must be equal to three or greater. There is no default for this variable.
.le
.ls eng1lv4  [integer]
This is the lower energy for the fourth energy level. For this number to be passed into emapgen numlev must be equal to four or greater. There is no default for this variable.
.le
.ls eng1lv5  [integer] 
This is the lower energy for the fifth energy level. For this number to be passed into emapgen numlev must be equal to five or greater. There is no default for this variable.
.le
.ls eng1lv6  [integer]
This is the lower energy for the sixth energy level. For this number to be passed into emapgen numlev must be equal to six or greater. There is no default for this variable.
.le
.ls eng1lv7  [integer]
This is the lower energy for the seventh energy level. For this number to be passed into emapgen numlev must be equal to seven or greater. There is no default for this variable.
.le
.ls eng1lv8  [integer]
This is the lower energy for the eighth energy level. For this number to be passed into emapgen numlev must be equal to eight or greater. There is no default for this variable.
.le
.ls eng1lv9  [integer]
This is the lower energy for the ninth energy level. For this number to be passed into emapgen numlev must be equal to nine or greater. There is no default for this variable.
.le
.ls eng1lv10  [integer]
This is the lower energy for the tenth energy level. For this number to be passed into emapgen numlev must be equal to ten. There is no default for this variable.
.le
.ls eng2lv1  [integer]
This is the upper energy for the first energy level. There is no default for this variable.
.le
.ls eng2lv2  [integer]
This is the upper energy for the second energy level. There is no default for this variable.
.le
.ls eng2lv3  [integer]
This is the upper energy for the third energy level. For this number to be passed into emapgen numlev must be equal to three or greater. There is no default for this variable.
.le
.ls eng2lv4  [integer]
This is the upper energy for the fourth energy level. For this number to be passed into emapgen numlev must be equal to four or greater. There is no default for this variable.
.le
.ls eng2lv5  [integer]
This is the upper energy for the fifth energy level. For this number to be passed into emapgen numlev must be equal to five or greater. There is no default for this variable.
.le
.ls eng2lv6  [integer]
This is the upper energy for the sixth energy level. For this number to be passed into emapgen numlev must be equal to six or greater. There is no default for this variable.
.le
.ls eng2lv7  [integer]
This is the upper energy for the seventh energy level. For this number to be passed into emapgen numlev must be equal to seven or greater. There is no default for this variable.
.le
.ls eng2lv8  [integer]
This is the upper energy for the eighth energy level. For this number to be passed into emapgen numlev must be equal to eight or greater. There is no default for this variable.
.le
.ls eng2lv9  [integer]
This is the upper energy for the ninth energy level. For this number to be passed into emapgen numlev must be equal to nine or greater. There is no default for this variable.
.le
.ls eng2lv10  [integer]
This is the upper energy for the tenth energy level. For this number to be passed into emapgen numlev must be equal to ten. There is no default for this variable.
.le
.ls zenmax1  [real]
This is the cutoff for the zenith angle. If albcut is nonzero this will be overwriten by a value calculated inside of emapgen. There is no default for this variable.
.le
.ls zenmax2  [real]
This is the cutoff for the zenith angle. If albcut is nonzero this will be overwriten by a value calculated inside of emapgen. There is no default for this variable.
.le
.ls zenmax3  [real]
This is the cutoff for the zenith angle. If albcut is nonzero this will be overwriten by a value calculated inside of emapgen. For this number to be passed into emapgen numlev must be equal to three or greater. There is no default for this variable.
.le
.ls zenmax4  [real]
This is the cutoff for the zenith angle. If albcut is nonzero this will be overwriten by a value calculated inside of emapgen. 
.sp
For this number to be passed into emapgen numlev must be equal to four or greater. There is no default for this variable.
.le
.ls zenmax5 [real]
This is the cutoff for the zenith angle.  If albcut is nonzero this will be overwriten by a value calculated inside of emapgen. For this number to be passed into emapgen numlev must be equal to five or greater.  There is no default for this variable.
.le
.ls zenmax6  [real]
This is the cutoff for the zenith angle. If albcut is nonzero this will be overwriten by a value calculated inside of emapgen.
.sp
For this number to be passed into emapgen numlev must be equal to six or greater. There is no default for this variable.
.le
.ls zenmax7  [real]
This is the cutoff for the zenith angle.  If albcut is nonzero this will be overwriten by a value calculated inside of emapgen. For this number to be passed into emapgen numlev must be equal to seven or greater. There is no default for this variable.
.le
.ls zenmax8  [real]
This is the cutoff for the zenith angle.  If albcut is nonzero this will be overwriten by a value calculated inside of emapgen. For this number to be passed into emapgen numlev must be equal to eight or greater. There is no default for this variable.
.le
.ls zenmax9  [real]
This is the cutoff for the zenith angle.  If albcut is nonzero this will be overwriten by a value calculated inside of emapgen. For this number to be passed into emapgen numlev must be equal to nine or greater. There is no default for this variable.
.le
.ls zenmax10  [real]
This is the cutoff for the zenith angle.  If albcut is nonzero this will be overwriten by a value calculated inside of emapgen. For this number to be passed into emapgen numlev must be equal to ten. There is no default for this variable.
.le
.ls timeline  [string]
This is the location of the timeline file.  The default for this variable is $FTOOLS/refdata/timeline, where $FTOOLS refers to the directory that the FTOOLS were installed to.
.le
.ih
EXAMPLES
The example below will make a map from the photons in the fits file qvp0160s.fits and put the results in qvptes.fits. This run will not eliminate any photons based on the time tag on the photon.  The default values are being used for detmax, xbinsiz, ybinsiz, and albcut (so the zenith angles do not need to be entered).
.sp
.nf
     emapgen 'qvp0160s.fits' 'qvptes.fits'  
     lonmin=-20.0 lonmax=20.0 latmin=-20.0 latmax=20.0      
     eng1lv1=30    eng2lv1=50  
     eng1lv2=50    eng2lv2=70  
     eng1lv3=70    eng2lv3=100  
     eng1lv4=100   eng2lv4=150  
     eng1lv5=150   eng2lv5=300  
     eng1lv6=300   eng2lv6=500  
     eng1lv7=500   eng2lv7=1000  
     eng1lv8=1000  eng2lv8=2000  
     eng1lv9=2000  eng2lv9=4000  
     eng1lv10=4000 eng2lv10=10000  

     The example below is making a map of pulsar data. 
     The file, PVP0007A was produced by the program pulsar. 
     There will be no restriction on the points in terms of  
     binary phase, but only the photons that have a pulsar 
     phase between 0.5 and 1.0 will be used in the map.  Also
     the user has placed a time range over in which photons 
     will be accepted (this has nothing to do with the pulsar
      mode).

    emapgen 'PVP0007A' 'pulstes.fits'  
    lonmin=250.0 lonmax=320.0 latmin=-40.0 latmax=40.0  
    smonth=05 sday=10 syr=91 shr=20 smin=15 ssec=08  
    emonth=5 eday=16 eyr=91 ehr=16 emin=38 esec=58  
    detmax=40 pulflg=Y  
    lpulphase=0.5 upulphase=1.0  lbinphase=0.0 ubinphase=1.0  
    numlev=2 eng1lv1=30 eng2lv1=100 eng1lv2=100 eng2lv2=99999
.fi
.sp
.ih
BUGS
.ih
SEE ALSO
eaddmap
.endhelp
