gtophase Help File

Usage: gtophase evfile scfile psrdbfile psrname ra dec

Computes an orbital phase for each event in input event
file(s), and writes it to a FITS column in the file(s).

This tool operates on input event file(s) to compute an orbital phase for a photon arrival time of each event, and writes it to, by default, PULSE_PHASE column of the event file(s). If necessary, this tool reads the spacecraft orbit file and performs the barycentric correction and the binary demodulation to each photon arrival time on the fly.

Example: gtophase

gtophase automatically extracts one or more ephemerides from an existing pulsar ephemerides database file. Unlike the similar gtpphase tool, there is no option for entering orbital ephemerides manually. This tool does not produce a separate output file, but operates directly on the input file in place. If execution is successful, the tool produces no textual output.

gtorbsim Help File

Usage: gtorbsim start_MJD stop_MJD Timeline EphemName EphemFunc Resolution Units Initial_Ra Initial_DEC OutPutFile saafile saafunc

Generate spacecraft orbit and attitude data for a variety of pointing or survey mode strategies.

The GSSC Orbit Simulator, gtorbsim, is a spacecraft attitude calculator based on the code already implemented in the general purpose scheduling and planning system TAKO (Timeline Assembler Keyword Oriented) at the GLAST Science Support Center. The simulator inherits many features of TAKO, but it does not have any scheduling capabilities. The main purpose of this simulator is:

• To calculate spacecraft attitude, that is where the local body frame axes are oriented relative to the sky.

• To determine when events such as entry/exit in South Atlantic Anomaly (SAA) will take place.
  
  The above must be accomplished starting with a series of pointing commands. The output of the orbit simulator is a FITS spacecraft data file.

Several SAE tools such as gtobssim, gtltcube, gtlike, etc. require the spacecraft data file as input. You may use the spacecraft data file provided by the GSSC, but in many cases you will probably need to generate that file if you want to perform a particular analysis of simulated data.

The first input you will have to provide to gtorbsim is the observation mode strategy. Several operational modes are planned for GLAST, but the spacecraft will acquire scientific data only in survey and pointed modes.

The sky survey mode is basically zenith pointed throughout the orbit and has two sub modes:

• With rocking.

• Without rocking.

Rocking provides more uniform sky coverage and allows for complete sky coverage within a shorter period of time. Different rocking profiles may be implemented, (square or sinusoid) with a basic 2-orbit period and a 60-degree maximum amplitude (above and below the orbit plane).

In pointed observation mode, the Z-axis of the observatory is commanded to point at a celestial target. An observing sequence is implemented via a series of commanded targets. There are two sub modes for observing any given target:

• Target tracking.

Target tracking mode maintains a commanded celestial target within a 60-degree diameter field of view. The target is allowed to drift at about 1 degree/minute across this field of view during the non-occulted part of the orbit.

• Target inertial.

Target inertial mode maintains the Z-axis on the target to within the 2-degree control capability of the spacecraft. This mode may be interrupted for downlink transmissions of science data. In this mode, Earth avoidance is accomplished via stored commands that keep the field of view on the sky while the target is occulted. Alternatively, an automatic earth avoidance capability may be used.

Even though it will be possible to do pointed observations, the large FOV of the LAT will provide such extensive data on individual sources that it will be difficult to justify modes of observation other than sky survey. For that reason, it is expected that GLAST will operate in sky survey mode ~90% of the time.

With the gtorbsim tool you may choose to calculate the attitude in survey or pointed mode. In survey mode, you may chose between two options:

• In fixed survey mode, the spacecraft does a sky survey with a specified offset with respect to its local zenith for one orbit, and then uses the opposite offset for the next orbit, and so on.

or

• In profiled survey mode, the spacecraft observes in survey mode according to a specified profile consisting of 17 increasing times and 17 zenith offsets. The 17 increasing times (in seconds) are used to indicate the time that it takes during each cycle to go from a corresponding zenith offset to the next. The 17 angles (in degrees) are the zenith offsets reached at the end of the corresponding time interval. The first and last of these offsets must be identical in order for the profile to be repeated.

On the other hand, in pointed mode the spacecraft stares at a specified location in the sky identified by an RA and DEC provided by the user.

In order to properly calculate the attitude, the orbit simulator needs to know the spacecraft position in the entire interval of interest. Therefore, it must be capable of either reading in a file
that contains the spacecraft ephemeris, or calculating one on the fly.

The orbit simulator can handle three different types of ephemeris files:

• NASA Flight Dynamic Facility (FDF) format, already used for missions such as RXTE.

• Satellite Tool Kit (STK) format, already in use for SWIFT.

• NORAD Two Line Elements, in which case the spacecraft position is calculated on the fly. (See NORAD Two-Line Elemet Sets Current Data.)

In addition, the initial spacecraft position in celestial coordinates should be provided by the user as an input parameter.

The South Atlantic Anomaly region:

The instrument high voltage power supplies will be protected when the spacecraft traverses the South Atlantic Anomaly (SAA). This will occur about 15% of the time.

gtorbsim has the capability to handle SAA constraints. The SAA region is appoximated by a polygon, which is specified by the Longitude and Latitude of its vertices. It is passed to the program as an input file where the specification of the polygon is given. In cases where the
file is not available, a default hard-coded table of longitude and latitude pairs of vertices will be used.

Earth limb:

The Earth Limb Tracing maneuvering is an optional feature that can easily be enabled/disabled using the appropriate input parameter in gtorbsim. This maneuvering consists of tracing the Earth Limb if a target is Earth-occulted. Targets are assumed to be occulted if their Earth angle (Angle between target and the Earth's Limb) is smaller, or – at most – equal to 30 degrees. Once the target is occulted by the Earth, the orbit simulator finds when it is visible again, and where it is coming out from the Earth's Limb. The simulator then finds the angular separation between the in-occult and out-occult position. And finally, the orbit simulator allows the local z-axis to sweep equal angles in equal times during its motion along the Earth's Limb.

Generally, when using TAKO Science timelines, this step is not necessary since the TAKO avoids scheduling any target during occultation time. However, in special cases, the occultation constraint in TAKO can be intentionally disabled to achieve some observational goal. Consequently, the orbit simulator calculates the occultation times, and then performs the Earth Limb tracing maneuvering. The occultation times are calculated using the same algorithm that TAKO uses.

Example: gtorbsim

The orbit simulator is designed so that inputs can be passed using the existing SAE infrastructure: by answering a prompt; as a list in a command; or using an input file. For this reason, the very first input of the simulator is the type of input, which can either be "console" or "file".

To be prompted for gtorbsim parameter values, enter (at the command line): gtorbsim

Note: "Hidden" parameters are not prompted. If you want to override one of the "hidden" parameters, specify the values in the command line. For example, if you do not want to overwrite the output file, set the clobber parameter "clobber=no" ( e.g., gtorbsim clobber=no).

An example of how to run the tool from the console for 55 days of survey mode operation is given below:

The same task could be performed from an ini file like this:

gtpsearch Help File

Usage: evfile scfile psrdbfile psrname outfile algorithm numphase
numharm maxharm scanstep numtrials timeorigin usertime
userformat usersys ephstyle ephepoch timeformat timesys
ra dec f0 f1 f2 p0 p1 p2

Searches for pulsations at frequencies near to a known, guessed or estimated reference frequency.

This tool searches for pulsations in data which is known or suspected to have a pulsation of a known approximate period or frequency. It is not useful for a so-called blind period search, in which data are examined for pulsations at any frequency. The
tool supports several test statistics available, including Chi-squared (X2), Z- squared-n ( Z2N), H, and Rayleigh (Z2N with N == 1). Ephemeris information can be given in one of the following forms:

• Manually input the source (pulsar) location (for the barycentric correction), pulse frequency or period, and related information.

• Automatically extracted from a pulsar ephemerides database, available online. If necessary, this tool reads the spacecraft orbit file and performs the barycentric correction, the p-dot cancellation, and the binary demodulation to each photon arrival time on the fly.

Example: gtpsearch

Performing a period search is straight forward if the object of interest is listed in a pulsar ephemerides database file. The example below shows how to perform the test under these
circumstances using the files described above. The time origin of periodicity test is taken to be the center of the observation. That means, if a pulsation is found, the pulse frequency should be interpreted as measured at the center of the observation (i.e., the time origin).

This command produces the following output message that describes the search criteria and explains the search result. A plot will also be produced.

gtpsf Help File

Usage: gtpsf expcube outfile irfs ra dec emin emax nenergies thetamax ntheta

Calculates the effective point spread function, as a function of energy at a given source location, averaged over an observation.

This tool calculates the effective point spread function, as a function of energy at a given source location, averaged over an observation. The theta and psf values are storaged in different extensions of the output FITS file. The allowed parameter ranges for emin, emax, and thetamax depend on which IRFs you are using. If you are outside the allowed ranges for a particular set of IRFs, then the code may (but not definitely) crash.

Example: gtpsf

gtpsf handles parameters following the FTOOLs model: They can be passed by answering a prompt for the parameter values, or as a list in a command line. This facilitates calling gtpsf from a script.

To be prompted for gtpsf options, enter (at the command line): gtpsf

Note: "Hidden" parameters are not prompted. If you want to change one of the "hidden" parameters, specify the values in the command line. For example, if you do not want to overwrite the output file, enter (at the command line): gtpsf clobber=no

An example of how to run the tool is given below:

The example above could also be run from the command line as follows:

>gtpsf expcube=expCube_2m.fits outfile=psf.fits irfs=Pass4_v2 ra=50
dec=-37 emin=20.0 emax=200000.0 nenergies=8 thetamax=30 ntheta=300

gtpspec Help File

Usage: evfile scfile psrdbfile psrname outfile binwidth numbins timeorigin usertime userformat usersys ra dec ephstyle f1f0ratio f2f0ratio p1p0ratio p2p0ratio

Searches for pulsations in wide frequency range using the Discrete Fast Fourier Transfer (FFT) technique.

gtpspec searches for pulsations in a relatively wide range of frequencies. It uses the Discrete Fast Fourier Transfer (FFT) technique to compute power spectrum density. This tool is suitable for a so-called blind period search, in which data are examined for pulsations at any frequency. Ephemeris information can be given in one of the following forms:

• Manually input the source (pulsar) location (for the barycentric correction), pulse
  frequency or period, and related information.

• Automatically extracted from a pulsar ephemerides database, available online. If necessary, this tool reads the spacecraft orbit file and performs the barycentric correction, the p-dot cancellation, and the binary demodulation to each photon arrival time on the fly.

Example: gtpspec

The example below shows how to perform a pulsation search in the simplest case, where one can assume no significant frequency variations exist throughout the observation. The time origin of
this search is taken to be the center of the observation. That means, if a pulsation is found, the pulse frequency should be interpreted as measured at the center of the observation (i.e.,
the time origin).

This command produces the following output message that describes the search criteria and explains the search result. A plot will also be produced.

gtptest Help File

Applies statistical tests to a series of pulse phase values stored in
given even t file(s).

Usage: gtpspec evfile outfile numphase numharm maxharm

gtptest applies all the statistical tests available with gtpsearch application to a series of pulse phase values stored in given even t files. The tool supports several test statistics available, including Chi-squared (X2), Z-squared-n ( Z2N), H, and Rayleigh (Z2N with N == 1).

Example: gtptest

The example below shows how to perform periodicity tests on an event file that has been processed by gtpphase application, where a pulse phase has already been assigned to each photon and is stored in a default FITS column (PULSE_PHASE column).

This command produces the following output message that describes the types and the parameters of the periodicity tests that are performed, and explains the test results. A plot will also be produced, which shows a folded-light curve used in the chi-squared test.

gtpulsardb Help File

Usage: gtpulsardb psrdbfile outfile filter psrname tstart tstop solareph

Creates, filters, and/or combines pulsar ephemerides database files.

gtpulsardb is a utility for manipulating and accessing databases containing pulsar ephemeris data. Using this tool, one can accept input from any number of FITS files in the GLAST D4 format, and/or simple text files containing pulsar data. These input pulsar ephemerides can be filtered by pulsar name and other criteria, and the results stored in a new GLAST D4 FITS file.

Example: gtpulsardb

In the following example, the tool filters an ephemerides file to extract only ephemerides for a particular pulsar as follows:

The name supplied in the example was simply "Crab", but in general the "B-name" or "J-name" may be used as well as common names such as "Crab" or "Vela". Colloquial names and B-names are looked up using the ALTERNATIVE_NAMES extension to obtain the correct J-name, which is then used to look up ephemerides in the SPIN_PARAMETERS and/or ORBITAL_PARAMETERS.

In order to merge two or more ephemerides files, it is necessary to supply more than one file name through the psrdbfile parameter. This is done using the "at-file" syntax familiar to
Ftools users, in which the file names are written into a text file, and that text file is supplied to gtpulsardb with a prepended at-sign (@).

gtrspgen Help File

Usage: gtrspen respalg specfile scfile outfile irfs time thetacut dcostheta ebinalg emin emax enumbins denergy ebinfile

Creates a "Detector Response Matrix" (DRM or RSP) FITS file from the multi-dimensional response functions.

gtrspgen produces a Response Matrix (RSP) file required to analyze a binned spectrum in an OGIP-standard format. The response matrix is computed from the detailed response functions provided by the LAT instrument team. The elements of the matrix are directly related to the probability of an incident photon with a true energy of E being detected by the LAT with an apparent energy E'. The source position, the observation time, and energy grid are extracted from a PHA1 (spectrum) file, while the pointing/livetime history file provides the instrument orientation during the observation. The gtrspgen tool has two main options:

• GRB for short observations during which the instrument's pointing does not change significantly. This is relevant for most gamma-ray burst observations.

• PS for an observation relevant to a point source over more than a fraction of an orbit, requiring that the instrument response be averaged over the different source directions in instrument coordinates.

Two input files are required:

• A pointing history file covering the time of the observation, which can be obtained from the GLAST Science Support Center (GSSC) web site.

• A PHA1 file, which can be created using the gtbin tool (see gtbin help).

In binned spectral analysis, the apparent energies are binned. For the LAT data, the data have to be binned into energy channels (a PHAI file) using, the gtbin tool. But the first step in the analysis is to select all the counts from a region of 10 to 15 degrees around the burst position from the time range that includes the burst. These counts can be selected using the gtselect tool. For further information on how to perform a Binned GRB Spectral analysis using the LAT data, it is highly recommended that you read the Cicerone Manual, and/or the workbook.

Example: gtrspgen

Parameters are passed followinb the FTOOLs model: by answering from a prompt; as a list in a command line; or by editing the parameter file.

To be prompted for gtrspgen parameter values, enter (at the command line): gtrspgen

Note: Not all parameters are prompted: some of the parameter are "hidden". If you want to change one of the "hidden" parameter you should specify its value in the command line. For example if you do want to open the GUI option enter (at the command line): gtrspgen gui=yes

An example of how to run the gtrspgen tool is given below:

In this case, the GRB option was chosen. The spectrum file was generated previously with gtbin with the name: GRB.pha.

The same task can also be run from the command line as follows:

>gtrspgen respalg=GRB specfile=GRB.pha scfile=SC2_FT2_v2.fits
outfile=GRB.rsp time=252374400 irfs=Handoff ebinalg=LOG emin=30
emax=200000 enumbins=100

gtselect Help File

Synopsis:

Performs sub-selections of event data.

Usage: gtselect infile outfile ra dec rad tmin tmax emin emax eventClass

gtselect creates a new FITS file of selected rows from an input event data file based on user-specified cuts that are applied to each row of the input file. This application enables detailed selections to be made on data obtained from the GSSC data server or generated using
gtobssim, the tool that generates simulated data (see gtobssim help).

The most common selections are these involving time range (minimum and maximum time) and energy range (minimum and maximum energy). For each cut that is applied Data Subspace (DSS) keywords are written to the EVENTS header of the output FITS file that describe the selection.

This information is used by the likelihood tools and gtrspgen for computing exposure-related information. Furthermore, there are several selections that this tool will make that are
deprecated, since it is not anticipated that the downstream tools will be able to account for them (even with the DSS keyword information).

Example: gtselect

Parameters are passed followinb the FTOOLs model: by answering from a prompt; as a list in a command line; or by editing the parameter file. The command line option facilitates calling gtselect from a script.

To be prompted for gtselect parameter values, simply type in the command line: gtselect

Note: Not all parameters are prompted: some of the parameter are "hidden". If you want to change one of the "hidden" parameter you should specify its value in the command line. For example, if you do not want to overwrite the existing output file, enter (at the command line): gtselect clobber=no

An example of how to run the tool is given below:

In this case, quasar 3C279 (centered on Ra=193.98, Dec=-5.82) was simulated using gtobssim (see gtobssim for further explanation) with a photon spectral index of 1.96, an integrated flux of 3.48e-4 m^-2s^-1, until a radius of 40 degrees . The energy for the simulated events ranges between 20 MeV and 200000 MeV. Using gtselect it possible to select the events with energy larger than 100 MeV and within a radius of 20 degrees centered on Ra=193.98, Dec=-5.82 and a time range between 220838400 and 225590400 MET seconds:

The above example can also be run from the command line as follows:

> gtselect infile=3C279_events_0000.fits outfile=3c279_filtered.fits
ra=193.98 dec=-5.82 rad=20 tmin=220838400 tmax=225590400 emin=100
emax=200000 eventClass=-1

gtsrcid

Creates a counterpart candidate catalog by correlating the objects from a list of detected sources with the objects of an existing source catalog, such as the 3EG catalog.

Usage: gtsrcid srcCatName srcCatPrefix cptCatName cptCatPrefix outCatName probMethod probThres maxNumCpt

The gtsrcid tool is an application that finds counterparts for a list of detected sources using a catalog of potential counterparts.

The source catalog, as well as the counterpart catalog, should be either in FITS or TSV (tab-separated values) format. The output counterpart candidate catalog will be in FITS format. A log file (gtsrcid.log) containing detailed information about the counterpart identification is generated and placed at the location where gtsrcid was executed.

The method used to define the counterpart probability (or function of merit) may be either POSITION (e.g. the probability of positional coincidence), or any output catalog quantity that can be parameterized as a probability between 0 and 1 (see details in probMethod parameter
description).

The counterpart probability assigned by gtsrcid is defined as:

P = P_pos * P_add * (1 - P_chance)

where

P_pos is the positional coincidence probability, P_add any additional probability (see below), and P_chance is the chance coincidence probability.

The positional coincidence probability is based on the assumption that the source location uncertainties can be modeled by a 2-dimensional normal distribution. In the most general form, the location uncertainty is described by an error ellipse, parameterized by the major and
minor axes and the position angle (measured counterclockwise from celestial north).

The user is allowed to enter a maximum number of counterpart candidates per source to be included in the output catalog (see the description of maxNumCpt parameter). Selection criterion on output catalog quantities can also be entered.

Although gtsrcid is designed to digest a large variety of different catalog types and formats, a certain number of rules have to be satisfied for gtsrcid to work properly:

1) Source position. Knowledge of source position is mandatory for gtsrcid to work. So far, only celestial coordinates are supported (Right Ascension and Declination).

The gtsrcid tool tries to find this information by first searching for columns with the Unified Content Descriptors POS_EQ_RA_MAIN and POS_EQ_DEC_MAIN. If those are not found, the following column name pairs are searched for (in the order shown): Radeg/DECdeg, RAJ200/DEJ200,_RAJ2000/_DEJ2000, or RA/DE.

2) Position uncertainties. No generic UCDs exist for this information, and the application searches for specific column names.

First, elliptical errors regions are searched for by looking for the column names:

• Conf_95_SemiMayor/Conf_95_SemiMinor/Conf_95_PosAng (for 95% error ellipses),
• Conf_68_SemiMayor/Conf_68_SemiMinor/Conf_95_PosAng (for 68% error ellipses), and
• Declination is searched for by looking for the column names:
  • e_RAdeg/e_DEdeg (for 1 sigma errors), and
  • e_RAJ200/e_DEJ200 (for 1 sigma errors).

Finally, circular errors are searched for by looking for the column names:

• theta95 (for 95 % errors), and
• PosErr (for 1 sigma errors).

If none of these column combinations has been found, the positional uncertainty will be taken from the parameters srcPosError (for the source catalog), and from cptPosError (for the counterpart catalog).

3) Sourcename. To keep track of the source information, each source should have a source name. The gtsrcid tool finds the source name by first searching for the UCD ID_MAIN. If no such UCD is found it then searches for columns named NAME or ID.

Output. gtsrcid produces a catalog of counterpart candidates. Each row (entry) of this catalog presents the association of an object of the source catalog with an object of the counterpart catalog. For a given object of the source catalog, several entries may be output, corresponding to the different possible counterparts that have been identified from the counterpart catalog. Each of the associations will have an assigned counterpart probability, allowing a judgment to be made on the reality of the proposed association. Each counterpart candidate in the output catalog is specified by:

• A unique name of the format CC_XXXXX_YYYYY, where XXXXX is the source number in the source catalog (starting from 1) and YYYYY is the running number of the counterpart candidate (starting from 1).

For example, the 2nd counterpart candidate of the 5th source of the source catalog will have the identifier CC_00005_00002. The unique name has the FITS column name ID and the UCD ID_MAIN.

• The coordinates of the counterpart candidate in Right Ascension and Declination for the epoch J2000 in units of degrees.

The FITS column names of the coordinates are RA_J2000 and DEJ2000, the UCDs are POS_EQ_RA_MAIN and POS_EQ_DEC_MAIN.

• The position uncertainty of the counterpart candidate in form of an error ellipse that defines the 95% confidence interval.

The major and minor axes of the error ellipse are stored in the columns POS_ERR_MAJ and POS_ERR_MIN in unit of degrees. T

he position angle, measured eastwards (or counterclockwise) from North in celestial coordinates, is stored in the column POS_ERR_ANG in units of degrees.

The UCD for all the three columns is ERROR.

• The counterpart candidate association probability in the range of 0 to 1.

The FITS column name of the probability is PROB.

Subsequent columns specify the probability based on the positional coincidence, which is also called the likelihood (stored in column PROB_POS); the product of any additional probabilities (stored in column PROB_ADD); and the chance coincidence probability (stored in column PROB_CHANCE).

• The position of the counterpart candidate with respect to the source is given in form of angular separation (stored in column ANGSEP in units of degrees) and the position angle, measured eastwards (or counterclockwise) from North in celestial coordinates (stored in column POSANG in units of degrees).

• The row of the counterpart in the counterpart catalog (stored in column REF).
  

The coordinates and positional uncertainty of the counterpart are those of the object that has the smaller positional uncertainty in either of the two input catalog.

In addition to the generic quantities, additional quantities may be copied from the input catalog to the output catalog. FITS columns for these copied quantities are preceded by @.

New information can be derived in the output catalog by combining information from quantities that are found in both input catalogs. For example, a spectral index may be calculated from the fluxes given at two energies or frequencies in the input catalog. These so called "derived quantities" will be added as final columns to the output catalog. Note that these derived quantities can also be used to specify additional probability laws.

