gw-skymap-finder 0.1.1

Gravitational wave skymap downloader and overlap analysis tools

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