Metadata-Version: 2.1
Name: skymap-overlap
Version: 0.1.5
Summary: Compute overlap between two skymaps
Home-page: https://git.ligo.org/ka-lok.lo/skymap-overlap
Author: Rico Ka Lok Lo
Author-email: ka-lok.lo@ligo.org
Requires-Python: >=3.9
License-File: LICENSE
Requires-Dist: healpy
Requires-Dist: ligo.skymap
Requires-Dist: pycondor

# 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
```bash
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
 ```math
 \displaystyle\int_{\rm all sky} p(\Omega)q(\Omega) \; d\Omega
 ```

 2. Normalized posterior overlap, which is defined as
 ```math
 \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
 ```math
 \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)
 ```math
 \max
 \left\{
 1 - \mathcal{H}(p, q),
 1 - \mathcal{H}(q, p)
 \right\}
 ```
 where
 ```math
 \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](https://lscsoft.docs.ligo.org/ligo.skymap/tool/ligo_skymap_combine.html), 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
