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

.. currentmodule:: gwpy.timeseries

Calculating the time-dependent coherence between two channels
#############################################################

The standard coherence calculation outputs a frequency series
(`~gwpy.frequencyseries.FrequencySeries`) giving a time-averaged measure
of coherence.

The `TimeSeries` method :meth:`~TimeSeries.coherence_spectrogram` performs the
same coherence calculation every ``stride``, giving a time-varying coherence
measure.




First, we import the `TimeSeriesDict`

.. code-block:: python

   from gwpy.timeseries import TimeSeriesDict


and then :meth:`~TimeSeriesDict.get` both data sets:

.. code-block:: python

   data = TimeSeriesDict.get(['L1:LSC-SRCL_IN1_DQ', 'L1:LSC-CARM_IN1_DQ'],
                              'Feb 13 2015', 'Feb 13 2015 00:15')


We can then use the :meth:`~TimeSeries.coherence_spectrogram` method
of one `TimeSeries` to calcululate the time-varying coherence with
respect to the other, using a 0.5-second FFT length, with a
0.45-second (90%) overlap, with a 8-second stride:

.. code-block:: python

   coh = data['L1:LSC-SRCL_IN1_DQ'].coherence_spectrogram(
       data['L1:LSC-CARM_IN1_DQ'], 8, 0.5, 0.45)


Finally, we can :meth:`~gwpy.spectrogram.Spectrogram.plot` the
resulting data

.. code-block:: python

   plot = coh.plot()
   ax = plot.gca()
   ax.set_ylabel('Frequency [Hz]')
   ax.set_yscale('log')
   ax.set_ylim(10, 8000)
   ax.set_title('Coherence between SRCL and CARM for L1')
   ax.grid(True, 'both', 'both')
   plot.add_colorbar(label='Coherence', clim=[0, 1])
   plot.show()

.. plot:: ../examples/spectrogram/coherence.py