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