gwtc-analysis 0.4.2

GWTC analysis tool

GWTC Analysis

Overview

GWTC Analysis is a command-line analysis suite for exploring publicly released Gravitational-Wave Transient Catalogs (GWTC) from the LIGO–Virgo–KAGRA (LVK) Collaboration.

The tool provides:

• Search of gravitational-wave sky localizations around a given sky position
• Visualization of parameter-estimation results for individual events
• Selection of events based on physical constraints (masses, distance)
• Global catalog statistics, including detector-network participation and sky-localization performance

All gravitational-wave data products are retrieved from the Gravitational Wave Open Science Center (GWOSC), or from supported alternative repositories (Zenodo / S3 / Galaxy collections).

New: the GWTC-5.0 catalog (O4b observing run) is now available and fully supported — use the GWTC-5 catalog key.

---

Containerized Distribution (Docker)

gwtc_analysis is distributed as a ready-to-use Docker container named gwtc-tool.

• Docker image name: gwtc-tool
• Docker Hub repository: https://hub.docker.com/r/danielsentenac/gwtc-tool/

Using the Docker image is recommended for reproducibility, portability, and integration with workflow systems (e.g. Galaxy, CI pipelines).

---

Astrophysical Sources

The GWTC catalogs contain compact binary merger events involving:

• Binary Black Holes (BBH)
• Binary Neutron Stars (BNS)
• Neutron Star – Black Hole systems (NSBH)

These mergers are detected by the LVK detector network: H1 (Hanford), L1 (Livingston), V1 (Virgo), K1 (KAGRA).

---

Supported GW Catalog Names

Catalog identifiers are case-sensitive:

Catalog name	Description
GWTC-1	Confident subset of GWTC-1
GWTC-2.1	Confident subset of GWTC-2.1
GWTC-3	Confident subset of GWTC-3
GWTC-4	GWTC-4 public release
GWTC-5	GWTC-5.0 public release (O4b)
ALL	Expands to all catalogs above

GWTC-5 resolves to the GWOSC GWTC-5.0 endpoint and to the Zenodo records below.

---

Command-Line Interface (CLI)

usage: gwtc_analysis [-h] MODE ...

positional arguments:
  MODE
    catalog_statistics
    event_selection
    search_skymaps
    parameters_estimation
    build_unofficial_pe

Each mode has its own help:

python -m gwtc_analysis.cli <MODE> -h

---

General Units and Ranges

• Right Ascension: degrees [0, 360)
• Declination: degrees [-90, +90]
• Probability threshold: [0, 1]
• Masses: solar masses (M☉)
• Distances: megaparsecs (Mpc)

---

Data repositories

The GWTC catalogs (Parameter Estimation and Skymaps) can be directly downloaded from different supports:

• The Zenodo portal (official catalogs PE/skymaps tarballs) at https://zenodo.org/records/8177023|17014085|6513631. GWTC-5.0 (O4b) is split across two records: https://zenodo.org/records/20348005 (part 1, plus the archived skymaps tarball) and https://zenodo.org/records/20348006 (part 2).
• A s3 Minio bucket called gwtc on https://minio-dev.odahub.fr
• Galaxy collections under the name GWTC at https://usegalaxy.org

---

Usage

This tool is designed to run either on your laptop as a docker image or conda package, or on several user-friendly platforms:

• docker image
• conda package
• Galaxy tool
• MMODA-LIGO-VIRGO-KAGRA service

Inputs

• Catalog selections are passed as parameters separated by space
• Data repositories accept --data-repo to choose where data products are read from:
  • galaxy: read inputs from Galaxy collections
  • zenodo: official releases from Zenodo
  • s3: S3-compatible bucket

Outputs

• TSV tables
• HTML reports
• Plot images

---

CLI options (auto-generated)

The tables below are generated directly from cli.py to stay aligned with the real CLI.

To regenerate locally (from the repository root):

python gwtc_analysis/gen_readme_cli_tables.py

catalog_statistics

Option	Default	Description
-h, --help	``	show this help message and exit
--catalogs	``	Catalog keys, space-separated (e.g. GWTC-1 GWTC-2.1 GWTC-3 GWTC-4 GWTC-5). ALL key takes them all.
--out-events	catalogs_statistics.tsv	Output TSV path (per-event table).
--out-report	catalogs_statistics.html	Output HTML report path.
--include-detectors	False	Include detector network via GWOSC v2 calls.
--include-area	False	Compute sky localization area Axx if skymaps are available.
--area-cred	0.9	Credible level for sky area: 0.9→A90, 0.5→A50, 0.95→A95.
--plots-dir	cat_plots	Directory for plots (default: cat_plots).
--data-repo	zenodo	Where to read data from: galaxy | zenodo | s3.

event_selection

Option	Default	Description
-h, --help	``	show this help message and exit
--catalogs	``	Catalog keys, space-separated (e.g. GWTC-1 GWTC-2.1 GWTC-3 GWTC-4 GWTC-5). ALL key takes them all.
--out-selection	event_selection.tsv	Output TSV path for the selected events.
--m1-min	``	Minimum primary mass (source frame).
--m1-max	``	Maximum primary mass (source frame).
--m2-min	``	Minimum secondary mass (source frame).
--m2-max	``	Maximum secondary mass (source frame).
--dl-min	``	Minimum luminosity distance (Mpc).
--dl-max	``	Maximum luminosity distance (Mpc).

search_skymaps

Option	Default	Description
-h, --help	``	show this help message and exit
--catalogs	``	Catalog keys, space-separated (e.g. GWTC-1 GWTC-2.1 GWTC-3 GWTC-4 GWTC-5). ALL key takes them all.
--ra-deg	``	Right ascension (deg).
--dec-deg	``	Declination (deg).
--prob	0.9	Credible-level threshold (0–1). Common values: 0.9, 0.5, 0.95.
--skymap-label	Mixed	Label selector used to filter skymap (default: Mixed).
--out-events	search_skymaps.tsv	Output TSV file (default: search_skymaps.tsv).
--out-report	search_skymaps.html	Optional output HTML report path for hits.
--plots-dir	sky_plots	Directory for hit plots (default: sky_plots).
--data-repo	zenodo	Where to read data from: galaxy | zenodo | s3.

parameters_estimation

Option	Default	Description
-h, --help	``	show this help message and exit
--out-report	parameters_estimation.html	Output HTML report path.
--src-name	``	Source event name (e.g. GW231223_032836).
--data-repo	zenodo	Where to read data from: galaxy | zenodo | s3.
--pe-vars	``	Extra posterior sample variables to plot (space-separated). Example: --pe-vars chi_eff chi_p luminosity_distance.
--pe-pairs	``	Extra 2D posterior pairs to plot as 'x:y' tokens. Example: --pe-pairs mass_1_source:mass_2_source chi_eff:chi_p.
--plots-dir	pe_plots	Directory for output PE plots (default: pe_plots).
--start	0.2	Default seconds before GPS time for overlay and q-transform windows.
--stop	0.1	Default seconds after GPS time for overlay and q-transform windows.
--fmin	20.0	Default low frequency bound (Hz) used for overlay filtering and q-transform range.
--fmax	300.0	Default high frequency bound (Hz) used for overlay filtering and q-transform range.
--overlay-start	``	Override seconds before GPS time for the whitened overlay window.
--overlay-stop	``	Override seconds after GPS time for the whitened overlay window.
--overlay-fmin	``	Override low frequency bound (Hz) for overlay whitening/bandpass.
--overlay-fmax	``	Override high frequency bound (Hz) for overlay whitening/bandpass.
--q-start	``	Override seconds before GPS time for the q-transform window.
--q-stop	``	Override seconds after GPS time for the q-transform window.
--q-fmin	``	Override low frequency bound (Hz) for the q-transform.
--q-fmax	``	Override high frequency bound (Hz) for the q-transform.
--q-fscale	log	Frequency axis scaling for q-transform plots (default: log).
--pe-label	``	PE label used to select posterior samples and metadata. If omitted and --waveform-engine is provided, the tool selects the closest PE label by substring match in the PE label. If both are omitted, defaults to Mixed.
--waveform-engine	``	Waveform engine used to generate a time-domain waveform for strain overlay. If omitted, a sensible default engine is used for overlays.

build_unofficial_pe

Option	Default	Description
-h, --help	``	show this help message and exit
--src-name	``	Source event name (e.g. GW170817).
--cache-dir	.cache_gwosc	Cache root where unofficial_pe/.h5 will be written.
--force	False	Force rebuilding the unofficial bundle even if a cached copy already exists and is up to date.

parameters_estimation: Shared Defaults And Overrides

The parameters_estimation workflow now separates shared plotting defaults from per-product overrides.

• Shared defaults apply to both the whitened overlay and the q-transform: --start, --stop, --fmin, --fmax
• Overlay-only overrides affect only the whitened waveform overlay: --overlay-start, --overlay-stop, --overlay-fmin, --overlay-fmax
• Q-transform-only overrides affect only the time-frequency panel: --q-start, --q-stop, --q-fmin, --q-fmax, --q-fscale {linear,log}

If an override is omitted, the corresponding shared default is used.

When the posterior is BNS-like (median chirp_mass < 5 M☉), the workflow automatically switches the overlay and q-transform windows to a BNS profile (longer windows, wider frequency range) for any parameter you did not set explicitly on the CLI. An explicit --overlay-* / --q-* value always wins.

parameters_estimation: Matched-filter SNR

For each detector present in the PE file, the workflow also produces a matched-filter SNR time series |ρ(t)|: the maximum-likelihood projected waveform is matched-filtered against the detector strain, and the peak should sit at the coalescence time and rise to the detector's recovered SNR.

• The strain is conditioned the canonical PyCBC way before filtering (high-pass at 15 Hz, resampled to a 2048 Hz grid, edges cropped of filter transients), so the off-source |ρ(t)| has unit-scale RMS (~0.7). A normalization guard warns if it strays from that range.
• Short (BBH-like) signals only. A single maximum-likelihood template cannot coherently recover a long BNS inspiral — over the many thousands of inspiral cycles, small parameter/phase differences accumulate and the SNR is lost (reliable BNS recovery requires a template bank, not just more strain). When the template is longer than the available conditioned data, the matched-filter SNR is skipped with a warning; all other plots are still produced. This is not fixable by fetching a longer strain segment.

