skymap-overlap

Compute the overlap between two skymaps

Requirements

• scipy-stack (numpy, scipy, matplotlib, pandas)
• astropy
• healpy
• ligo.skymap (only supports Python3.X)
• ligo-gracedb (for batch downloading skymaps)
• pycondor

Installation

This package is available on PyPI. To install, simply run

pip install skymap-overlap

Usage

Computing the overlap between two skymaps

To compute the overlap between two skymaps $p(\Omega)$ and $q(\Omega)$, one can use compute_overlap to compute the overlap. Currently the script computes three overlap statistics:

1. Posterior overlap, which is defined as

$$\displaystyle\int_{\rm all sky} p(\Omega)q(\Omega) \; d\Omega$$

2. Normalized posterior overlap, which is defined as

$$\frac{\displaystyle\int_{\rm all sky} p(\Omega)q(\Omega) \; d\Omega}{\sqrt{\displaystyle\int_{\rm all sky} p(\Omega)p(\Omega) \; d\Omega}\sqrt{\displaystyle\int_{\rm all sky} q(\Omega)q(\Omega) \; d\Omega}}$$

3. 90% credible region (CR) overlap, which is defined as

$$\frac{\displaystyle\int \mathbf{1}_{\rm 90\% CR} \left[ p(\Omega)\right] \mathbf{1}_{\rm 90\% CR} \left[ q(\Omega) \right] d\Omega}{{\rm min} (\displaystyle\int \mathbf{1}_{\rm 90\% CR} \left[ p(\Omega) \right] \; d\Omega , \displaystyle\int \mathbf{1}_{\rm 90\% CR} \left[ q(\Omega) \right] \; d\Omega)},$$

where $\mathbf{1}$ is the indicator function.

4. Cross-highest posterior density (HPD)

$$\max \left\{ 1 - \mathcal{H}(p, q), 1 - \mathcal{H}(q, p) \right\}$$

where

$$\mathcal{H}(p, q) = \int \mathbf{1} \left[ q(\Omega) > q(\Omega_{p, \mathrm{MAP}}) \right] q(\Omega) d\Omega \,,$$

$\mathbf{1}$ is the indicator function, $\Omega_{p,\mathrm{MAP}}$ is the maximum a posteriori estimate of the sky location $\Omega$ for $p$.

Given two FITS skymaps, the simplest usage is

compute_overlap --skymap SKYMAP1.fits.gz --skymap SKYMAP2.fits.gz

Computing the pairwise overlap between a batch of skymaps

To compute the pairwise overlap between a batch of skymaps, you can use compute_overlap_from_skymaps_pipe which generates a DAG file for you to submit to a HTCondor-compatible cluster to calculate the overlap. The simplest usage is

compute_overlap_from_skymaps_pipe --skymap SKYMAP1.fits.gz --skymap SKYMAP2.fits.gz --skymap SKYMAP3.fits.gz

so on and so forth. There are also other options for example the accounting tag (if you are running on LDG).

Batch downloading skymaps from GraceDB

You can use download_skymap to download skymaps from GraceDB given the GID or SID. The simplest usage is

download_skymap GID_or_SID

By default it will download LALInference skymaps whenever possible. There is also an option --bayestar to only use skymaps generated by bayestar.

Joint sky localization

This package provides a command-line-interface tool combine_skymaps that is identical to ligo-skymap-combine here, except all distance information stored in the given maps will be discarded. The simplest usage is

combine_skymaps INPUT1.fits INPUT2.fits OUTPUT.fits

Author

Rico K. L. Lo @ka-lok.lo