EADDMAP (Aug97)                   gro                    EADDMAP (Aug97)



NAME 
    emapgen      
    
USAGE 
    emapgen evfile filnam csystm lonmin lonmax latmin latmax     
    xbinsiz ybinsiz timfmt stjd smsd smonth sday syr     
    smin ssec etjd emsd emonth eday eyr ehr emin esec     
    tscflg detmax pulflg lpulphase upulphase lbinphase     
    ubinphase albcut numlev eng1lv1 eng1lv2 eng1lv3      
    eng1lv4 eng1lv5 eng1lv6 eng1lv7 eng1lv8 eng1lv9     
    eng1lv10 eng2lv1 eng2lv2 eng2lv3 eng2lv4 eng2lv5     
    eng2lv6 eng2lv7 eng2lv8 eng2lv9 eng2lv10 zenmax1      
    zenmax2  zenmax3  zenmax4  zenmax5  zenmax6  zenmax7       
    zenmax8 zenmax9 zenmax10 timeline     
    
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.     
    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.)     
    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).      
    
PARAMETERS 
    
    evfile [filename]         
        A  fits  file  that contains a list of photon events.  This is a
        qvp fits file.     
    filnam [filename]         
        The name of the output counts map.     
    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:         
        'GALA' - galactic coordinates         
        'CELE' - celestial coordinates         
        'INST' - instrument centered coordinates         
        'ERTH' - earth centered coordinates         
        The default is 'GALA'         
    
    lonmin [real]         
        The minimum longitude coordinate in  the  coordinate  system  of
        csystm. No default value for this variable.     
    lonmax [real]         
        The  maximum  longitude  coordinate  in the coordinate system of
        csystm. No default value for this variable.     
    latmin [real]         
        The minimum latitude coordinate  in  the  coordinate  system  of
        csystm. No default value for this variable.     
    latmax [real]         
        The  maximum  latitude  coordinate  in  the coordinate system of
        csystm. No default value for this variable.     
    xbinsiz [real]         
        The bin size in the x direction.  The  default  value  for  this
        variable is: 0.5     
    ybinsiz [real]         
        The  bin  size  in  the  y direction. The default value for this
        variable is: 0.5     
    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.         
        'CAL' - calender dates          
        'TJD' - Truncated julian date         
        The default value for this variable is: 'CAL'     
    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.     
    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.     
    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)     
    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     
    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.     
    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     
    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     
    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     
    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.     
    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     
    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)     
    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      
    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.     
    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     
    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     
    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     
    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     
    detmax [integer]         
        This is the angle of acceptance from the pointing angle  of  the
        spacecraft in degrees. The default for this variable is: 30     
    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.     
    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     
    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     
    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     
    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     
    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.          
        If  albcut  is  non-zero,  it  is  used  to calculate the zenith
        cutoff angles.         
        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.          
        The default for this variable is: 2.5     
    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     
    eng1lv1  [integer]         
        This  is  the  lower energy for the first energy level. There is
        no default for this variable.     
    eng1lv2  [integer]         
        This is the lower energy for the second energy level.  There  is
        no default for this variable.     
    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.     
    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.     
    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.     
    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.     
    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.     
    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.     
    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.     
    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.     
    eng2lv1  [integer]         
        This  is  the  upper energy for the first energy level. There is
        no default for this variable.     
    eng2lv2  [integer]         
        This is the upper energy for the second energy level.  There  is
        no default for this variable.     
    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.     
    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.     
    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.     
    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.     
    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.     
    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.     
    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.     
    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.     
    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.     
    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.     
    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.     
    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.          
        For  this  number to be passed into emapgen numlev must be equal
        to four or greater. There is no default for this variable.     
    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.     
    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.         
        For this number to be passed into emapgen numlev must  be  equal
        to six or greater. There is no default for this variable.     
    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.     
    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.     
    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.     
    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.     
    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.     
    
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).     
         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     
    
    
    
BUGS 
    
    
SEE ALSO 
    eaddmap