aladin.rst 8.46 KB
Newer Older
Leo Pound Singer's avatar
Leo Pound Singer committed
1 2
Sky Map Visualizations and Credible Regions in Aladin
=====================================================
Leo Pound Singer's avatar
Leo Pound Singer committed
3

Leo Pound Singer's avatar
Leo Pound Singer committed
4 5
In this section, we demonstrate working with gravitational-wave sky
localizations in `Aladin Desktop`_. The following main topics are addressed.
Giuseppe Greco's avatar
Giuseppe Greco committed
6 7 8 9

.. contents:: :local:

MOC and GW Sky Localizations
Leo Pound Singer's avatar
Leo Pound Singer committed
10
----------------------------
Leo Pound Singer's avatar
Leo Pound Singer committed
11 12

The enclosed area within a given probability level contour of a GW sky map can
Leo Pound Singer's avatar
Leo Pound Singer committed
13 14 15 16 17 18 19 20 21 22 23 24 25
be effectively described with a Multi-Order Coverage (:term:`MOC`) map
[#Fernique15]_. MOC is a standard of the Virtual Observatory which provides a
representation of arbitrary regions on the unit sphere using the
:term:`HEALPix` sky tessellation.

The MOC data structure encodes irregular sky regions as a hierarchy of HEALPix
pixels. Each MOC cell is defined by two numbers: the hierarchy level (HEALPix
:math:`\mathit{order}`) and the pixel index (HEALPix :math:`\mathit{ipix}`).
MOCs are serialized as FITS or JSON files. The finest level of refinement
within the MOC hierarchy is determined by the HEALPix :math:`\mathit{order}`
parameter or the equivalent :math:`\mathit{nside}` parameter, related by
:math:`\mathit{nside} = 2^\mathit{order}`. For example, ``order=9`` corresponds
to ``nside=512``, and a resolution of :math:`6.9'` per pixel.
Giuseppe Greco's avatar
Giuseppe Greco committed
26 27

The MOC maps make database queries for retrieving objects and logical operation
Leo Pound Singer's avatar
Leo Pound Singer committed
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45
(such as union, intersection, subtraction, difference) extremely fast even for
very complex sky regions.

MOC maps and :doc:`multi-order sky maps </tutorial/multiorder_skymaps>` are
closely related. They use similar multi-resolution HEALPix data structures. The
main distinction is that MOC maps encode *regions on the sphere*, whereas
multi-order sky maps encode *sampled images or functions on the sphere*. The
multi-order sky map FITS format is a superset of the MOC FITS format, the only
difference being that a multi-order sky map has values attached to each cell
(probability density, distance estimates) whereas a MOC map does not. Future
Aladin releases will support the LIGO/Virgo multi-resolution sky maps.

Running Aladin Desktop
----------------------

Aladin Desktop is a Java application. To run it, you must first have the `Java
Virtual Machine`_ (JVM) installed. More details are in Aladin's `download
page`_.
Leo Pound Singer's avatar
Leo Pound Singer committed
46 47

.. note::
Leo Pound Singer's avatar
Leo Pound Singer committed
48 49 50 51 52 53 54
   Aladin may fail to load some LIGO/Virgo sky maps and display a
   ``java.lang.OutOfMemoryError`` error message. This is because the highest
   resolution LIGO/Virgo sky maps do not fit inside Aladin's default memory
   size.

   You can increase the maximum memory size used by your Java runtime
   environment by following the instructions below.
Giuseppe Greco's avatar
Giuseppe Greco committed
55

Leo Pound Singer's avatar
Leo Pound Singer committed
56 57
   Download the Aladin.jar from the Aladin `download page`_. Execute it from a
   terminal by typing::
Giuseppe Greco's avatar
Giuseppe Greco committed
58

Leo Pound Singer's avatar
Leo Pound Singer committed
59
       $ java -Xmx2g -jar Aladin.jar
Giuseppe Greco's avatar
Giuseppe Greco committed
60 61

   The flag ``-Xmx< ammount of memory >`` specifies the maximum memory
Leo Pound Singer's avatar
Leo Pound Singer committed
62 63 64
   allocation pool for a JVM. Here 2GB of memory is allocated. For GW sky
   localizations with ``nside=2048``, increase the memory allocated up to 3GB,
   ``-Xmx3g``.
Giuseppe Greco's avatar
Giuseppe Greco committed
65

Leo Pound Singer's avatar
Leo Pound Singer committed
66 67
Loading a GW Sky Localization
-----------------------------
Leo Pound Singer's avatar
Leo Pound Singer committed
68 69 70 71 72 73

You can copy and paste the sky map URL from the `GraceDB`_ or drag and drop a
HEALPix FITS file from your operating system's file browser in the main Aladin
window. Aladin recognizes only the standard HEALPix format with the file
extension ``.fits.gz``. Here we will work with the `LALinference sky map of
GW170817`_.
Giuseppe Greco's avatar
Giuseppe Greco committed
74

Leo Pound Singer's avatar
Leo Pound Singer committed
75 76
Building a Credible Region
--------------------------
Leo Pound Singer's avatar
Leo Pound Singer committed
77 78

The sequence of the Aladin Desktop commands to create a credible region at a
Leo Pound Singer's avatar
Leo Pound Singer committed
79
defined confidence level is described below. From the menu bar, select
Leo Pound Singer's avatar
Leo Pound Singer committed
80
:menuselection:`Coverage --> Generate a MOC based on --> The current
Leo Pound Singer's avatar
Leo Pound Singer committed
81
probability skymap`
Giuseppe Greco's avatar
Giuseppe Greco committed
82 83 84 85

.. figure:: /_static/aladin_fig1.png
   :alt: Create a MOC from a GW sky localization

Leo Pound Singer's avatar
Leo Pound Singer committed
86 87 88 89 90 91 92 93 94 95 96 97
The :guilabel:`MOC generation` window has two options: the probability sky map
and the threshold. Make sure that the GW sky map that we loaded in the previous
step is selected in the probably sky maps dropdown menu. The drop-down menu
contains the GW sky localization previously loaded and showed in the Aladin
Stack. Then enter a probability threshold between 0 and 1. Finally, press the
:guilabel:`CREATE` button. The MOC for the credible region is created and
loaded in the Aladin Stack. If you repeat this process multiple times for
different credible levels, then you can select each MOC independently from the
Aladin stack.

:guilabel:`Properties` Window
-----------------------------
Leo Pound Singer's avatar
Leo Pound Singer committed
98

Giuseppe Greco's avatar
Giuseppe Greco committed
99
To open the :guilabel:`Properties` window, right click on the selected plan in
Leo Pound Singer's avatar
Leo Pound Singer committed
100 101 102 103 104 105 106 107
the Aladin stack. The associated :guilabel:`Properties` windows allows to
change the drawing methods in perimeter in order to simultaneously visualize
multiple confidence levels. This operation facilitates tiling operations by
telescopes monitoring the highest probability areas. The enclosed sky area in
square degrees and the percentage of the sky coverage are quoted for each
credible region either **i)** by leaving the cursor on the corresponding plan
loaded in the Aladin stack or **ii)** by opening the associated Properties
windows.
Giuseppe Greco's avatar
Giuseppe Greco committed
108 109 110 111

.. figure:: /_static/aladin_fig2.png
   :alt: Properties window

Leo Pound Singer's avatar
Leo Pound Singer committed
112 113 114 115
You can overlap a large data set of image backgrounds provided by the `HiPS
list aggregator`_ or you can generate your own HiPS from image/cube data. For
doing this, from the main menu press :menuselection:`Tool --> Generate a HiPS
based on --> An image collections (FITS, JPEG, PNG)`
Giuseppe Greco's avatar
Giuseppe Greco committed
116

Leo Pound Singer's avatar
Leo Pound Singer committed
117 118
Querying and Filtering a Galaxy Catalog
---------------------------------------
Leo Pound Singer's avatar
Leo Pound Singer committed
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135

Singer et al. [#Singer16b]_ discuss a fast algorithm for obtaining a
three-dimensional probability estimates of sky location and luminosity distance
from observations of binary compact object mergers with Advanced LIGO and
Virgo. Combining the reconstructed gravitational wave volumes with positions
and redshifts of possible host galaxies provides a filtered list of sky
location targets to search for the electromagnetic counterpart of the
gravitational wave signal. At present it is not implemented in Aladin a catalog
query by the GW three-dimensional posterior probability distribution. What we
can currently achieve is to query the entire galaxy catalog and, afterwards, to
filter the selection. Here a cut-distance filter is applied taking into account
the marginal distance posterior distribution integrated over the whole sky.
These tasks are efficiently performed in the Aladin Desktop using the data
collections tree and the filter methods as follows.

:menuselection:`Aladin data collections tree --> Select --> click on the
catalog item --> in the popup window check --> by region & MOC`
Giuseppe Greco's avatar
Giuseppe Greco committed
136 137 138 139 140 141

  .. figure:: /_static/aladin_fig3.png
   :alt:  Aladin data collection tree

Now we can filter the galaxy catalog. From the main menu press

Leo Pound Singer's avatar
Leo Pound Singer committed
142 143
:menuselection:`Catalog --> Create a filter--> Properties --> Advanced mode -->
Or enter your filter definition`
Giuseppe Greco's avatar
Giuseppe Greco committed
144

Leo Pound Singer's avatar
Leo Pound Singer committed
145 146 147 148 149 150 151
An example about the Aladin filter using as galaxy selection the marginal
distance posterior distribution integrated over the whole sky is reported
below: ``${Dist} > DISTMEAN-DISTSTD && ${Dist} < DISTMEAN+DISTSTD {draw}``. The
posterior mean distance (Mpc) and the posterior standard deviation of distance
(Mpc) are reported in the fits file header with the keywords ``DISTMEAN`` and
``DISTSTD``. Click on ``Apply`` and then ``Export`` to create a new plane
consisting only of sources selected by the filter.
Giuseppe Greco's avatar
Giuseppe Greco committed
152 153 154 155

  .. figure:: /_static/aladin_filter.png
   :alt: Aladin filter

Leo Pound Singer's avatar
Leo Pound Singer committed
156 157 158
Finally, make thumbnails of the selected galaxies. From the main menu press
:menuselection:`Tool --> Thumbnail view generator` download and select in the
Aladin stack any image background to obtain the corresponding galaxy images.
Giuseppe Greco's avatar
Giuseppe Greco committed
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174

  .. figure:: /_static/aladin_fig4.png
   :alt: Thumbnail view generator

.. |apjl| replace:: *Astrophys. J. Lett.*
.. |A&A|  replace:: *Astronomy & Astrophysics*
.. |prd|  replace:: *Phys. Rev. D*

.. [#Fernique15]
   Fernique, P., Allen, et al. 2015, |A&A|, 578, A114.
   :doi:`10.1051/0004-6361/201526075`

.. [#Singer16b]
   Singer, L. P., Chen, H.-Y., Holz, D. E., et al. 2016, |apjl|, 829, L15.
   :doi:`10.3847/2041-8205/829/1/L15`

Leo Pound Singer's avatar
Leo Pound Singer committed
175
.. _`Aladin Desktop`:  https://aladin.u-strasbg.fr/AladinDesktop/
Giuseppe Greco's avatar
Giuseppe Greco committed
176 177
.. _`VizieR`:  http://vizier.u-strasbg.fr/index.gml
.. _`Java Virtual Machine`: https://www.java.com/en/
Leo Pound Singer's avatar
Leo Pound Singer committed
178
.. _`download page`: https://aladin.u-strasbg.fr/java/nph-aladin.pl?frame=downloading
Giuseppe Greco's avatar
Giuseppe Greco committed
179 180
.. _`script launcher`: https://aladin.u-strasbg.fr/java/Aladin
.. _`GraceDB`: https://gracedb.ligo.org/
Leo Pound Singer's avatar
Leo Pound Singer committed
181 182
.. _`LALinference sky map of GW170817`: https://dcc.ligo.org/public/0157/P1800381/006/GW170817_skymap.fits.gz
.. _`HiPS list aggregator`: https://aladin.unistra.fr/hips/list