diff --git a/tutorial/Aladin.rst b/tutorial/Aladin.rst deleted file mode 100644 index d4a00f830e127f7333bece6fa3c5f2183ea78d26..0000000000000000000000000000000000000000 --- a/tutorial/Aladin.rst +++ /dev/null @@ -1,174 +0,0 @@ -Aladin Desktop -================================== - -The tutorial focuses on some basic strategies for working with -gravitational-wave sky localizations in the context of electromagnetic -follow-up activities. Here we propose the usage of `Aladin -Desktop `__. -The following main topics are addressed. - -1. Sky map visualizations and credible regions. -2. Access to existing catalogs. -3. Filtering and thumbnail view generator - -MOC and GW sky localizations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The contours of a GW sky localization, which enclose a given percentage -of the total probability, are constructed using a *water-filling* -algorithm: the pixels from most probable to least are ranked, and summed -up to get a fixed level of probability \ `[1] <#cite-singer16a>`__. The -enclosed area within a given probability level contour of a GW sky map -can be effectively described through the Multi-Order Coverage (MOC) -method \ `[2] <#cite-fernique15>`__. It is a standard of the Virtual -Observatory which provides a multi-scale mapping based on HEALPix sky -tessellation. Basically, the algorithm maps irregular and complex sky -regions into hierarchically grouped predefined cells. Each MOC cell is -defined by two numbers: the hierarchy level (HEALPIX ORDER) and the -pixel index (HEALPIX NPIX).The NUNIQ scheme defines an algorithm for -packing an (ORDER, NPIX) pair into a single integer for compactness. - -MOCs are serialized as ``FITS`` or ``JSON`` files. The MOC resolution is -determined by the map resolution parameter :math:`N_{side}`, which is -used for defining the resolution of the grid. For a typical -:math:`N_{side}` = 512, the MOC order resolution is :math:`order` = 9; -(:math:`N_{side}` = 2\ :math:`^{order}`). The MOC maps make database -queries for retrieving objects and logical operation (such as union, -intersection, subtraction, difference) extremely simple and fast even -for very complex sky regions. If databases are adapted to support MOC -based queries, such as -`VizieR `__, they offer a -useful method allowing any support of sky region query. - -1. Running Aladin Desktop -------------------------- - -`Aladin -Desktop `__ -is developed in Java. As any Java tool, Aladin Desktop requires a `Java -Virtual Machine `__ on your machine. Download -the ``Aladin.jar`` file from -`here `__ and execute it -from a terminal by typing - -:: - - \$ java -Xmx2g -jar Aladin.jar - -The flag ``-Xmx< ammount of memory >`` specifies the maximum memory -allocation pool for a Java Virtual Machine (JVM). Here 2GB of memory is -allocated. For GW sky localizations with ``NSIDE = 2048``, increase the -memory allocated up to 3GB, ``-Xmx3g``. - -2. Loading a GW sky localization --------------------------------- - -You can *copy&paste* the sky map location from the -`GraceDB `__ or drag the local file 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 `__. - -3. Building a Credible Region ------------------------------ - -The sequence of the Aladin GUI (Graphical User Interface) commands to -create a credible region at a defined confidence level is reported -below. From the main menu press -``→ Coverage → Generate a MOC based on... → The current probability skymap → MOC generation window`` - - -.. figure:: /_static/aladin_fig1.png - :alt: Create a MOC from a GW sky localization - - -The ``MOC generation`` window requires two mandatory parameters 1) the -*probability skymap* and 2) the *threshold*. The probability sky map -entry - that means the GW sky localization in our context - can be -selected from the drop down menu. They are the GW sky localization -previously loaded and showed in the Aladin Stack. The threshold input -represents the percentage of the credible region passed in decimal -(ranging from 0 to 1). Press the ``CREATE`` button to generate the -resulting credible region. The credible region is created and loaded in -the Aladin Stack. The credible region obtained so far are decoded in the -Multi Order Coverage map (MOC) and each new level can be independently -used. - -4. *Properties* Window ----------------------- - -To open the ``Properties`` window, right click on the selected plan in -the Aladin stack. The associated ``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. - -.. figure:: /_static/aladin_fig2.png - :alt: Properties window - -You can overlap a large dataset 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 -``→ Tool → Generate a HiPS based on... → An image collections (FITS, JPEG, PNG)...`` - -5. Querying and Filtering a Galaxy Catalog ------------------------------------------- - -Singer et al. \ `[3] <#cite-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 manageable list of sky location targets to search for the -electromagnetic counterpart of the gravitational wave signal. These -tasks can efficiently be performed in the Aladin Desktop using the data -collections tree and the filter methods as follows. - -``Aladin data collections tree → Select → click on the catalog item → in the popup menu check → by region & MOC`` - - .. figure:: /_static/aladin_fig3.png - :alt: Aladin data collection tree - -Now we can filter the galaxy catalog... - -``Catalog → Create a filter → Properties window → Advanced mode→ Or enter your filter definition:`` - -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-DISTSTB && \${Dist} < DISTMEAN+DISTSTB {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 ``DISTSTB``. Click on ``Apply`` and then ``Export`` to -create a new plane consisting only of sources selected by the filter. - - .. figure:: /_static/aladin_filter.png - :alt: Aladin filter - - -Finally, make thumbnails of the selected galaxies. From the main menu -press ``→ Tool → Thumbnail view generator...`` download and select in -the Aladin stack any image background to obtain the corresponding galaxy -images. - - .. figure:: /_static/aladin_fig4.png - :alt: Thumbnail view generator - - - -[1] Singer, L. P., & Price, L. R. 2016, *Phys. Rev. D*, 93, 024013. -`doi: -0.1103/PhysRevD.93.024013 `__ - -[2] Fernique, P., Allen, et al. 2015, *Astron. Astrophys.*, 578, A114. -`doi: 10.1051/0004-6361/201526075 <10.1051/0004-6361/201526075>`__ - -[3] Singer, L. P., Chen, H.-Y., Holz, D. E., et al. 2016, *Astropys. J. -Lett.*, 829, L15. -`doi:10.3847/2041-8205/829/1/L15 `__