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 the dtheta_max parameter.
  • 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 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 re-fit 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 best-fit 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 best-fit 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
image_loc image_loc_peak

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:

localize Output
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 best-fit position (deg).
dec float Declination of best-fit position (deg).
glon float Galactic Longitude of best-fit position (deg).
glat float Galactic Latitude of best-fit position (deg).
xpix float Longitude pixel coordinate of best-fit position.
ypix float Latitude pixel coordinate of best-fit 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 pre-localization position (deg).
dec_preloc float Declination of pre-localization position (deg).
glon_preloc float Galactic Longitude of pre-localization position (deg).
glat_preloc float Galactic Latitude of pre-localization 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 1-sigma 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 1-sigma uncertainty (deg) along major axis of uncertainty ellipse.
pos_err_semiminor float 1-sigma 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(1-b**2/a**2).
pos_ecc2 float Eccentricity of uncertainty ellipse defined as sqrt(a**2/b**2-1).
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 Log-Likelihood of model before localization.
loglike_base float Log-Likelihood of model after initial spectral fit.
loglike_loc float Log-Likelihood of model after localization.
dloglike_loc float Difference in log-likelihood before and after localization.
fit_success bool  
fit_inbounds bool  
fit_init dict  
fit_scan dict  

Configuration

localize Options
Option Default Description
dtheta_max 0.5 Half-width 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 best-fit 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 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) – Half-width 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 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.
Returns:

localize – Dictionary containing results of the localization analysis.

Return type:

dict