LIKE (May02)                   ftools.gro                   LIKE (May02)



NAME 
    like  --  Performs  Maximum  Likelihood  analysis of EGRET sky maps.
    Provides menu driven options.     
    
USAGE 
    like datadir calibdir tempfildir cmapfile  emapfile  gmapfile  ranal
    lmapfile  gbiasfile  miscdir  egretdoc  phase0  phase1 phase2 phase3
    phase4 phase5 phase6 phase7 phase8 phase9 phase10     
    
DESCRIPTION  
    This is the FTOOLS version of the EGRET  team  "like"  program.  Its
    purpose  is  to  apply  a  maximum  liklihood  analysis to the EGRET
    skymaps,  to  determine  the  significance,  position,  fluxes   and 
    spectral information for point source candidates.     
    The  likelihood  ratio test is used to determine the significance of
    point sources.  It  is  based  on  the  maximum-liklihood  algorthim
    described        in       Mattox       and       Macomb       (1993)      
    <ftp://cossc.gsfc.nasa.gov/pub/software/egret/like.tex>; also  refer
    to  Mattox,  J.R., et al 1996, ApJ, 461, 396. Note however, that the
    Mattox & Macomb (1993) document  makes  specific  references  to  an
    older  version  of  the code, so some of the interactive commands no
    longer work  as  described.  It  also  discusses  a  "control  file"
    interface,  and  directory  structures  which are now handled by the
    FTOOLS parameter file interface.  The  original  code  had  numerous
    authors, both at GSFC and the Max Planck Institute.     
    The  EGRET  point source analysis program, like, is used analyze the
    EGRET  data  (FITS  Count  and  Exposure  maps,  as  well  as   some 
    auxilliary   files)   with  the  goal  of  point  source  detection, 
    localization, and spectral  characterization.  Specifically,  it  is
    designed  to  find  an excess above the predicted diffuse-background
    flux which is consistent with the instrument point  spread  function
    (PSF).  It  also  has parameter-estimation capbilities.  LIKE uses a
    maximum likelihood method (e.g. Cash, 1979,ApJ, 228, 939)      
    Experience with flight data from the  CGRO  mission  indicates  that
    the  maximum  liklihood  method  provides reliable gamma-ray results
    (e.g. Mattox et al 1996). The method allows simultaneous  estimation
    of  background model parameters (a multiplier for a diffuse galactic
    emission model and the intensity  of  isotropic  emission)  and  the
    intensity  of  emission from a hypothetical point source distributed
    as the EGRET PSF.     
    The maximum-liklihood ratio test provides a means  to  evaluate  the
    strength  of  the  evidence  for  the existence of a point source of
    gamma rays. By a well  known  theorem,  -2  times  the  log  of  the
    ml-ratio  (the likelihood of the data without a point source, or the
    null hypothesis, divided by the likelihood of the data with a  point
    source  which  is  the  alternative  hypothesis)  is  distributed as
    chi-square  with  one  degree  of  freedom  (source  strength  at  a 
    predetermined  location).   If  the  source  is  not  detected,  the 
    dependence of the ml-ratio on  the  intensity  of  the  hypothetical
    point  source  may be used to obtain an upper limit.  The dependence
    of the ml-ratio on the assumed position of the point  source  allows
    for  estimation  of  the source position and the uncertainty of this
    position.  In addition, estimates of the intensity of  emission  for
    sub-intervals  of  the  EGRET  energy range are used to obtain EGRET
    spectra.     
    Like is a Fortran program, migrated  to  FTOOLS  for  LHEASoft  5.2,
    which  accomplishes  all the above tasks. Its primary inputs are the
    counts and exposure maps produced by the  related  programs  emapgen
    and  intmap (also see eaddmap) respectively.  In addition, it uses a
    maps of expected diffuse galactic emission which are available  from
    the  CGRO  data  archive.   All  input  maps  are  expected to be in
    standard  FITS  format;  reading  and  writing  of  FITS  files   is 
    accomplished using the GSFC FITSIO package.     
    Like  is  a  very  resource  intensive  application. Our recommended
    minumum system resource requirements are 256  Mb  main  memory,  and
    about 150-200 Mb of scratch disk space for temporary files.     
    
    
INTERACTIVE MENU COMMANDS: 
    
    At  the  "like>"  prompt,  there  are  various interactive commands,
    summarized below.     
    
    Invoke          
        Help menu     
    B            
        Evaluate Gbias for fixed  value  of  Counts  and  position  with
        extant value of Gmult.     
    BB           
        Evaluate Gbias with extant values of Counts, Gmult and position.     
    C            
        Evaluate  Counts  for fixed position with extant values of Gmult
        and Gbias.     
    CB           
        Evaluate Counts and Gbias simultaneously for  a  fixed  position
        with the extant value of Gmult.     
    CBB                  
        Evaluate  Counts  and  Gbias  with  extant  values  of Gmult and
        position.     
    CC           
        Evaluate Counts with extant values of Gmult, Gbias and position.     
    E            
        Re-select the energy range.     
    G            
        Evaluate Gmult for fixed values of Counts and position with  the
        extant value of Gbias.     
    GB           
        Evaluate  Gmult  and  Gbias  simultaneously for a fixed value of
        Counts and position.     
    GBB          
        Evaluate Gmult and  Gbias  with  extant  values  of  Counts  and
        position.     
    GBC          
        Evaluate  Grnult,  Gbias,  and Counts simultaneously for a fixed
        position.     
    GC           
        Evaluate Gmult and Counts simultaneously  with  fixed  value  of
        Gbias.     
    GG           
        Evaluate   Gmult  with  extant  values  of  Counts,  Gbias,  and 
        position.     
    L            
        Evaluate  Gmult, Gbias, Counts, and TS for a fixed position.     
    LC           
        Evaluate a likelihood ratio test for source positions listed  in
        an input catalog file.     
    LE           
        Invoke  likelihood  position  error  analysis  using  elipsoidal 
        fitting.     
    LL           
        Evaluate Gmult, Gbias, Counts, and TS for the extant position.     
    LM           
        Optimize the values of Gmult, Gbias, and Counts for  active  PSF
        sources.     
    LN           
        Test  the significance of the extant source as an additional PSF
        source commands</     
    LPE          
        Perform error analysis for extant source or  PSF  sources  using
        equivalent area error circles.     
    LPF                  
        Find max TS for sources contained in a file.     
    LPM                          
        Create fine maps for active PSF sources.     
    LPMS          
        Perform search of the ROI for point sources.     
    LPO[]                        
        Optimize max TS positions for active PSF.     
    LPR[]                        
        Create report for all source locations in PSF map.     
    LPS[]                        
        Find the position max TS for a single test point source input.     
    MF           
        Create a fine map of likelihood.     
    MG           
        Create  a map of Gmult and Counts with fixed Gbias.     
    MH           
        Create a TS, Gbias, and Counts map with fixed Gmult.     
    MS           
        Create a map of the likelihood TS, Gmult, and Gbias.     
    OMC                  
        Output a FITS file of the counts map.     
    OME                  
        Output a FITS file of the exposure map.     
    OMG                  
        Output a FITS file of the diffuse model as flux.     
    OMGC                 
        Output a FITS map of the diffuse model as counts.     
    OMR                  
        Output a FITS file of the normalized residual counts.     
    OMRC                 
        Output a FITS file of the residual counts.     
    OMRF                 
        Output a FITS file of the residual flux.     
    OP           
        Produce a profile plot for the defined ROI.     
    PA           
        Invoke PSF adjustment menu.     
    PB           
        Command to reset, or add Gbias to the diffuse model.     
    PG           
        Adjust the spectral index used to construct the PSF.     
    PR           
        Adjust range of likelihood analysis (Ranal).     
    PMC                  
        Change coordinate system label.     
    PMF          
        Read an array into the PSF array.     
    PML                  
        Change limit confidence.      
    PMM                  
        Change output filenames.      
    PMN          
        Adjust Gmult_nom or Gbias_nom.     
    PMP          
        Toggle the PUBLISH flag.     
    PMV          
        Toggle VERBOSE flag.     
    PMR          
        Change Gmult or Gbias parameter restrictions.     
    PMS          
        Toggle SPECTRAL flag.      
    PMT          
        Adjust TS_min & TS_max.      
    PMX          
        Change extant value of counts, Gmult, Gbias, or position.     
    Q            
        Quit.     
    S            
        Adjust or reset the ROI range.     
    Z            
        Read like commands from a script.         
        
        
        
PARAMETERS 
    
    datadir [string]         
        name  of  directory  containing  FITS count and exposure maps as
        well as the standard diffuse map     
    calibdir [string]         
        name of directory containing FITS calibration files     
    tempfildir [string]         
        location to put temporary files  generated  during  the  program
        execution     
    cmapfile [string]         
        name of the input FITS counts map     
    emapfile [string]         
        name of the input FITS exposure map     
    gmapfile [string]         
        name of the input FITS diffuse background map     
    ranal [real]         
        desired radius for analysis (typically 10-15 degrees)     
    lmapfile [string]         
        name  of  the output file for maximum likelihood analysis; often
        not needed     
    gbiasfile [string]         
        name of the output file for gbias map; often not needed     
    miscdir [string]         
        name of directory containing miscelaneous files     
    egretdoc [string]         
        path to EGRET document directory; generally not used     
    phase0 [string]         
        user defined path     
    phase1 [string]         
        path to cycle 1 FITS directory (these "phaseN" parameters are  a
        relic  of  the  production  analysis  capability of the original
        program, and generally not used)     
    phase2 [string]         
        path to cycle 2 FITS directory     
    phase3 [string]         
        path to cycle 3 FITS directory     
    phase4 [string]         
        path to cycle 4 FITS directory     
    phase5 [string]         
        path to cycle 5 FITS directory     
    phase6 [string]         
        path to cycle 6 FITS directory     
    phase7 [string]         
        path to cycle 7 FITS directory or user defined path     
    phase8 [string]         
        path to cycle 8 FITS directory or user defined path     
    phase9 [string]         
        path to cycle 9 FITS directory or user defined path     
    phase10 [string]         
        path to cycle 10 FITS directory or user defined path         
        
EXAMPLES   
    
    In this example, like is run with the parameter file displayed     
    below. The second energy range (100 MeV - 99999 MeV) is selected, and      
    an interactive command, GBC,  to deterimne the Grnult, Gbias, and      
    Counts simultaneously for a fixed position, in this case that      
    of the Crab pulsar, is executed:     
    Parameter File:     
         
    #                 sample parameter file for like      
    #     
    # directory paths for input data, calibration, and temporary files     
    #     
    datadir,s,h,"/mydisk/egret/data_dir/",,,"Path to the input FITS files:"     
    calibdir,s,h,"/mydisk/egret/calib_dir/",,,"Path to the input Calibration files:"     
    tempfildir,s,h,"/mydisk/egret/tempbin_dir/",,,"Directory for temporary files:"     
    #     
    # input data files (count, exposure maps) and galactic diffuse emission model     
    #     
    cmapfile,s,a,"counts_vp0040_g002",,,"Name of the input FITS Counts Map:"     
    emapfile,s,a,"exposr_vp0040_g002",,,"Name of the input FITS Exposure Map:"     
    gmapfile,s,a,"cfgas.cel.g002b",,,"Name of the input FITS Diffuse Background Map:"     
    #     
    # radius of useful analysis region     
    #     
    ranal,r,a,15,,,"Desired radius for analysis:"     
    #     
    # oprional output files (generally not used)     
    #     
    lmapfile,s,a,"NONE",,,"Name of output file for Maximum Likelihood Map (def=NONE):"     
    gbiasfile,s,a,"NONE",,,"Name of output file for Gbias Map (def=NONE):"     
    #     
    # directory path for output (exposure and intensity maps) and miscellaneous files     
    #     
    miscdir,s,a,"/mydisk/egret/misc_dir/",,,"Directory for miscelaneous files:"     
    outputdir,s,a,"/mydisk/egret/output_dir/",,,"Path to the output files:"     
    #     
    # the following directory specification are retained for historical reasons      
    # and are usually not needed. they may be useful for production processing     
    #      
    egretdoc,s,h,".",,,"Path to EGRET document directory:"     
    phase0,s,h,".",,,"User defined path:"     
    phase1,s,h,".",,,"Path to cycle 1 FITS directory:"     
    phase2,s,h,".",,,"Path to cycle 2 FITS directory:"     
    phase3,s,h,".",,,"Path to cycle 3 FITS directory:"     
    phase4,s,h,".",,,"Path to cycle 4 FITS directory:"     
    phase5,s,h,".",,,"Path to cycle 5 FITS directory:"     
    phase6,s,h,".",,,"Path to cycle 6 FITS directory:"     
    phase7,s,h,".",,,"Path to cycle 7 FITS directory or user defined path:"     
    phase8,s,h,".",,,"Path to cycle 1 FITS directory or user defined path:"     
    phase9,s,h,".",,,"Path to cycle 1 FITS directory or user defined path:"     
    phase10,s,h,".",,,"Path to cycle 1 FITS directory or user defined path:"     
    #     
    clobber,i,ql,1,,,"Do you want to delete any existing output files? (Yes):"     
    mode,s,h,"ql",,,""     
    .sp     
    now run like using these inputs, and select energy range 2:     
    .sp     
    % like     
    ...     
    -----------------------------------------     
    THERE ARE  2 IMAGES with energy ranges:     
      1    30 MeV -    100 MeV     
      2   100 MeV -  99999 MeV     
     WHICH DO YOU WANT?     
    2     
    Then, use the gbc command to obtain a flux:     
    like>gbc     
    Input counts test point:   GLON and GLAT     
     (A to abort, cr for  189.750  -5.250):184.5 -5.86     
    Input Source Name (cr for                   ):Crab     
     Correlation coefficient for Counts/Gmult: -0.0772200525     
     Correlation coefficient for Counts/Gbias: -0.0168280266     
     Correlation coefficient for Gmult/Gbias: -0.937903702     
    Gmult    0.879582 +/-    0.049064     
    Gbias    4.495169 +/-    0.376795     
    Counts     875.92 +/-      45.46     
    Corresponding flux  214.573013 +/-   11.136075 10^-8 cm^-2 s^-1     
    Log likelihood:      2551.11     
    like>     
    In this example, a TS (test statistic, i.e. significance) map of the      
    whole field with the command     
    "lpi" at the "like>" prompt.  Specifically, these the responses     
    lpi,m,#C,C,<ret>,<ret>     
    
    
    
FILES NEEDED 
    The files needed to run like are downloadable from the  CGRO  public
    data  archive; <ftp://cossc.gsfc.nasa.gov/compton/data/egret/>. Look
    in the "high_level" directory for the counts and exposure  maps,  in
    the  "diffuse_model"  directories  for  the background maps, and the
    "calib" directory for the calibration files. Examples are:     
    datadir/counts_vp0040_g002.fits    #sample counts map     
    datadir/exposr_vp0040_g002.fits    #sample exposure map file     
    datadir/cfgas.cel.g002b            #sample galactic diffuse background map     
    datadir/cfgas.gal.g002b            #same but in galactic coordinates     
    datadir/catlog                     #catalof file (ascii), obtain from archive     
    calibdir/edpfil01.fits             #sample (energy dispersion) calibration file     
    calibdir/psdfil01.fits             #sample (point-spread function) calibration file      
    calibdir/sarfil01.fits             #sample (sensitive area correction) calibration file      
    miscdir/timeline                   #EGRET Timeline file (download from archive)     
    
    
    
BUGS 
    
    
SEE ALSO