For reading catalogs, gtsrcid makes use of the interface routines provided by the library catalogAccess. Consequently the catalog can be read in all formats that are supported by catalog Access. The gtsrcid tool writes the output catalog directly using cfitsio routines; thus, only the FITS format is supported on the output.

The gtsrcid tool creates an ASCII log-file in the directory where the executable is executed for the purpose of: logging errors that occurred during task execution; logging the actions that gtsrcid performed for the counterpart search in order to control the proper execution of the
task; and to provide a detailed report about the task execution in case the result looks suspicious to the user.

For astronomical catalogs see: The HEASARC Catalog or the VizieR Service websites.

Example: gtsrcid

Parameters are passed following the FTOOLs model: by answering from a prompt; as a list in a command line; or by editing the parameter file.

To be prompted for gtsrcid parameter values, enter (at the command line): gtsrcid

Note: Not all parameters are prompted: some of the parameter are "hidden". If you want to change one of the "hidden" parameter, specify its value in the command line. For example, it is possible to change the counterpart position by entering: gtsrcid cptPosError=0.01

There are several examples of how to run the tool in the workbook (see the LAT Science Tools section of the workbook --> Source Analysis - Source Identification); only one is reproduced here:

A catalog of LAT sources (for a simulated LAT sky) is compared to the Third EGRET Catalog.
In this case, you may run the gtsrcid tool as follows:

