Commit 72836f13 authored by Leo Pound Singer's avatar Leo Pound Singer

Clean up MOC section

parent c0ef14a7
...@@ -7,71 +7,64 @@ localizations in `Aladin Desktop`_. The following main topics are addressed. ...@@ -7,71 +7,64 @@ localizations in `Aladin Desktop`_. The following main topics are addressed.
.. contents:: :local: .. contents:: :local:
MOC and GW Sky Localizations MOC and GW Sky Localizations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----------------------------
The enclosed area within a given probability level contour of a GW sky map can The enclosed area within a given probability level contour of a GW sky map can
be effectively described through the Multi-Order Coverage (:term:`MOC`) method be effectively described with a Multi-Order Coverage (:term:`MOC`) map
[#Fernique15]_. It is a standard of the Virtual Observatory which provides a [#Fernique15]_. MOC is a standard of the Virtual Observatory which provides a
multi-scale mapping based on :term:`HEALPix` sky tessellation. representation of arbitrary regions on the unit sphere using the
:term:`HEALPix` sky tessellation.
The data structure maps irregular and complex sky regions into hierarchically
grouped predefined cells. Each MOC cell is defined by two numbers: the The MOC data structure encodes irregular sky regions as a hierarchy of HEALPix
hierarchy level (HEALPix order) and the pixel index (HEALPix ipix). The pixels. Each MOC cell is defined by two numbers: the hierarchy level (HEALPix
``NUNIQ`` scheme defines an algorithm for packing an (order, ipix) pair into a :math:`\mathit{order}`) and the pixel index (HEALPix :math:`\mathit{ipix}`).
single integer for compactness. MOCs are serialized as FITS or JSON files. The MOCs are serialized as FITS or JSON files. The finest level of refinement
MOC resolution is determined by the map resolution parameter ``nside``, which within the MOC hierarchy is determined by the HEALPix :math:`\mathit{order}`
is used for defining the resolution of the grid. For a typical ``nside=512`` parameter or the equivalent :math:`\mathit{nside}` parameter, related by
(:math:`6.871'` per pixel), the MOC order resolution is ``order = 9`` :math:`\mathit{nside} = 2^\mathit{order}`. For example, ``order=9`` corresponds
to ``nside=512``, and a resolution of :math:`6.9'` per pixel.
.. math::
\mathit{nside} = 2^\mathit{order}.
The MOC maps make database queries for retrieving objects and logical operation The MOC maps make database queries for retrieving objects and logical operation
(such as union, intersection, subtraction, difference) extremely simple and (such as union, intersection, subtraction, difference) extremely fast even for
fast even for very complex sky regions. If databases are adapted to support MOC very complex sky regions.
based queries, such as `VizieR`_, they offer a useful method allowing any
support of sky region query. MOC maps and :doc:`multi-order sky maps </tutorial/multiorder_skymaps>` are
closely related. They use similar multi-resolution HEALPix data structures. The
The resolution of a GW sky localization with three or more detectors can reach main distinction is that MOC maps encode *regions on the sphere*, whereas
a resolution considerably large. To mitigate the computational time, a new multi-order sky maps encode *sampled images or functions on the sphere*. The
variant of the HEALPix format is designed and annotated with the file extension multi-order sky map FITS format is a superset of the MOC FITS format, the only
``.multiorder.fits``. See the section :doc:`/tutorial/multiorder_skymaps` for difference being that a multi-order sky map has values attached to each cell
details. Although the FITS format for LIGO/Virgo multi-resolution sky maps uses (probability density, distance estimates) whereas a MOC map does not. Future
the **UNIQ** indexing scheme and is a superset of the FITS serialization for Aladin releases will support the LIGO/Virgo multi-resolution sky maps.
MOC map, operationally, they are defined as follows. With *MOC map*, we
indicate the method to map complex regions for fast queries and sky map Running Aladin Desktop
comparisons, while, with *multi-order sky map*, we refer to a new HEALPix ----------------------
format to deal with computational challenges related to highly accurate
localizations. Future Aladin releases will support the LIGO/Virgo Aladin Desktop is a Java application. To run it, you must first have the `Java
multi-resolution sky maps. Virtual Machine`_ (JVM) installed. More details are in Aladin's `download
page`_.
1. Running Aladin Desktop
-------------------------
Aladin is developed in Java. As any Java tool, Aladin Desktop requires a `Java
Virtual Machine`_ (JVM) and a classical installation on the user machine
according with your operating system. More details in the `Download
instructions`_.
.. note:: .. note::
If Aladin fails during operation with a message that says something about a Aladin may fail to load some LIGO/Virgo sky maps and display a
``java.lang.OutOfMemoryError``, then your heap size is too small for what ``java.lang.OutOfMemoryError`` error message. This is because the highest
you are trying to do. You will have to run Java with a bigger heap size. You resolution LIGO/Virgo sky maps do not fit inside Aladin's default memory
can increase the maximum memory size used by your Java runtime environment size.
by following the instructions below.
You can increase the maximum memory size used by your Java runtime
environment by following the instructions below.
Download the ``Aladin.jar`` file from `here`_ and execute it from a terminal Download the Aladin.jar from the Aladin `download page`_. Execute it from a
by typing:: terminal by typing::
$ java -Xmx2g -jar Aladin.jar $ java -Xmx2g -jar Aladin.jar
The flag ``-Xmx< ammount of memory >`` specifies the maximum memory The flag ``-Xmx< ammount of memory >`` specifies the maximum memory
allocation pool for a Java Virtual Machine (JVM). Here 2GB of memory is allocation pool for a JVM. Here 2GB of memory is allocated. For GW sky
allocated. For GW sky localizations with ``NSIDE = 2048``, increase the localizations with ``nside=2048``, increase the memory allocated up to 3GB,
memory allocated up to 3GB, ``-Xmx3g``. ``-Xmx3g``.
2. Loading a GW Sky Localization Loading a GW Sky Localization
-------------------------------- -----------------------------
You can copy and paste the sky map URL from the `GraceDB`_ or drag and drop a 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 HEALPix FITS file from your operating system's file browser in the main Aladin
...@@ -79,30 +72,29 @@ window. Aladin recognizes only the standard HEALPix format with the file ...@@ -79,30 +72,29 @@ window. Aladin recognizes only the standard HEALPix format with the file
extension ``.fits.gz``. Here we will work with the `LALinference sky map of extension ``.fits.gz``. Here we will work with the `LALinference sky map of
GW170817`_. GW170817`_.
3. Building a Credible Region Building a Credible Region
----------------------------- --------------------------
The sequence of the Aladin Desktop commands to create a credible region at a The sequence of the Aladin Desktop commands to create a credible region at a
defined confidence level is reported below. From the main menu press defined confidence level is described below. From the menu bar, select
:menuselection:`Coverage --> Generate a MOC based on --> The current :menuselection:`Coverage --> Generate a MOC based on --> The current
probability skymap --> MOC generation` probability skymap`
.. figure:: /_static/aladin_fig1.png .. figure:: /_static/aladin_fig1.png
:alt: Create a MOC from a GW sky localization :alt: Create a MOC from a GW sky localization
The :guilabel:`MOC generation` window requires two mandatory parameters 1) the The :guilabel:`MOC generation` window has two options: the probability sky map
probability sky map and 2) the threshold. The probability sky map entry, that and the threshold. Make sure that the GW sky map that we loaded in the previous
means the GW sky localization in our context, can be selected from the step is selected in the probably sky maps dropdown menu. The drop-down menu
drop-down menu. The drop-down menu contains the GW sky localization previously contains the GW sky localization previously loaded and showed in the Aladin
loaded and showed in the Aladin Stack. The threshold input represents the Stack. Then enter a probability threshold between 0 and 1. Finally, press the
percentage of the credible region in decimal (ranging from 0 to 1). Press the :guilabel:`CREATE` button. The MOC for the credible region is created and
:guilabel:`CREATE` button to generate the resulting credible region. The loaded in the Aladin Stack. If you repeat this process multiple times for
credible region is created and loaded in the Aladin Stack. The credible region different credible levels, then you can select each MOC independently from the
obtained so far are encoded in the Multi Order Coverage map (MOC) and each new Aladin stack.
level can be independently used.
:guilabel:`Properties` Window
4. :guilabel:`Properties` Window -----------------------------
--------------------------------
To open the :guilabel:`Properties` window, right click on the selected plan in To open the :guilabel:`Properties` window, right click on the selected plan in
the Aladin stack. The associated :guilabel:`Properties` windows allows to the Aladin stack. The associated :guilabel:`Properties` windows allows to
...@@ -122,8 +114,8 @@ list aggregator`_ or you can generate your own HiPS from image/cube data. For ...@@ -122,8 +114,8 @@ 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 doing this, from the main menu press :menuselection:`Tool --> Generate a HiPS
based on --> An image collections (FITS, JPEG, PNG)` based on --> An image collections (FITS, JPEG, PNG)`
5. Querying and Filtering a Galaxy Catalog Querying and Filtering a Galaxy Catalog
------------------------------------------ ---------------------------------------
Singer et al. [#Singer16b]_ discuss a fast algorithm for obtaining a Singer et al. [#Singer16b]_ discuss a fast algorithm for obtaining a
three-dimensional probability estimates of sky location and luminosity distance three-dimensional probability estimates of sky location and luminosity distance
...@@ -183,8 +175,7 @@ Aladin stack any image background to obtain the corresponding galaxy images. ...@@ -183,8 +175,7 @@ Aladin stack any image background to obtain the corresponding galaxy images.
.. _`Aladin Desktop`: https://aladin.u-strasbg.fr/AladinDesktop/ .. _`Aladin Desktop`: https://aladin.u-strasbg.fr/AladinDesktop/
.. _`VizieR`: http://vizier.u-strasbg.fr/index.gml .. _`VizieR`: http://vizier.u-strasbg.fr/index.gml
.. _`Java Virtual Machine`: https://www.java.com/en/ .. _`Java Virtual Machine`: https://www.java.com/en/
.. _`Download instructions`: https://aladin.u-strasbg.fr/java/nph-aladin.pl?frame=downloading .. _`download page`: https://aladin.u-strasbg.fr/java/nph-aladin.pl?frame=downloading
.. _`here`: https://aladin.u-strasbg.fr/java/nph-aladin.pl?frame=downloading
.. _`script launcher`: https://aladin.u-strasbg.fr/java/Aladin .. _`script launcher`: https://aladin.u-strasbg.fr/java/Aladin
.. _`GraceDB`: https://gracedb.ligo.org/ .. _`GraceDB`: https://gracedb.ligo.org/
.. _`LALinference sky map of GW170817`: https://dcc.ligo.org/public/0157/P1800381/006/GW170817_skymap.fits.gz .. _`LALinference sky map of GW170817`: https://dcc.ligo.org/public/0157/P1800381/006/GW170817_skymap.fits.gz
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment