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.

tsmap_fitter

tsmap

Set the method for generating the TS map. Valid options are tsmap or tscube.

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