In this example the LAT Catalog is named:

LATSourceCatalog_v1.fits

while the counterpart Catalog is called:

3EG.fits

The name of the output catalog is data/DC2_LATSourceCatalog_v1-3EG.fits.

The position probability method was used (see formula 1). The name of the output catalog is
data/DC2_LATSourceCatalog_v1-3EG.fits. The position probability method was used (see formula 1). The maximum number of counterpart candidates selected was 1, and the probability threshold was 0.2.

gtsrcmaps Help File

Convolves source model components with instrument response.

Usage: gtsrcmaps scfile expcube cmap srcmdl bexpmap outfile irfs

gtsrcmaps convolves the components of the specified source model with the instrument response for a given observation. This tool is used as part of the GLAST binned likelihood analysis, so it is recommended that you read the gtlike help.

One of the inputs of this tool is a counts map, which should be created using the gtbin tool (see gtbin help).

The geometry in sky coordinates and energy binning of the output maps match that of the input maps.

Another input is the binned exposure map. If the binned exposure map file does not exist, then gtsrcmaps will compute an all-sky map using the name provided at the prompt and using the energy bands of the 3D counts map. This exposure map can be reused for subsequent analyses of regions that cover the same time range and that use the same energy binning.

Since the source map generation for point sources is fairly quick, and maps for many point sources may use a lot of disk space, it may be preferable to disable the generation of the source maps for point sources at this stage. If a source in the xml model is missing from the input source map file, gtlike will compute the maps on the fly. Relying on this mechanism is recommended only for point sources.

To skip generating source maps for point sources, specify "ptsrc=no" on the command line when running gtsrcmaps.

Example: gtsrcmaps

Parameters are passed followinb the FTOOLs model: by answering from a prompt; as a list in a command line; or by editing the parameter file.

To be prompted for gtsrcmaps parameter values, enter (at the command line): gtsrcmaps

Note: Not all parameters are prompted: some of the parameter are "hidden". If you want to change one of the "hidden" parameter you should specify its value in the command line. For example, if you want to skip generating source maps for point sources, enter (at the command line): gtsrcmaps ptsrc=no

An example of how to run the tool is shown below:

This example above could also be run from the command line as follows:

> gtsrcmaps scfile=SC2_FT2_v2.fits expcube=expCube_SC.fits
cmap= ps_counts.fits srcmdl=src_model.xml bexpmap=none
outfile=srcMaps.fits irfs=Pass4_v2

gttsmap Help File

Usage: gttsmap evfile scfile expmap expcube srcmdl outfile irfs optimizer ftol xref_min xref_max nx yref_min yref_max ny coordsys

Calculates test-statistic map for source localization and detection.

gttsmap computes a significance map based on the maximum likelihood test statistic (TS). (See, gtlike help.) The resulting map can be used to localize sources within the analysis region. It can also serve as input to follow up unbinned likelihood analysis. The TS maps are created by moving a putative point source through a grid of locations on the sky and maximizing -log(likelihood) at each grid point, with the other, stronger, and presumably well-identified sources included in each fit. New, fainter sources are then identified at local maxima of the TS map.

In each point of the map the TS is obtained using the same procedure as in the unbinned likelihood analysis, so many of the gttsmap parameters are the same as the ones used in gtlike. (See the gtlike help.)

Note: Run gtdiffrsp before running gttsmap. (See gtdiffrsp help.)

One should keep in mind that this tool takes a lot of time to run because a CPU-intensive likelihood analysis is performed at a grid of different positions.

Example: gttsmap

Parameters are passed following the FTOOLs model (i.e., they can be passed interactively by: answering a prompt; as a list in a command line; or by editing the parameter file). To be prompted for gttsmap parameter values, simply type (at the command line): > gttsmap

Note: Not all parameters are prompted; some are "hidden". In order to change one of the "hidden" parameters, specify its value in the command line. For example, to prevent overwriting an existing output file, type (at the command line): > gttsmap clobber=no

An example of how to run the tool is given below:

This example is performed in the region around 3C279 (194.046527,-5.789313). 3C279, 3C273 and the Galactic and Extragalactic background were included in the source model. The
expMap.fits file was produced using gtexpmap (see the gtexpmap help), while the expCube.fits file was produced using gtltcube (see the gtltcube help). SC2_FT2_v2.fits is a simulated spacecraft file. The x coordinate min (max) and the y coordinate min (max) were chosen to be approximately 10 degrees from the 3C279 coordinates. 40 points were selected for the x- and y-axis respectively. In those points, the likelihood analysis is performed.

The example above could also be run from the command line as follows:

> gttsmap evfile=3c279_filted.fits scfile=SC2_FT2_v2.fits
expmap=expMap.fits expcube=expCube.fits srcmdl=src_model.xml
outfile=TS.fits irfs=Pass4_v2 optimizer=DRMNGB ftol=1e-05
xref_min=180 xref_max=200 nx=40 yref_min=-10 yref_max=10 ny=40
coordsys=CEL

gtvcut Help File

Synopsis:

Prints a summary of the Data Sub-Space keywords.

Usage: gtvcut infile table

gtvcut is used to view the Data Sub-Space (DSS) keywords in a given extension, where the EVENTS extension is assumed by default. The DSS keywords scheme was introduced for recording data selection criteria in a systematic manner.

For GLAST data, DSS keywords store information in the FITS headers about the selection criteria that have been applied to the data using the gtselect tool (see the gtselect help). The DSS keywords are used by the exposure-related tools (gtexpmap, gtrspgen) and by gtlike (see
the gtlike help) for calculating various quantities, such as the predicted number of detected events given the source model. These keywords must be the same for all of the filtered event files considered in a given analysis. gtlike will check to ensure that all of the DSS keywords are the same in every file.

A filtering condition is expressed with a set of three or four keywords, DSTYP1, DSUNI1, DSVAL1, and DSREF1.

For example, if we select events in a given time interval (TIME>start_time&&TIME<end_time) the filtering condition are stored as

DSTYP1 = 'TIME'
DSUNI1 = 's '
DSVAL1 = 'start_time:end_time'

If you select events in a given energy range (ENERGY>start_energy&&ENERGY<end_energy) the filtering conditions are stored as

DSTYP3: ENERGY
DSUNI3: MeV
DSVAL3: start_energy:end_energy

Example: gtvcut

Parameters are passed following the FTOOLs model (i.e., they can be passed interactively by: answering a prompt; as a list in a command line; or by editing the parameter file). To be prompted for gttsmap parameter values, simply type (at the command line): > gtvcut

Note: Not all parameters are prompted; some are "hidden". In order to change one of the "hidden" parameters, specify its value in the command line. For example, if you want to
suppress the printing of the individual GTI start and stop times, enter (at the command line): gtvcut suppress_gtis=yes

An example of how to run the tool is shown below:

In this example, selections included: a time range of the events in the original event file
between 2.5239e+08 (MET sec) and 2.54966e+08 (MET sec); an energy range between 100 MeV and 200000 MeV; and a region of 20 degrees from a central point at coordinates RA=193.98 DEC=-5.82.

The example above can also be run from the command line as follows:

> gtvcut infile=_3C279_3C273_back_filtered.fits Input FITS file table = EVENTS