This repository contains a Python pipeline to estimate the Targeted Detectability Range (TDR) for compact-binary gravitational-wave signals associated with an external GRB trigger.
The pipeline retrieves public gravitational-wave strain data from the Gravitational Wave Open Science Center (GWOSC), estimates the detector power spectral density (PSD), computes compact-binary signal-to-noise ratios (SNRs), and evaluates the distance at which a chosen fraction of simulated sources would be detectable.
The current public version is designed for a single GRB trigger at a time.
For a given trigger time, sky position or sky map, and inclination-angle prior, the pipeline:
- identifies the relevant LVK observing run;
- determines which public GWOSC strain data are available for each detector;
- downloads a 256 s strain segment around the trigger time;
- estimates the detector PSD using Welch averaging;
- creates BNS and NSBH signal injections using PyCBC;
- computes the optimal SNR using pycbc_optimal_snr;
- optionally converts optimal SNR to a matched-filter-like SNR;
- estimates the targeted detectability range, D90;
- produces TDR plots, sky maps, PSD plots, and JSON result files.
The default inclination treatment compares two priors:
0 deg < iota < 45 deg
and
0 deg < iota < 90 deg
Alternatively, the user can provide a custom inclination interval using --iota-min and --iota-max.
Prerequisites: You must have either wget or curl installed on your system to download the strain data from GWOSC.
Create a fresh conda environment:
conda create -n TDR python=3.11 pip
conda activate TDR
Clone the repository:
git clone <repo-url>
cd <repo-name>
Install the required packages:
pip install -r requirements.txt
Install the repository in editable mode:
pip install -e .
Test the installation:
python -m targ_ac_git.targ_range_snr_mf --help
/ README.txt requirements.txt pyproject.toml targ_ac_git/ init.py targ_range_snr_mf.py aux_snr_mf.py gwosc_utils_snr_mf.py pipeline_utils_snr_mf.py
Main files:
targ_range_snr_mf.py
Main command-line interface and pipeline driver.
gwosc_utils_snr_mf.py
GWOSC run configuration and strain-data retrieval.
pipeline_utils_snr_mf.py
PSD estimation utilities.
aux_snr_mf.py
Injections, SNR conversion, TDR calculation, and plotting.
The pipeline uses public calibrated strain data from GWOSC.
The observing-run configuration is defined in:
targ_ac_git/gwosc_utils_snr_mf.py
The code selects the correct strain release and detector configuration based on the input trigger time.
Examples of configured public strain channels include:
O1:
H1:DCS-CALIB_STRAIN_C02
L1:DCS-CALIB_STRAIN_C02
O2:
H1:DCH-CLEAN_STRAIN_C02
L1:DCH-CLEAN_STRAIN_C02
V1:Hrec_hoft_V1O2Repro2A_16384Hz
O3:
H1:DCS-CALIB_STRAIN_CLEAN_SUB60HZ_C01
L1:DCS-CALIB_STRAIN_CLEAN_SUB60HZ_C01
V1 run-dependent public strain channels
O4a:
H1:GDS-CALIB_STRAIN_CLEAN_AR
L1:GDS-CALIB_STRAIN_CLEAN_AR
O4b:
H1:DCS-CALIB_STRAIN_CLEAN_AR01
L1:DCS-CALIB_STRAIN_CLEAN_AR01
V1:Hrec_hoftRepro1AR_16384Hz
For a trigger time t0, the pipeline downloads the interval:
t0 - 128 s <= t <= t0 + 128 s
GWOSC files are located using:
from gwosc.locate import get_urls
The downloaded files are saved in:
<output_dir>/gwosc_cache/
The cache is kept after the run for reproducibility and debugging.
For each available detector, the pipeline stitches the required 256 s strain segment and estimates the PSD using Welch averaging.
The default PSD configuration is:
PSD segment length: 16 s
PSD overlap: 8 s
The PSD files are written as two-column text files:
h1_psd.txt
l1_psd.txt
v1_psd.txt
These PSDs are passed to pycbc_optimal_snr.
The pipeline currently evaluates the following mass combinations.
BNS:
m1 = 1.0 Msun, m2 = 1.0 Msun
m1 = 1.4 Msun, m2 = 1.4 Msun
m1 = 2.0 Msun, m2 = 2.0 Msun
NSBH:
mBH = 5.0 Msun, mNS = 1.0 Msun
mBH = 10.0 Msun, mNS = 1.4 Msun
mBH = 20.0 Msun, mNS = 2.0 Msun
For BNS systems, the waveform is:
TaylorF2
For NSBH systems, the waveform is:
IMRPhenomNSBH
The NSBH calculations are performed for the SFHo and DD2 equations of state. The final public results_nsbh.json reports the EOS-averaged D90.
The command-line option:
--snr-type
accepts two values:
mf
matched-filter-like SNR
opt
optimal SNR
The default is:
--snr-type mf
The SNR threshold used to define D90 is set with:
--snr-threshold
The default value is:
--snr-threshold 9
A typical output directory has the structure:
<output_dir>/ targ_range.log ifos_used.txt ifos_used.json gwosc_cache/ inj/ results/ h1_psd.txt l1_psd.txt v1_psd.txt psd_plot.pdf bns_targeted_range.pdf nsbh_targeted_range.pdf range_map_bns_m1_1.4_m2_1.4.fits range_map_bns_m1_1.4_m2_1.4.pdf results_bns.json results_nsbh.json
The file:
ifos_used.txt
summarizes which detector strain data were available and which detectors were used in the analysis.
The files:
results_bns.json
results_nsbh.json
contain the final D90 values.
Use this when the GRB sky position is known.
python -m targ_ac_git.targ_range_snr_mf \
--output-dir <output_directory> \
--t0 <trigger_time> \
--ra <right_ascension_deg> \
--dec <declination_deg> \
--snr-threshold 9 \
--snr-type mf
Example:
python -m targ_ac_git.targ_range_snr_mf \
--output-dir GRB_GIT \
--t0 2020-03-26T12:24:47.903 \
--ra 245.33 \
--dec -21.08 \
--snr-threshold 9 \
--snr-type mf
Use this when a HEALPix localization file is available.
python -m targ_ac_git.targ_range_snr_mf \
--output-dir <output_directory> \
--t0 <trigger_time> \
--skymap-file <skymap_file.fit> \
--snr-threshold 9 \
--snr-type mf
Example:
python -m targ_ac_git.targ_range_snr_mf \
--output-dir GRB_GIT \
--t0 2020-03-26T12:24:47.903 \
--skymap-file examples/glg_healpix_all_bn200326517_v00.fit \
--snr-threshold 9 \
--snr-type mf
If --iota-min and --iota-max are omitted, the code evaluates both:
0 deg < iota < 45 deg
0 deg < iota < 90 deg
To run only a custom inclination range:
python -m targ_ac_git.targ_range_snr_mf \
--output-dir GRB_GIT \
--t0 2020-03-26T12:24:47.903 \
--skymap-file examples/glg_healpix_all_bn200326517_v00.fit \
--iota-min 0 \
--iota-max 30 \
--snr-threshold 9 \
--snr-type mf
The code currently performs a single-trigger analysis. It does not run a time scan, does not use multiprocessing, and does not read a CSV file of GRBs.
If a sky map is provided with --skymap-file, RA and Dec are not required. If no sky map is provided, both --ra and --dec must be given.