/
localization.rst
110 lines (80 loc) · 3.64 KB
/
localization.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
.. _localization:
Source Localization
===================
The :py:meth:`~fermipy.gtanalysis.GTAnalysis.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
`~fermipy.gtanalysis.GTAnalysis.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.
.. code-block:: python
>>> 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.
.. |image_loc| image:: 3fgl_j1722.7+6104_localize.png
:width: 100%
.. |image_loc_peak| image:: 3fgl_j1722.7+6104_localize_peak.png
:width: 100%
.. csv-table::
:header: First Iteration, Second Iteration
:widths: 50, 50
|image_loc|, |image_loc_peak|
The default configuration for the localization analysis can be
overriden by supplying one or more *kwargs*:
.. code-block:: python
# 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:
.. code-block:: python
# 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:
.. csv-table:: *localize* Output
:header: Key, Type, Description
:file: ../config/localize_output.csv
:delim: tab
:widths: 10,10,80
Configuration
-------------
.. csv-table:: *localize* Options
:header: Option, Default, Description
:file: ../config/localize.csv
:delim: tab
:widths: 10,10,80
Reference/API
-------------
.. automethod:: fermipy.gtanalysis.GTAnalysis.localize
:noindex: