# ----------------------------------------
# README for calibration uncertainty files
# ----------------------------------------
The tgz files contain the time-dependent, frequency-dependent, and complex-valued calibration error and uncertainty estimates for LIGO Hanford, LIGO Livingston, and Virgo.
LIGO Hanford (H1) and Livingston (L1):
O3: LIGO_O3_cal_uncertainty.tgz
O2: LIGO_O2_cal_uncertainty.tgz
O1: LIGO_O1_cal_uncertainty.tgz
Virgo (V1):
O3: Virgo_O3_cal_uncertainty.tgz
O2: Virgo_O2_cal_uncertainty.tgz
For LIGO O1-O3 runs, there are three folders in LIGO_O3_cal_uncertainty.tgz (H1, L1, and statisticalsummaries). Folders 'H1' and 'L1' stand for Hanford and Livingston, respectively. Each file ending with 'FinalResults.txt' in these two folders contains the frequency-dependent, complex-valued error and uncertainty estimated at a discrete GPS time (on hourly cadence) for a given detector. Each file ending with 'MinMax.txt' provides the corresponding summary of the uncertainty boundary at a discrete GPS time. Folder 'statisticalsummaries' contains the statistical summaries of all the calibration error and uncertainty estimated on hourly cadence, divided into various detector epochs. (See more details in the data section below.) The 'MinMax.txt' files are not included for LIGO O1 and O2 runs.
For Virgo O3 run, there are two data files for O3a and O3b, respectively, providing the frequency-dependent, complex-valued error and uncertainty applicable throughout the entire O3a/O3b. For Virgo O2 run, there is one data file covering the whole run.
For all runs, there can be multiple versions of the calibrated strain data. In particular, low latency searches for transient event alerts (https://emfollow.docs.ligo.org/userguide/) in LIGO (Hanford and Livingston) data make use of "C00" calibration, which does not come with well-established uncertainty estimation. Most (not always all) final publications from the LIGO-Virgo collaboration that report on astrophysical parameters associated with events (e.g., GWTC-1, GWTC-2, GWTC-3) make use of "final" calibration (called C02 in O1 and O2, or C01 in O3) which are released by GWOSC (https://www.gw-openscience.org/data/) and are accompanied by these calibration uncertainty estimates. These uncertainty estimates are also available for individual detected events in the GWTC catalog; e.g., for O3a, they are in the Parameter Estimation files in https://dcc.ligo.org/LIGO-P2000223/public.
The source of the LIGO calibration uncertainty estimates and statistical summaries for C02 in O1 and O2, and C01 in O3 is from https://ldas-jobs.ligo.caltech.edu/~cal/uncertainty/ (only available to people with ligo.org credentials).
# ----------------------------------------
# Data
# ----------------------------------------
!!WARNING: Advanced LIGO and advanced Virgo data are not calibrated or valid below 10 Hz or above 5 kHz. Any data below 10 Hz included in these calibration uncertainty files are NOT valid for any analysis purposes.
For LIGO detectors, the data in each 'FinalResults.txt' file contain 7 columns, indicating the frequency-dependent, complex-valued systematic error and the +/- 1-sigma uncertainty boundaries. The systematic error is described by the ratio between the true response function and the modeled response function of the detector, i.e., R^(true)/R^(model) -- see equation (9) in [1]. The 7 columns are:
Column 0 - Frequency
Column 1 - Median systematic error in magnitude, i.e., median abs[R^(true)/R^(model)]
Column 2 - Median systematic error in phase (rad), i.e., median angle[R^(true)/R^(model)]
Column 3 - Lower (-1 sigma) uncertainty boundary in magnitude
Coulmn 4 - Lower (-1 sigma) uncertainty boundary in phase (rad)
Column 5 - Upper (+1 sigma) uncertainty boundary in magnitude
Coulmn 6 - Upper (+1 sigma) uncertainty boundary in phase (rad)
The data in each 'MinMax.txt' file contain 8 columns (8 numbers):
Column 0 - Min 1-sigma magnitude error in frequency band 20-1024 Hz
Column 1 - Max 1-sigma magnitude error in frequency band 20-1024 Hz
Column 2 - Min 1-sigma magnitude error in frequency band 1024-5000 Hz
Column 3 - Max 1-sigma magnitude error in frequency band 1024-5000 Hz
Column 4 - Min 1-sigma phase error (deg) in frequency band 20-1024 Hz
Column 5 - Max 1-sigma phase error (deg) in frequency band 20-1024 Hz
Column 6 - Min 1-sigma phase error (deg) in frequency band 1024-5000 Hz
Column 7 - Max 1-sigma phase error (deg) in frequency band 1024-5000 Hz
NOTE: Each individual 'FinalResults.txt' or 'MinMax.txt' file (in 'H1' and 'L1') are stamped with the GPS time in the middle of the file name, indicating the observing time when the calibration error and uncertainty are estimated. The date at the beginning of each file name indicates the creation date of the file for internal version control purposes and can be safely ignored.
EXAMPLE: See script makeSamplePlot.py for an example of reading the data and plotting the results for a given GPS time.
In the folder 'statisticalsummaries', a set of files are provided, summarizing the time-dependent variation statistics of the hourly estimated calibration error and uncertainty at the LIGO detectors, in each detector epoch. The string 'H1' or 'L1' in the file names marks the detector. The string in the format of 'yymmdd-yymmdd' marks the epoch, defined by detector configuration (see [1] and [2] for detailed definition of each epoch). LIGO O1 and O2 runs only have one epoch each.
The data in each 'percentile.txt' file contain 15 columns:
Column 0 - Frequency
Column 1 - Median value of Column 1 in all 'FinalResults.txt' files for a given epoch
Column 2 - Median value of Column 2 in all 'FinalResults.txt' files for a given epoch
Column 3 - 16th percentile of Column 3 in all 'FinalResults.txt' files for a given epoch
Coulmn 4 - 84th percentile of Column 5 in all 'FinalResults.txt' files for a given epoch
Column 5 - 16th percentile of Column 4 in all 'FinalResults.txt' files for a given epoch
Coulmn 6 - 84th percentile of Column 6 in all 'FinalResults.txt' files for a given epoch
Column 7 - 2.5th percentile of Column 3 in all 'FinalResults.txt' files for a given epoch
Coulmn 8 - 97.5th percentile of Column 5 in all 'FinalResults.txt' files for a given epoch
Column 9 - 2.5th percentile of Column 4 in all 'FinalResults.txt' files for a given epoch
Coulmn 10 - 97.5th percentile of Column 6 in all 'FinalResults.txt' files for a given epoch
Column 11 - 0.5th percentile of Column 3 in all 'FinalResults.txt' files for a given epoch
Coulmn 12 - 99.5th percentile of Column 5 in all 'FinalResults.txt' files for a given epoch
Column 13 - 0.5th percentile of Column 4 in all 'FinalResults.txt' files for a given epoch
Coulmn 14 - 99.5th percentile of Column 6 in all 'FinalResults.txt' files for a given epoch
See section 5 in [1] for details about how these results and statistics are obtained in LIGO.
For Virgo, the data files are in the same format as the LIGO 'FinalResults.txt' file (see above).
# ----------------------------------------
# References
# ----------------------------------------
[1] Sun et al., Class. Quantum Grav. 37 225008 (2020), https://arxiv.org/abs/2005.02531
[2] Sun et al., preprint arXiv:2107.00129 (2021), https://arxiv.org/abs/2107.00129
[3] Cahillane et al., Phys. Rev. D 96, 102001 (2017), https://arxiv.org/abs/1708.03023
[4] Acernese et al., preprint arXiv:2107.03294 (2021), https://arxiv.org/abs/2107.03294
[5] Acernese et al., Class. Quantum Grav. 35 205004 (2018), https://arxiv.org/abs/1807.03275