gw-skymap-finder 0.1.1
Gravitational wave skymap downloader and overlap analysis tools
License: MIT
Requires Python: >=3.10

# gw-skymap-finder

Tools for downloading and analyzing gravitational-wave skymaps from LIGO/Virgo GraceDB, with a focus on Binary Black Hole (BBH) events and sky-localization overlap analysis.

This package began as a notebook-based workflow for identifying event pairs with high sky overlap and is now packaged for reuse as a Python library.

---

## Features

- **GraceDB querying**
  - Query recent superevents from GraceDB with configurable:
    - Time window (e.g. last 32 months)
    - False Alarm Rate (FAR) threshold
    - Minimum BBH classification probability

- **Skymap download and organization**
  - Download BAYESTAR and BILBY skymaps for each event
  - Intelligent filename pattern matching for common GraceDB skymap names
  - Skip known-bad / excluded files (e.g. by keyword)
  - Extract basic FITS metadata (distance info, NSIDE, ordering, coordinate system)
  - Save a JSON manifest of all downloaded skymaps

- **Notebook workflow (example)**
  - Example Jupyter notebook showing:
    - Querying events from GraceDB
    - Computing overlap integrals between sky localizations
    - Visualizing skymaps and high-overlap pairs
    - Basic statistical analysis and plotting

---

## Installation

From PyPI:

pip install gw-skymap-finderThis installs the library package `skymap_finder` (import name) and its core dependencies.

---

## Quick Start

### 1. Import and initialize GraceDB client

import skymap_finder as sf

# Create a GraceDB client (requires network access and, for some endpoints, credentials)
client = sf.initialize_gracedb_client()### 2. Query BBH events

event_ids = sf.query_bbh_events(
    client,
    far_threshold=2.3e-5,      # False Alarm Rate threshold
    lookback_months=32,       # Time window for events
    bbh_probability_threshold=0.5,
)

print(f"Found {len(event_ids)} candidate BBH events")### 3. Download skymaps for those events

from pathlib import Path

output_dir = Path("./BBH_skymaps")
downloads = sf.download_skymaps_batch(
    event_ids,
    output_dir=output_dir,
    save_manifest=True,
)

print(f"Downloaded {len(downloads)} skymaps to {output_dir}")Each `download` entry is a `SkymapMeta` dataclass with useful metadata (event ID, pipeline, local path, distance info, etc.).

---

## Package API

The main public objects are exported at the top level:

import skymap_finder as sf

sf.SkymapMeta
sf.initialize_gracedb_client
sf.download_skymap_for_event
sf.download_skymaps_batch
sf.query_bbh_events- **`SkymapMeta`**: dataclass describing a single skymap file and its metadata.
- **`initialize_gracedb_client()`**: returns a `GraceDb` REST client.
- **`download_skymap_for_event(client, event_id, output_dir)`**: attempt to download one or more skymaps for a single event.
- **`download_skymaps_batch(event_ids, output_dir, save_manifest=True)`**: batch-download skymaps for a list of event IDs, with an optional manifest.
- **`query_bbh_events(client, far_threshold, lookback_months, bbh_probability_threshold)`**: query for BBH-like events using p_astro classification files.

---

## Example Notebook

This repository includes a Jupyter notebook `skymap_finder.ipynb` that demonstrates:

- Connecting to GraceDB and querying events
- Downloading and caching skymaps
- Computing overlap integrals between skymaps
- Visualizing high-overlap sky localizations and distributions of overlaps

You can run it with:

jupyter notebook skymap_finder.ipynb(Ensure you have installed the extra scientific/plotting dependencies listed in `requirements.txt`.)

---

## Dependencies

Core dependencies include:

- `numpy`, `tqdm`
- `ligo.skymap`, `ligo.gracedb`
- `astropy`, `astropy-healpix`
- `healpy`
- `matplotlib`, `seaborn`
- `pathos`, `tqdm-pathos`
- `requests`

For a complete list, see `requirements.txt`.

---

## Development

Clone the repository and install in editable mode:

git clone https://github.com/your-username/gw-skymap-finder.git
cd gw-skymap-finder
pip install -e .You can then edit the code under `src/skymap_finder/` and rerun the notebook or scripts.

---

## License

This project is licensed under the MIT License.

---

## Citation

If you use this package or the associated methodology, please cite:

- Singer et al. (2014), *The First Two Years of Electromagnetic Follow-Up with Advanced LIGO and Virgo* (`https://doi.org/10.3847/1538-4357/aabfd2`)
- The LIGO/Virgo Collaboration skymap and GraceDB documentation