# 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 profile over any background parameters that were free when the method was executed. One can fix all background parameters with the fix_background parameter:

# Free a nearby source that may be be partially degenerate with the
# source of interest
gta.free_norm('sourceB')
gta.localize('sourceA')


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

localize Output
Key Type Description
glon float Galactic Longitude of best-fit position in deg.
glat float Galactic Latitude of best-fit position in deg.
sigmay float 1-sigma uncertainty in deg in latitude.
sigmax float 1-sigma uncertainty in deg in longitude.
offset float Angular offset in deg between the current and localized source position.
theta float Position angle of uncertainty ellipse.
r68 float 68% positional uncertainty in deg.
xpix float Longitude pixel coordinate of best-fit position.
dec float Declination of best-fit position in deg.
ra float Right ascension of best-fit position in deg.
r99 float 99% positional uncertainty in deg.
ypix float Latitude pixel coordinate of best-fit position.
r95 float 95% positional uncertainty in deg.
config dict Copy of the input parameters to this method.

## Reference/API¶

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.

Parameters: name (str) – Source name. dtheta_max (float) – Maximum offset in RA/DEC in deg from the nominal source position that will be used to define the boundaries of the TS map search region. 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. fix_background (bool) – Fix background parameters when fitting the source position. update (bool) – Update the model for this source with the best-fit position. If newname=None this will overwrite the existing source map of this source with one corresponding to its new location. newname (str) – Name that will be assigned to the relocalized source when update=True. If newname is None then the existing source name will be used. localize – Dictionary containing results of the localization analysis. This dictionary is also saved to the dictionary of this source in ‘localize’. dict