NAME
    gtexpcube - Generates an exposure map, or a set of exposure
    maps for different energies.


USAGE
    
    gtexpcube infile evfile cmfile outfile irfs nxpix nypix 
    pixscale coordsys xref yref axisrot proj emin emax enumbins
    bincalc 


DESCRIPTION

The gtexpcube provides an alternative method for producing binned
exposure map. Normally, this is done automatically by gtsrcmaps
(see the gtsrcmaps help). gtexpcube generates an exposure map or
a set of exposure maps for different energies, multiplying 
effective area by exposure, and integrating over solid angle. 
To create an exposure map with gtexpcube you will need to generate
an exposure live-time cube file. This file can be created using
gtltcube (see the gtltcube documentation for a description of
the livetime cubes, and additional details).
Alternatively, pre-generated exposure cubes can be obtained
directly from the FERMI Science Support Center (FSSC) website.
Those pre-existing exposure cube files may cover the sky region
of interest at different time ranges and thus may need to be 
merged before running gtexpcube. To add two livetime cubes together
you may use the gtltsum tool (see the gtltsum help for more
information). You can also create an exposure map from each livetime
cube and then add the resulting exposure maps, but map generation
is CPU intensive and it is recommended to combine the cubes before
creating the maps.  

You will also need to provide as input to gtexpcube the number
of pixels in horizontal and vertical dimensions (nxpix and nypix
parameters respectively), the image scale in degrees/pixel (pixscale
parameter), the response function (irfs parameter) as well as the
horizontal and vertical positions of the center of the image
(xref and yref parameters respectively in Galactic or Celestial
coordinates accordingly to the coordsys parameter, which can be GAL
or CEL). The energy binning parameters should be input as well (emin
in MeV , emax in  MeV, enumbins parameters). Optionally, a counts map
FITS file generated with gtbin (see the gtbin help), from which
gtexpcube will match the coordinate projection and grid, could be
input in gtexpcube to produce the exposure map.

The units of the exposure maps created by gtexpcube are: cm^2 s^1.
  
After creating the exposure map you can examine the results using,
for example, ds9 (http://hea-www.harvard.edu/RD/ds9/) or fv
(http://heasarc.gsfc.nasa.gov/lheasoft/ftools/fv/).

 
PARAMETERS

infile [file]
Exposure Livetime cube file. FITS file containing live-time as a
function of sky position and off-axis angle. This file should be
generated by gtltcube (see the gtltcube help for further explanation)
or be provided by the FSSC website.

evfile [file]
Name of input event FITS file. This is the file containing the event
data. 
The LAT data will be available in from the FERMI Science Support
Center data server.
 	 	 
cmfile [file]
       This is the count map input FITS file. This file should be generated
       using gtbin (see the gtbin documentation). You should select "NONE"
       if you wish to specified the map geometry from parameters (nxpix, nypix,
       xref, yref, enumbins, etc).
	 	 
outfile [file]
	This is the name of the Exposure Map output FITS file.
 	 	 
irfs [string]
         Instrument response functions. The instrument response (PSF, effective
         area, energy resolution) is currently a function of energy,
         inclination angle (the angle between the source and the LAT normal)
         and photon category. Since the LAT will usually survey the sky, a
         source will be observed at different inclination angles. Each count
         will therefore be characterized by a different instrument response
         function (IRF). The default value is “CALDB”.

nxpix = 1 [int]
      The number of pixels in the horizontal dimension in the output image.
      You may use the default value "1" for full sky, if proj (see the proj
      parameter description) is one of "CAR","AIT", or "ZEA".
	 	 
nypix = 1 [int]
      The number of pixels in the vertical dimension in the output image.
      You may use the default value "1" to create a full sky if proj is one of
      "CAR","AIT", or "ZEA", or to use the same value as specified for nxpix.

pixscale = 0.5 [float]
	 Image scale (in degrees/pixel). The default value is 0.5. You should
	 decide this value according to your needs.
	 	 
coordsys = "CEL" [string: CEL|GAL]
	 Coordinate system. If you choose CEL you will be prompted for RA
	 and DEC (J2000) in the xref and yref parameters; if you choose GAL
	 you will be prompted for l and b coordinates. 
 	 	 
xref = 0. [float]
     The horizontal position of the center of the image, either RA in
     celestial coordinates or l in Galactic coordinates (decimal degrees).
     The default value is 0.
 	 	 
yref = 0. [float]
     The vertical position of the center of the image, either DEC in
     celestial coordinates or b in Galactic coordinates (decimal degrees).
     The default value is 0.
 	 	 
axisrot = 0. [float]
	The rotation angle desired for the image in degrees. 
	The default value is 0.
 	 	 
proj = "AIT" [string: AIT|ARC|CAR|ZEA|GLS|MER|NCP|SIN|STG|TAN]
     Desired coordinate projection: Aitoff [AIT], Zenithal equal- area
     [ZEA], Zenithal equidistant [ARC], Plate Carree [CAR], Sanson-Flamsteed
     [GLS], Mercator [MER], North-Celestial-Pole [NCP], Slant orthographic
     [SIN], Stereographic [STG], Gnomonic [TAN]. 
     See Calabretta & Greisen 2002, A&A, 395, 1077 for definitions of
     the projections.  Must be AIT, ZEA, or CAR for auto full sky.
     The default value is AIT.

emin = 30 [float]
     Lower boundary for first energy bin in MeV. 
     The default value is 30 MeV.
 	 	 
emax = 200000 [float]
     Upper boundary for last energy bin in MeV. 
     The default value is 200 GeV. 
	 	 
enumbins = 8 [int]
	 Number of logarithmically spaced energy bins spanning emin to emax.
	 The default value is 8.
 	 	 
bincalc = "CENTER" [string: CENTER|EDGE] 	 	
	This parameter allows you to choose how energy layers are computed from
	the count map (cmfile parameter) energy bounds.
	The options are CENTER and EDGE. 
	The default value is CENTER.  
	 	 
(table = "Exposure") 
       Exposure cube extension. This is a hidden parameter. The default value is
       "Exposure".

(evtable = "EVENTS")
	 FT1 events extension.

(chatter = 2)    
	 Output verbosity. This is a hidden parameter. The default value is 2.

(clobber = yes) 
	 If true, an existing file of the same name will be
	 overwritten. This is a hidden parameter. The default value is
	 "yes".

(debug = no)
       Activate debugging mode. This is a hidden parameter. The
       default value is "no". When debug is "no", all exceptions that
       are not caught and handled by individual tool-specific code are
       caught by a top-level exception handler that displays
       information about the exception and then exits.  When debug is
       "yes", such exceptions are not caught by the top level code.
       Instead the tool produces a segmentation violation, which is
       more useful for debugging. When debugging mode is enabled, the
       tool produces more verbose output describing any errors or
       exceptions that are encountered.

(gui = no)
     Graphical user Interface (GUI) mode activated if "yes" is specified. 
     This is a hidden parameter. The default value is "no".

(mode = ql) 
      Mode of automatic parameters. This is a hidden parameter.
      The default value is "ql".

       
EXAMPLES

Parameters are passed following the FTOOLs model: They can be passed
interactively in response to a prompt, a listed in a command line, or by
editing the parameter file. 
 
To run gtexpcube interactively simply type in the command line: 

>gtexpcube
 
You will then be prompted for parameter values. Beware that not all
parameter are prompted: some of them are "hidden".  If you want to
change one of the "hidden" parameter you should specify the values in
the command line. For example if you want to change the clobber parameter
type in the command line: 
 
>gtexpcube clobber=no


Example 1:

To generate an exposure map using a single exposure cube simply run the
gtexpcube tool which allows you to control the map generation parameters,
including: Map center, size, scale, projection type, energy range, and
number of energy bins.

The following example shows how to generate an all sky exposure map in
an Aitoff projection. 

>gtexpcube
This is gtexpcube version N/A
Exposure cube input file name[] expCube_allsky_1week.fits
FT1 events input file name[] allsky.fits
Count map input file name (NONE for manual input of map geometry)[NONE]
Exposure map output file name[] exposuremap.fits
Response function to use. Run gtirfs for a list[] CALDB
Size of the X axis in pixels (leave at 1 for auto full sky (1:) [1] 
Size of the Y axis in pixels (leave at 1 to copy nxpix or auto full sky) (1:) [1]
Image scale (in degrees/pixel) (1.:) [1] 
Coordinate system (CEL - celestial, GAL -galactic) (CEL|GAL) [CEL] GAL 
First coordinate of image center in degrees (RA or galactic l)[0] 
Second coordinate of image center in degrees (DEC or galactic b)[-90] 0 
Rotation angle of image axis, in degrees[0] 
Projection method (AIT|ARC|CAR|ZEA|GLS|MER|NCP|SIN|STG|TAN) [ZEA] AIT
Start value for first energy bin[100] 
Stop value for last energy bin[100000] 
Number of logarithmically uniform energy bins[4] 
How are energy layers computed from count map ebounds? (CENTER|EDGE) [CENTER] 
Creating an Exposure object from file expCube_allsky_1week.fits
Using Aeff(s) 
Combining exposure from the response function(s), specified by "P6_V3_DIFFUSE": 
        P6_V3_DIFFUSE::FRONT
        P6_V3_DIFFUSE::BACK
        
Cutoff used: 0.406737
Creating an Image, will write to file exposuremap.fits
Generating layer 0 at energy 208.114 MeV  Aeff(0): 3509.08 cm^2
Generating layer 1 at energy 658.114 MeV  Aeff(0): 6255.7 cm^2
Generating layer 2 at energy 2081.14 MeV  Aeff(0): 7129.67 cm^2
Generating layer 3 at energy 6581.14 MeV  Aeff(0): 7394.34 cm^2
      

You are prompted for an exposure cube, which in this case is called 
expCube_allsky_1week.fits, and it was previously created using gtltcube 
(see the gtltcube help). In the example the geometry was entered by hand, 
so "NONE" was selected in the cmfile parameter. After that, the output FITS
file name and the irfs was specified. A map of the entire sky was created,
with 1 degree bins centered on Galactic Coordinates l=0, b=0. A total number
of 4 energy logarithmic bins were selected starting from an energy of 100 MeV
and ending in 100 GeV.

Once the output exposure FITS file has been generated, it can be viewed with
a FITS viewer such as ds9 or fv.  It contains a data structure with layers
corresponding to the number of bins specified. 

That last example could be also run in the command line as follows:

>gtexpcube infile= expCube_allsky_1week.fits cmfile=NONE outfile=
exposuremap.fits irfs=CALDB nxpix=1 nypix=1 pixscale=1 coordsys=GAL
xref=0 yref=0 axisrot=0 emin=100 emax=100000 enumbins=4 bincalc=CENTER

Example 2:

To generate an exposure map using a count map as input you should first create
that count map using the gtbin tool (see the gtbin documentation).
Below an example of how to run the tool by inputting a count map is given:

>gtexpcube
This is gtexpcube version N/A
Exposure cube input file name[] expCube_allsky_1week.fits
FT1 events input file name[NONE]allsky.fits 
Count map input file name (NONE for manual input of map geometry)[NONE] allsky_cnts.fits
Exposure map output file name[] exposuremap_withcntmap.fits
Response function to use. Run gtirfs for a list[]CALDB
Image properties copied from file allsky_cnts.fits
How are energy layers computed from count map ebounds? (CENTER|EDGE) [CENTER] 
Creating an Exposure object from file expCube_allsky_1week.fits
Using Aeff(s) 
Combining exposure from the response function(s), specified by "P6_V3_DIFFUSE": 
        P6_V3_DIFFUSE::FRONT
        P6_V3_DIFFUSE::BACK
        
Cutoff used: 0.406737
Creating an Image, will write to file exposuremap_withcntmap.fits
Generating layer 0 at energy 60.09 MeV  Aeff(0): 44.6284 cm^2
Generating layer 1 at energy 180.63 MeV  Aeff(0): 3001.03 cm^2
Generating layer 2 at energy 542.974 MeV  Aeff(0): 5834.65 cm^2
Generating layer 3 at energy 1632.18 MeV  Aeff(0): 7144.48 cm^2
Generating layer 4 at energy 4906.32 MeV  Aeff(0): 7208.28 cm^2
Generating layer 5 at energy 14748.4 MeV  Aeff(0): 7707.91 cm^2
Generating layer 6 at energy 44333.6 MeV  Aeff(0): 8329.42 cm^2
Generating layer 7 at energy 133267 MeV  Aeff(0): 8058.14 cm^2


All the binning parameters (in energy and space) are taken directly from the 
count map, in this case, named allsky_cnts.fits. The user should enter the
live-time cube file (previously created with gtltcube), the irfs name, and
the name of the output exposure FITS file as input.


KNOWN BUGS



SEE ALSO


    * gtbin

    * gtltcube

