.. _gwpy-example-frequencyseries-coherence:

.. sectionauthor:: Duncan Macleod <duncan.macleod@ligo.org>

.. currentmodule:: gwpy.timeseries

Calculating the coherence between two channels
##############################################

The `coherence <http://en.wikipedia.org/wiki/Coherence_(physics)>`_ between
two channels is a measure of the frequency-domain correlation between their
time-series data.

In LIGO, the coherence is a crucial indicator of how noise sources couple into
the main differential arm-length readout.
Here we use use the :meth:`TimeSeries.coherence` method to highlight coupling
of motion of a beam periscope attached to the main laser table into the
strain output of the LIGO-Hanford interferometer.

First, we import the `TimeSeriesDict`

.. plot::
   :context: reset
   :nofigs:
   :include-source:

   from gwpy.timeseries import TimeSeriesDict

and then :meth:`~TimeSeriesDict.get` the data for the strain output
(``H1:GDS-CALIB_STRAIN``) and the PSL periscope accelerometer
(``H1:PEM-CS_ACC_PSL_PERISCOPE_X_DQ``):

.. plot::
   :context:
   :nofigs:
   :include-source:

   data = TimeSeriesDict.get(
       ['H1:GDS-CALIB_STRAIN', 'H1:PEM-CS_ACC_PSL_PERISCOPE_X_DQ'],
       1126260017,
       1126260617,
   )
   hoft = data['H1:GDS-CALIB_STRAIN']
   acc = data['H1:PEM-CS_ACC_PSL_PERISCOPE_X_DQ']

We can then calculate the :meth:`~TimeSeries.coherence` of one
`TimeSeries` with respect to the other, using an 2-second Fourier
transform length, with a 1-second (50%) overlap:

.. plot::
   :context:
   :nofigs:
   :include-source:

   coh = hoft.coherence(acc, fftlength=2, overlap=1)

Finally, we can :meth:`~gwpy.frequencyseries.FrequencySeries.plot` the
resulting data:

.. plot::
   :context:
   :include-source:

   plot = coh.plot(
       xlabel='Frequency [Hz]', xscale='log',
       ylabel='Coherence', yscale='linear', ylim=(0, 1),
   )
   plot.show()

We can clearly see the correlation between the periscope motion and the
strain data between 100 Hz and 1000 Hz. Once this was discovered the
motion was damped by modifying the structure of the periscope itself,
reducing the coupling into the gravitational-wave strain output.