build_unofficial_pe: Unofficial Bundle Workflow

For supported special-case events such as GW170817, build_unofficial_pe creates a PESummary-compatible PEDataRelease bundle from locally cached source products such as posterior samples, PSDs, and skymaps.

• GW170817 is reconstructed from separate GWTC-1-era pieces rather than a single official PESummary release. The current recipe expects: ~/.gwcache/GW170817_GWTC-1.hdf5, ~/.gwcache/GWTC1_GW170817_PSDs.dat, and ~/.gwcache/GW170817_skymap.fits.gz.

• The raw posterior samples do not provide H1_time, L1_time, or V1_time. The bundle builder derives those detector arrival times from geocent_time, ra, and dec with LAL detector delays, then stores them in the reconstructed sample table. For the median GW170817 sky position and geocenter GPS 1187008882.429464, the arrivals are approximately H1 1187008882.448258, L1 1187008882.444965, and V1 1187008882.423074.

• If any of the three source files above are absent, the bundle cannot be rebuilt and strain overlays will not proceed from this special-case path.

• Use python -m gwtc_analysis.cli build_unofficial_pe --src-name GW170817 to build or reuse the cached unofficial bundle explicitly.

• Use --force to rebuild the bundle even if the cached output is up to date.

• parameters_estimation keeps its transparent fallback for supported special cases, but the explicit builder is the recommended way to prepare an uploadable bundle for S3 or local inspection.

Choosing --pe-label and --waveform-engine

The parameter estimation workflow distinguishes between which PE label is used (to read posteriors and metadata from the PE file) and which waveform engine is requested (to synthesize a time-domain signal for strain overlays).

--pe-label (PE samples / posteriors)

• Selects the PE label used to read posterior samples and associated metadata (e.g. C00:Mixed, C00:IMRPhenomXPHM-SpinTaylor, C00:SEOBNRv5PHM).
• If explicitly provided, this choice takes priority.

--waveform-engine (waveform engine for strain overlay)

• Selects the waveform generator used to build the time-domain waveform for strain overlays (engine name, e.g. IMRPhenomXPHM).
• This is an engine name and does not have to exactly match a PE label stored in the file.

---

Automatic label selection rules

1. If --pe-label is explicitly provided

   • That label is used for posterior plots.
   • The same label is also used as the source of PSDs and maximum-likelihood parameters for strain overlays.

2. If --pe-label is not provided but --waveform-engine is

   • The tool selects the PE label whose waveform string best matches the requested engine by substring match on the PE label string (no hardcoded waveform mappings).
   • The selected label is then used consistently for posteriors, PSDs/detector lists, and maximum-likelihood parameters.

   Example:

   • --waveform-engine IMRPhenomXPHM
   • → selects C00:IMRPhenomXPHM-SpinTaylor if present in the PE file

3. If neither option is provided

   • The default Mixed PE label is used.

---

Waveform synthesis fallback

If the requested waveform engine cannot be instantiated (e.g. unsupported parameter range), the tool:

• logs a clear warning
• falls back to an alternative engine when possible
• explicitly reports both the requested and the actually used engine in the logs and plot titles

This ensures robustness while keeping model choices transparent.

---

Testing

python -m gwtc_analysis.cli search_skymaps --catalogs GWTC-4 --ra-deg 265.0 --dec-deg -46.0 --prob 0.6 --data-repo s3
python -m gwtc_analysis.cli event_selection --catalogs GWTC-4
python -m gwtc_analysis.cli catalog_statistics --catalogs GWTC-4 --data-repo s3
python -m gwtc_analysis.cli catalog_statistics --catalogs GWTC-5 --data-repo zenodo
python -m gwtc_analysis.cli build_unofficial_pe --src-name GW170817
python -m gwtc_analysis.cli parameters_estimation --src-name GW231223_032836 --data-repo zenodo
python -m gwtc_analysis.cli parameters_estimation --src-name GW170817 --overlay-start 0.2 --overlay-stop 0.2 --overlay-fmax 1000 --q-start 2 --q-stop 2 --q-fmax 1000 --q-fscale log

---

LIGO–Virgo–KAGRA (LVK)

• LIGO Scientific Collaboration: https://www.ligo.org
• Virgo Collaboration: https://www.virgo-gw.eu
• KAGRA Collaboration: https://gwcenter.icrr.u-tokyo.ac.jp/en

---

Software Stack

• GWpy – detector strain handling and time-series analysis: https://gwpy.github.io
• GWOSC – public access to gravitational-wave data and metadata: https://www.gw-openscience.org
• pesummary – parameter-estimation posteriors handling and visualization: https://pesummary.readthedocs.io
• ligo.skymap – sky-localization map I/O and plotting: https://lscsoft.docs.ligo.org/ligo.skymap