Source Localization

The localize() method can be used to spatially localize a source. Localization is performed by scanning the 2D likelihood surface in a local patch around the nominal source position. The current implementation of the localization analysis proceeds in two steps:

  • TS Map Scan: Obtain a rough estimate of the source position by generating a fast TS Map of the region using the tsmap method. In this step all background parameters are fixed to their nominal values.
  • Likelihood Scan: Refine the position of the source by performing a scan of the likelihood surface in a box centered on the best-fit position found with the TS Map method. The size of the search region is set to encompass the 99% positional uncertainty contour. This method uses a full likelihood fit at each point in the likelihood scan and will re-fit all free parameters of the model.

The localization method is executed by passing the name of a source as its argument. The method returns a python dictionary with the best-fit source position and localization errors and also saves this information to the localization dictionary of the Source object.

>>> loc = gta.localize('3FGL J1722.7+6104')
>>> print(loc['ra'],loc['dec'],loc['r68'],loc['r95'])
(260.53164555483784, 61.04493807148745, 0.14384100879403075, 0.23213050350030126)

By default the method will save a plot to the working directory with a visualization of the localization contours. The black and red contours show the uncertainty ellipse derived from the TS Map and likelihood scan, respectively.


The default configuration for the localization analysis can be overriden by supplying one or more kwargs:

# Localize the source and update its properties in the model
# with the localized position
>>> o = gta.extension('sourceA', update=True)

The localization method will not profile over any background parameters that were free when the method was executed. One can free background parameters with the free_background parameter:

# Free a nearby source that may be be partially degenerate with the
# source of interest
gta.localize('sourceA', free_background=True)

The contents of the output dictionary are described in the following table:

localize Output
Key Type Description
ra float Right ascension of best-fit position in deg.
dec float Declination of best-fit position in deg.
glon float Galactic Longitude of best-fit position in deg.
glat float Galactic Latitude of best-fit position in deg.
offset float Angular offset in deg between the old and new (localized) source positions.
sigma float 1-sigma positional uncertainty in deg.
r68 float 68% positional uncertainty in deg.
r95 float 95% positional uncertainty in deg.
r99 float 99% positional uncertainty in deg.
sigmax float 1-sigma uncertainty in deg in longitude.
sigmay float 1-sigma uncertainty in deg in latitude.
sigma_semimajor float 1-sigma uncertainty in deg along major axis of uncertainty ellipse.
sigma_semiminor float 1-sigma uncertainty in deg along minor axis of uncertainty ellipse.
xpix float Longitude pixel coordinate of best-fit position.
ypix float Latitude pixel coordinate of best-fit position.
theta float Position angle of uncertainty ellipse.
eccentricity float Eccentricity of uncertainty ellipse defined as sqrt(1-b**2/a**2).
eccentricity2 float Eccentricity of uncertainty ellipse defined as sqrt(a**2/b**2-1).
config dict Copy of the input parameters to this method.


GTAnalysis.localize(name, **kwargs)

Find the best-fit position of a source. Localization is performed in two steps. First a TS map is computed centered on the source with half-width set by dtheta_max. A fit is then performed to the maximum TS peak in this map. The source position is then further refined by scanning the likelihood in the vicinity of the peak found in the first step. The size of the scan region is set to encompass the 99% positional uncertainty contour as determined from the peak fit.

  • name (str) – Source name.
  • dtheta_max (float) – Half-width of the search region in degrees used for the first pass of the localization search. (default : 0.5)
  • free_background (bool) – Leave background parameters free when performing the fit. If True then any parameters that are currently free in the model will be fit simultaneously with the source of interest. (default : False)
  • free_radius (float) – Free normalizations of background sources within this angular distance in degrees from the source of interest. If None then no sources will be freed. (default : None)
  • make_plots (bool) – Generate diagnostic plots. (default : False)
  • nstep (int) – Number of steps in longitude/latitude that will be taken when refining the source position. The bounds of the scan range are set to the 99% positional uncertainty as determined from the TS map peak fit. The total number of sampling points will be nstep**2. (default : 5)
  • update (bool) – Update the source model with the best-fit position. (default : True)
  • write_fits (bool) – Write the output to a FITS file. (default : True)
  • write_npy (bool) – Write the output dictionary to a numpy file. (default : True)
  • optimizer (dict) – Dictionary that overrides the default optimizer settings.

localize – Dictionary containing results of the localization analysis.

Return type: