Source Localization¶
The localize()
method can be
used to spatially localize a source. Localization is performed by
scanning the likelihood surface in source position in a local patch
around the nominal source position. The fit to the source position
proceeds in two iterations:
 TS Map Scan: Obtain a first estimate of the source position by
generating a likelihood map of the region using the
tsmap
method. In this step all background parameters are fixed to their nominal values. The size of the search region used for this step is set with thedtheta_max
parameter.  Likelihood Scan: Refine the position of the source by performing a scan of the likelihood surface in a box centered on the bestfit position found in the first iteration. 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 refit all free parameters of the model.
If a peak is found in the search region and the positional fit succeeds, the method will update the position of the source in the model to the new bestfit position.
Examples¶
The localization method is executed by passing the name of a source as its argument. The method returns a python dictionary with the bestfit source position and localization errors and also saves the same information to FITS and numpy files.
>>> loc = gta.localize('3FGL J1722.7+6104', make_plots=True)
>>> print(loc['ra'],loc['dec'],loc['pos_r68'],loc['pos_r95'])
(260.53164555483784, 61.04493807148745, 0.14384100879403075, 0.23213050350030126)
When running with make_plots=True
the method will save a
diagnostic plot to the working directory with a visualization of the
localization contours. The green and white contours show the
uncertainty ellipse derived from the first and second iterations of
the positional scan.
First Iteration  Second Iteration 

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('3FGL J1722.7+6104', update=True)
By default all background parameters will be fixed when the positional
fit is performed. One can choose to free background parameters with
the free_background
and free_radius
options:
# Free a nearby source that may be be partially degenerate with the
# source of interest
gta.free_norm('sourceB')
gta.localize('3FGL J1722.7+6104', free_background=True)
# Free normalizations of background sources within a certain
# distance of the source of interest
gta.localize('3FGL J1722.7+6104', free_radius=1.0)
The contents of the output dictionary are described in the following table:
Key  Type  Description 

name 
str 
Name of source. 
file 
str 
Name of output FITS file. 
config 
dict 
Copy of the input configuration to this method. 
ra 
float 
Right ascension of bestfit position (deg). 
dec 
float 
Declination of bestfit position (deg). 
glon 
float 
Galactic Longitude of bestfit position (deg). 
glat 
float 
Galactic Latitude of bestfit position (deg). 
xpix 
float 
Longitude pixel coordinate of bestfit position. 
ypix 
float 
Latitude pixel coordinate of bestfit position. 
deltax 
float 
Longitude offset from old position (deg). 
deltay 
float 
Latitude offset from old position (deg). 
skydir 
SkyCoord 

ra_preloc 
float 
Right ascension of prelocalization position (deg). 
dec_preloc 
float 
Declination of prelocalization position (deg). 
glon_preloc 
float 
Galactic Longitude of prelocalization position (deg). 
glat_preloc 
float 
Galactic Latitude of prelocalization position (deg). 
ra_err 
float 
Std. deviation of positional uncertainty in right ascension (deg). 
dec_err 
float 
Std. deviation of positional uncertainty in declination (deg). 
glon_err 
float 
Std. deviation of positional uncertainty in galactic longitude (deg). 
glat_err 
float 
Std. deviation of positional uncertainty in galactic latitude (deg). 
pos_offset 
float 
Angular offset (deg) between the old and new (localized) source positions. 
pos_err 
float 
1sigma positional uncertainty (deg). 
pos_r68 
float 
68% positional uncertainty (deg). 
pos_r95 
float 
95% positional uncertainty (deg). 
pos_r99 
float 
99% positional uncertainty (deg). 
pos_err_semimajor 
float 
1sigma uncertainty (deg) along major axis of uncertainty ellipse. 
pos_err_semiminor 
float 
1sigma uncertainty (deg) along minor axis of uncertainty ellipse. 
pos_angle 
float 
Position angle of uncertainty ellipse with respect to major axis. 
pos_ecc 
float 
Eccentricity of uncertainty ellipse defined as sqrt(1b**2/a**2). 
pos_ecc2 
float 
Eccentricity of uncertainty ellipse defined as sqrt(a**2/b**21). 
pos_gal_cov 
ndarray 
Covariance matrix of positional uncertainties in local projection in galactic coordinates. 
pos_gal_corr 
ndarray 
Correlation matrix of positional uncertainties in local projection in galactic coordinates. 
pos_cel_cov 
ndarray 
Covariance matrix of positional uncertainties in local projection in celestial coordinates. 
pos_cel_corr 
ndarray 
Correlation matrix of positional uncertainties in local projection in celestial coordinates. 
tsmap 
Map 

tsmap_peak 
Map 

loglike_init 
float 
LogLikelihood of model before localization. 
loglike_base 
float 
LogLikelihood of model after initial spectral fit. 
loglike_loc 
float 
LogLikelihood of model after localization. 
dloglike_loc 
float 
Difference in loglikelihood before and after localization. 
fit_success 
bool 

fit_inbounds 
bool 

fit_init 
dict 

fit_scan 
dict 
Configuration¶
Option  Default  Description 

dtheta_max 
0.5  Halfwidth of the search region in degrees used for the first pass of the localization search. 
fix_shape 
False  Fix spectral shape parameters of the source of interest. If True then only the normalization parameter will be fit. 
free_background 
False  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. 
free_radius 
None  Free normalizations of background sources within this angular distance in degrees from the source of interest. If None then no sources will be freed. 
make_plots 
False  Generate diagnostic plots. 
nstep 
5  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. 
update 
True  Update the source model with the bestfit position. 
write_fits 
True  Write the output to a FITS file. 
write_npy 
True  Write the output dictionary to a numpy file. 
Reference/API¶

GTAnalysis.
localize
(name, **kwargs) Find the bestfit position of a source. Localization is performed in two steps. First a TS map is computed centered on the source with halfwidth 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) – Halfwidth of the search region in degrees used for the first pass of the localization search. (default : 0.5)
 fix_shape (bool) – Fix spectral shape parameters of the source of interest. If True then only the normalization parameter will be fit. (default : False)
 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 bestfit 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.
Returns: localize – Dictionary containing results of the localization analysis.
Return type: