.help like May02 ftools.gro
.ih
NAME
like -- Performs Maximum Likelihood analysis of EGRET sky maps. Provides menu driven options.
.ih
USAGE
like datadir calibdir tempfildir cmapfile emapfile gmapfile ranal lmapfile gbiasfile miscdir egretdoc phase0 phase1 phase2 phase3 phase4 phase5 phase6 phase7 phase8 phase9 phase10
.ih
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.
.sp
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.
.sp
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) 
.sp
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.
.sp
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.
.sp
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.
.sp
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.
.sp
.ih
INTERACTIVE MENU COMMANDS:
.sp
At the "like>" prompt, there are various interactive commands, summarized below.
.sp
.ls Invoke 
Help menu
.le
.ls B 	
Evaluate Gbias for fixed value of Counts and position with extant value of Gmult.
.le
.ls BB	
Evaluate Gbias with extant values of Counts, Gmult and position.
.le
.ls C 	
Evaluate Counts for fixed position with extant values of Gmult and Gbias.
.le
.ls CB 	
Evaluate Counts and Gbias simultaneously for a fixed position with the extant value of Gmult.
.le
.ls CBB 	
Evaluate Counts and Gbias with extant values of Gmult and position.
.le
.ls CC	
Evaluate Counts with extant values of Gmult, Gbias and position.
.le
.ls E	
Re-select the energy range.
.le
.ls G	
Evaluate Gmult for fixed values of Counts and position with the extant value of Gbias.
.le
.ls GB	
Evaluate Gmult and Gbias simultaneously for a fixed value of Counts and position.
.le
.ls GBB	
Evaluate Gmult and Gbias with extant values of Counts and position.
.le
.ls GBC	
Evaluate Grnult, Gbias, and Counts simultaneously for a fixed position.
.le
.ls GC	
Evaluate Gmult and Counts simultaneously with fixed value of Gbias.
.le
.ls GG	
Evaluate Gmult with extant values of Counts, Gbias, and position.
.le
.ls L	
Evaluate  Gmult, Gbias, Counts, and TS for a fixed position.
.le
.ls LC	
Evaluate a likelihood ratio test for source positions listed in an input catalog file.
.le
.ls LE	
Invoke likelihood position error analysis using elipsoidal fitting.
.le
.ls LL	
Evaluate Gmult, Gbias, Counts, and TS for the extant position.
.le
.ls LM	
Optimize the values of Gmult, Gbias, and Counts for active PSF sources.
.le
.ls LN	
Test the significance of the extant source as an additional PSF source commands</
.le
.ls LPE	
Perform error analysis for extant source or PSF sources using equivalent area error circles.
.le
.ls LPF 	
Find max TS for sources contained in a file.
.le
.ls LPM 		
Create fine maps for active PSF sources.
.le
.ls LPMS 
Perform search of the ROI for point sources.
.le
.ls LPO[] 		
Optimize max TS positions for active PSF.
.le
.ls LPR[]		
Create report for all source locations in PSF map.
.le
.ls LPS[] 		
Find the position max TS for a single test point source input.
.le
.ls MF 	
Create a fine map of likelihood.
.le
.ls MG 	
Create  a map of Gmult and Counts with fixed Gbias.
.le
.ls MH 	
Create a TS, Gbias, and Counts map with fixed Gmult.
.le
.ls MS 	
Create a map of the likelihood TS, Gmult, and Gbias.
.le
.ls OMC 	
Output a FITS file of the counts map.
.le
.ls OME 	
Output a FITS file of the exposure map.
.le
.ls OMG 	
Output a FITS file of the diffuse model as flux.
.le
.ls OMGC 	
Output a FITS map of the diffuse model as counts.
.le
.ls OMR 	
Output a FITS file of the normalized residual counts.
.le
.ls OMRC 	
Output a FITS file of the residual counts.
.le
.ls OMRF	
Output a FITS file of the residual flux.
.le
.ls OP 	
Produce a profile plot for the defined ROI.
.le
.ls PA 	
Invoke PSF adjustment menu.
.le
.ls PB 	
Command to reset, or add Gbias to the diffuse model.
.le
.ls PG 	
Adjust the spectral index used to construct the PSF.
.le
.ls PR	
Adjust range of likelihood analysis (Ranal).
.le
.ls PMC 	
Change coordinate system label.
.le
.ls PMF	
Read an array into the PSF array.
.le
.ls PML 	
Change limit confidence. 
.le
.ls PMM 	
Change output filenames. 
.le
.ls PMN	
Adjust Gmult_nom or Gbias_nom.
.le
.ls PMP	
Toggle the PUBLISH flag.
.le
.ls PMV	
Toggle VERBOSE flag.
.le
.ls PMR	
Change Gmult or Gbias parameter restrictions.
.le
.ls PMS	
Toggle SPECTRAL flag. 
.le
.ls PMT	
Adjust TS_min & TS_max. 
.le
.ls PMX	
Change extant value of counts, Gmult, Gbias, or position.
.le
.ls Q	
Quit.
.le
.ls S	
Adjust or reset the ROI range.
.le
.ls Z	
Read like commands from a script.
.sp
.sp
.ih
PARAMETERS
.ls datadir [string]
name of directory containing FITS count and exposure maps as well as the standard diffuse map
.le
.ls calibdir [string]
name of directory containing FITS calibration files
.le
.ls tempfildir [string]
location to put temporary files generated during the program execution
.le
.ls cmapfile [string]
name of the input FITS counts map
.le
.ls emapfile [string]
name of the input FITS exposure map
.le
.ls gmapfile [string]
name of the input FITS diffuse background map
.le
.ls ranal [real]
desired radius for analysis (typically 10-15 degrees)
.le
.ls lmapfile [string]
name of the output file for maximum likelihood analysis; often not needed
.le
.ls gbiasfile [string]
name of the output file for gbias map; often not needed
.le
.ls miscdir [string]
name of directory containing miscelaneous files
.le
.ls egretdoc [string]
path to EGRET document directory; generally not used
.le
.ls phase0 [string]
user defined path
.le
.ls 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)
.le
.ls phase2 [string]
path to cycle 2 FITS directory
.le
.ls phase3 [string]
path to cycle 3 FITS directory
.le
.ls phase4 [string]
path to cycle 4 FITS directory
.le
.ls phase5 [string]
path to cycle 5 FITS directory
.le
.ls phase6 [string]
path to cycle 6 FITS directory
.le
.ls phase7 [string]
path to cycle 7 FITS directory or user defined path
.le
.ls phase8 [string]
path to cycle 8 FITS directory or user defined path
.le
.ls phase9 [string]
path to cycle 9 FITS directory or user defined path
.le
.ls phase10 [string]
path to cycle 10 FITS directory or user defined path
.ih
EXAMPLES  
.sp
.nf
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>
.fi
.sp
.ih
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:
.sp
.nf
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)
.fi
.sp
.ih
BUGS
.ih
SEE ALSO

.endhelp








