# ----------------------------------------
# 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 and LIGO Livingston.

LIGO Hanford (H1) and Livingston (L1):
     O4a: LIGO_O4a_cal_uncertainty.tgz

The online C00 calibrated data in O4a released by GWOSC (https://gwosc.org/data/) are accompanied by calibration uncertainty estimates calculated on an hourly basis. 

The file name follows the convention of "calibration_uncertainty_[IFO]_[GPS].txt" with [IFO] indicating the detector and [GPS] indicating the GPS time when the uncertainty is calculated. Please use the nearest GPS time to the event being analyzed. These uncertainty estimates are also available for individual detected events in the GWTC catalog; e.g., for O4a, they are in the Parameter Estimation files in https://zenodo.org/records/16053484.

For internal users with ligo.org credentials, see more details in Ref. [4]

# ----------------------------------------
# Data
# ----------------------------------------

Each txt file contains the frequency-dependent, complex-valued error and uncertainty estimated at a discrete GPS time (on hourly cadence) for a given detector. 

!!WARNING: LIGO data are not calibrated or valid below 10 Hz or above 5 kHz. No uncertainty estimates are provided below 10 Hz or above 5 kHz. 

For LIGO detectors, the data in each '[IFO]_[GPS].txt' file contains 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 best estimated response function of the detector, denoted by R^(true), and the modeled response function used in the calibration pipeline, R^(model), 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
Column 4 - Lower (-1 sigma) uncertainty boundary in phase (rad)
Column 5 - Upper (+1 sigma) uncertainty boundary in magnitude
Column 6 - Upper (+1 sigma) uncertainty boundary in phase (rad)

To help understand the uncertainty estimate product, here are some relevant formulae:
The reconstructed strain data output by LIGO, using a calibration model R^(model), is h = R^(model) * d_err/L, where d_err is the digital output error signal and L is the arm length. See equation (4) in [1]. The digital error signal is perfectly known, and L is measured with high accuracy and precision. The error and uncertainty in h is essentially the error and uncertainty in R^(model). 

The best-estimated systematic errors of the detector response in R^(model), and hence the equivalent systematic errors in the reconstructed strain, are left uncorrected in the strain data, but presented in these uncertainty estimates as multiplicative factors R^(true)/R^(model) (magnitude and phase).

Given that the uncertainty estimate product (the file ending with '[IFO]_[GPS].txt') provides the ratio of R^(true)/R^(model), we get the more accurately estimated strain, h^(true), by multiplying the uncertainty products to the LIGO output strain (in the frequency domain), i.e., h^(true) = R^(true) * d_err/L = [R^(true)/R^(model)] * R^(model) * d_err/L 

# ----------------------------------------
# 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] https://dcc.ligo.org/LIGO-T2500293