gtsrcid Help File

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.

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.

The 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 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 can 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.

Owned by: Jürgen Knödlseder