gw-skychron

Visualize gravitational-wave sky localization by overlaying timing circles on a sky map. Given a true (or injected) sky position and a detector network, the script draws the iso-delay ring for each detector pair — the locus of sky positions consistent with the measured arrival-time difference. Timing uncertainty annuli and credible-region contours from a HEALPix skymap or a bilby posterior can be overlaid.

Dependencies

All required packages are available in the IGWN conda distribution. Alternatively, create a custom virtual environment by running

conda create -n gw-skychron python=3.11
conda activate gw-skychron

or the analogous command with your favorite tool. After that, go into this repository and run

pip install .

(adding the optional -e flag installs an editable version). This should automatically install all the core runtime dependencies: lal, ligo.skymap, healpy, numpy, pandas, matplotlib, astropy. bilby is only required when using --bilby-json.

After that, you can use the provided CLI by simply running gw-skychron .... See below for concrete examples.

Quick start

Injection from a stats file + FITS skymap:

gw-skychron \
    --skymap-file examples/sim_id_4.fits \
    --stats-file examples/combined_stats.dat \
    --injection-number 4 \
    --ring-pairs L1-H1 L1-V1 H1-V1 \
    --timing-uncertainty --timing-sigma-ms 0.25 \
    --contour-levels 50 90

Bilby posterior (KDE skymap, auto-computed timing uncertainty):

gw-skychron \
    --bilby-json examples/hv_true_snr_fixed_spins_nohom_zero_noise_result.json \
    --detectors H1 V1 \
    --contour-levels 50 90 \
    --timing-uncertainty --n-annulus 96

Globe projection (transparent globe with back-hemisphere circles):

gw-skychron \
    --stats-file examples/combined_stats.dat \
    --injection-number 4 \
    --plot-freq 56 \
    --ring-pairs L1-H1 L1-V1 H1-V1 \
    --timing-uncertainty --timing-sigma-ms 0.25 \
    --resp-func \
    --globe

Direct sky position (no injection lookup):

gw-skychron \
    --sky-pos 97.2 -35.7 1187008882 \
    --ring-pairs L1-H1 L1-V1 H1-V1 \
    --label-frac 0.42 0.8 0.8 \
    --geo

Input formats

Source flag	Required companion	What it provides
--injection-number N	--stats-file PATH	True RA, Dec, GPS from a tab-separated stats CSV; optionally pass --skymap-file for a FITS credible-region overlay
--bilby-json PATH	—	True sky position and GPS from injection_parameters; posterior samples rendered as a smoothed HEALPix KDE skymap; per-detector SNRs used for timing uncertainty
--sky-pos RA DEC GPS	—	Explicit sky position in degrees and GPS seconds; optionally pass --skymap-file

Key options

Flag	Default	Description
--detectors D1 D2 …	—	All pairwise combinations become ring pairs
--ring-pairs D1-D2 …	L1-H1 L1-V1 H1-V1	Explicit detector pairs
--timing-uncertainty	off	Draw uncertainty annuli around each ring
--timing-sigma-ms MS	auto	Override timing σ [ms]; auto uses SNR + effective bandwidth
--n-annulus N	50	Number of sampled rings per pair
--posterior-smooth-deg DEG	1.5	Gaussian smoothing width for bilby KDE skymap; set to 0 to disable
--contour-levels PCT …	50 90	Credible-region contour levels [%]
--geo	off	Orthographic geo-globe projection centred on the source
--globe	off	Like --geo but with a transparent globe surface and back-hemisphere circles shown through it
--resp-func	off	Color each timing circle by the combined antenna response √(F₁²+F₂²) along the arc, using a single normalized colorbar across all pairs
--label-frac F [F …]	auto	Override label position: fraction of circle clockwise from source (0 = source, 0.5 = opposite side). One value for all pairs or one per pair (requires --ring-pairs)
--outdir DIR	script dir	Output directory for auto-named PNG
--output PATH	—	Explicit output path (overrides auto-naming)
--no-show	off	Skip interactive window (useful for batch runs)

Run gw-skychron --help for the full reference.