:orphan:

Examples gallery
################

.. admonition:: GWpy needs more examples!
    :class: seealso

    The GWpy project needs more real-life worked examples to demonstrate
    the full range of functionality that is available.

    If you use GWpy for your research, please consider suggesting a new
    example to be included in the documentation.

    To make a suggestion, please open an issue at

    https://gitlab.com/gwpy/gwpy/-/issues/new?issuable_template=Example

    If you have a script that can be converted directly into an example
    please consider opening a
    `merge request <https://gitlab.com/gwpy/gwpy/-/merge_requests/new>`__
    to add it to this gallery.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

.. currentmodule:: gwpy.frequencyseries

##########################
`FrequencySeries` examples
##########################



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="One of the principal means of estimating the sensitivity of a gravitational-wave detector is to esimate it&#x27;s amplitude spectral density (ASD). The ASD is a measurement of how a signal&#x27;s amplitude varies across different frequencies.">

.. only:: html

  .. image:: /examples/frequencyseries/images/thumb/sphx_glr_hoff_thumb.png
    :alt:

  :ref:`sphx_glr_examples_frequencyseries_hoff.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Calculate and plot a FrequencySeries</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The coherence between two channels is a measure of the frequency-domain correlation between their time-series data.">

.. only:: html

  .. image:: /examples/frequencyseries/images/thumb/sphx_glr_coherence_thumb.png
    :alt:

  :ref:`sphx_glr_examples_frequencyseries_coherence.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Calculate the coherence between two channels</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The most common visualisation of the spectral content of a data series is via the power or amplitude spectral density calculations (PSD or ASD). However, these typically involve averaging of the data over a period, which can wash out transient noise (as is often desired).">

.. only:: html

  .. image:: /examples/frequencyseries/images/thumb/sphx_glr_variance_thumb.png
    :alt:

  :ref:`sphx_glr_examples_frequencyseries_variance.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Generating a SpectralVariance histogram</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="It can often be useful to add some known signal to inherently random or noisy data. For example, one might want to investigate what would happen if a binary black hole merger signal occured at or near the time of a glitch. In LIGO data analysis, this procedure is referred to as an injection.">

.. only:: html

  .. image:: /examples/frequencyseries/images/thumb/sphx_glr_inject-fs_thumb.png
    :alt:

  :ref:`sphx_glr_examples_frequencyseries_inject-fs.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Inject a signal into a FrequencySeries</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In LIGO the &#x27;Rayleigh&#x27; statistic is a calculation of the coefficient of variation of the power spectral density (PSD) of a given set of data. It is used to measure the &#x27;Gaussianity&#x27; of those data, where a value of 1 indicates Gaussian behaviour, less than 1 indicates coherent variations, and greater than 1 indicates incoherent variation. It is a useful measure of the quality of the strain data being generated and recorded at a LIGO site.">

.. only:: html

  .. image:: /examples/frequencyseries/images/thumb/sphx_glr_rayleigh_thumb.png
    :alt:

  :ref:`sphx_glr_examples_frequencyseries_rayleigh.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting a Rayleigh-statistic Spectrum</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="As we have seen in sphinx_glr_examples_frequency_hoff, the Amplitude Spectral Density (ASD) is a key indicator of frequency-domain sensitivity for a gravitational-wave detector.">

.. only:: html

  .. image:: /examples/frequencyseries/images/thumb/sphx_glr_percentiles_thumb.png
    :alt:

  :ref:`sphx_glr_examples_frequencyseries_percentiles.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting an averaged ASD with percentiles.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we demonstrate how to calculate the transfer function between two TimeSeries signals.">

.. only:: html

  .. image:: /examples/frequencyseries/images/thumb/sphx_glr_transfer_function_thumb.png
    :alt:

  :ref:`sphx_glr_examples_frequencyseries_transfer_function.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Transfer function</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

.. currentmodule:: gwpy.timeseries

######################
Miscellaneous examples
######################



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="sphx_glr_examples_miscellaneous_range-timeseries.py shows how the binary neutron star (BNS) inspiral range of a gravitational-wave detector can be measured directly from the strain readout.">

.. only:: html

  .. image:: /examples/miscellaneous/images/thumb/sphx_glr_range-spectrogram_thumb.png
    :alt:

  :ref:`sphx_glr_examples_miscellaneous_range-spectrogram.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Estimating the spectral contribution to inspiral range</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="One standard figure-of-merit for the sensitivity of a gravitational-wave detector is the distance to which a binary neutron star (BNS) inspiral with two 1.4 solar mass components would be detected with a signal-to-noise ratio (SNR) of 8. We can estimate this using gwpy.astro.range_timeseries directly from the strain readout for a detector.">

.. only:: html

  .. image:: /examples/miscellaneous/images/thumb/sphx_glr_range-timeseries_thumb.png
    :alt:

  :ref:`sphx_glr_examples_miscellaneous_range-timeseries.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Generating an inspiral range timeseries</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In order to study interferometer performance, it is common in LIGO to plot all of the data for a day, in order to determine trends, and see data-quality issues.">

.. only:: html

  .. image:: /examples/miscellaneous/images/thumb/sphx_glr_open-data-spectrogram_thumb.png
    :alt:

  :ref:`sphx_glr_examples_miscellaneous_open-data-spectrogram.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting a spectrogram of all open data for many hours</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

.. currentmodule:: gwpy.segments

###################
`Segments` examples
###################



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The data from the full Observing Run 1 (O1) have been released by |GWOSC|_.">

.. only:: html

  .. image:: /examples/segments/images/thumb/sphx_glr_open-data_thumb.png
    :alt:

  :ref:`sphx_glr_examples_segments_open-data.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting observing segments for O1</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

.. currentmodule:: gwpy.signal

##########################
Signal processing examples
##########################



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The raw &#x27;strain&#x27; output of the LIGO detectors is recorded as a TimeSeries with contributions from a large number of known and unknown noise sources, as well as possible gravitational wave signals.">

.. only:: html

  .. image:: /examples/signal/images/thumb/sphx_glr_gw150914_thumb.png
    :alt:

  :ref:`sphx_glr_examples_signal_gw150914.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Filtering a TimeSeries to detect gravitational waves</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

.. currentmodule:: gwpy.spectrogram

######################
`Spectrogram` examples
######################



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The standard coherence calculation outputs a frequency series (`~gwpy.frequencyseries.FrequencySeries`) giving a time-averaged measure of coherence. See sphx_glr_examples_frequencyseries_coherence.py for an example.">

.. only:: html

  .. image:: /examples/spectrogram/images/thumb/sphx_glr_coherencegram_thumb.png
    :alt:

  :ref:`sphx_glr_examples_spectrogram_coherencegram.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Calculating the time-dependent coherence between two channels</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="One of the most useful methods of visualising gravitational-wave data is to use a spectrogram, highlighting the frequency-domain content of some data over a number of time steps.">

.. only:: html

  .. image:: /examples/spectrogram/images/thumb/sphx_glr_plot_thumb.png
    :alt:

  :ref:`sphx_glr_examples_spectrogram_plot.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting a Spectrogram</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="As described in sphx_glr_examples_frequencyseries_rayleigh.py, the Rayleigh statistic can be used to study non-Gaussianity in a timeseries. We can study the time variance of these features by plotting a time-frequency spectrogram where we calculate the Rayleigh statistic for each time bin.">

.. only:: html

  .. image:: /examples/spectrogram/images/thumb/sphx_glr_rayleighgram_thumb.png
    :alt:

  :ref:`sphx_glr_examples_spectrogram_rayleighgram.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting a Spectrogram of the Rayleigh statistic</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The sphx_glr_examples_spectrogram_plot.py example showed how to generate and display a Spectrogram of the LIGO-Hanford strain data around the |GW150914|_ event.">

.. only:: html

  .. image:: /examples/spectrogram/images/thumb/sphx_glr_ratio_thumb.png
    :alt:

  :ref:`sphx_glr_examples_spectrogram_ratio.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting a normalised Spectrogram</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The normal spectrogram method uses non-overlapping intervals to calculate discrete PSDs for each stride. This is fine for long-duration data, but give poor resolution when studying short-duration phenomena.">

.. only:: html

  .. image:: /examples/spectrogram/images/thumb/sphx_glr_spectrogram2_thumb.png
    :alt:

  :ref:`sphx_glr_examples_spectrogram_spectrogram2.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting an over-dense, short-duration Spectrogram</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

.. currentmodule:: gwpy.table

#####################
Tabular data examples
#####################



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="I would like to study the rate at which event triggers are generated by the ExcessPower gravitational-wave burst detection algorithm, over a small stretch of data.">

.. only:: html

  .. image:: /examples/table/images/thumb/sphx_glr_rate_thumb.png
    :alt:

  :ref:`sphx_glr_examples_table_rate.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Calculating (and plotting) rate versus time for an EventTable</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="I would like to study the rate at which event triggers are generated by the ExcessPower gravitational-wave burst detection algorithm, over a small stretch of data, binned by various thresholds on signal-to-noise ratio (SNR).">

.. only:: html

  .. image:: /examples/table/images/thumb/sphx_glr_rate_binned_thumb.png
    :alt:

  :ref:`sphx_glr_examples_table_rate_binned.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting EventTable rate versus time for specific column bins</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="I would like to study the event triggers generated by the ExcessPower gravitational-wave burst detection algorithm, over a small stretch of data.">

.. only:: html

  .. image:: /examples/table/images/thumb/sphx_glr_tiles_thumb.png
    :alt:

  :ref:`sphx_glr_examples_table_tiles.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting an EventTable as 2-d tiles</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="I would like to study the distribution of the GW events detected to date.">

.. only:: html

  .. image:: /examples/table/images/thumb/sphx_glr_histogram_thumb.png
    :alt:

  :ref:`sphx_glr_examples_table_histogram.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting an EventTable in a histogram</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="We can use GWpy&#x27;s EventTable to download the catalogue of gravitational-wave detections, and create a scatter plot to investigate the mass distribution of events.">

.. only:: html

  .. image:: /examples/table/images/thumb/sphx_glr_scatter_thumb.png
    :alt:

  :ref:`sphx_glr_examples_table_scatter.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting an EventTable in a scatter</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

.. currentmodule:: gwpy.timeseries

#####################
`TimeSeries` examples
#####################



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Data from the current generation gravitational wave detectors are published by |GWOSCl| and freely available to the public. In this example we demonstrate how to identify times of a published GW detection event, and to download and visualise detector data.">

.. only:: html

  .. image:: /examples/timeseries/images/thumb/sphx_glr_public_thumb.png
    :alt:

  :ref:`sphx_glr_examples_timeseries_public.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Accessing and visualising public GW detector data</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The example sphx_glr_examples_signal_gw150914.py showed us we can visually extract a signal from the noise using basic signal-processing techniques.">

.. only:: html

  .. image:: /examples/timeseries/images/thumb/sphx_glr_pycbc-snr_thumb.png
    :alt:

  :ref:`sphx_glr_examples_timeseries_pycbc-snr.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Calculating the SNR associated with an astrophysical signal model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="On Jan 16 2020 there was a series of earthquakes, that should have had an impact on LIGO operations, I&#x27;d like to find out.">

.. only:: html

  .. image:: /examples/timeseries/images/thumb/sphx_glr_blrms_thumb.png
    :alt:

  :ref:`sphx_glr_examples_timeseries_blrms.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Comparing seismic trends between LIGO sites</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="One of the most useful tools for filtering and visualising short-duration features in a TimeSeries is the Q-transform. This is regularly used by the Detector Characterization working groups of the LIGO Scientific Collaboration and the Virgo Collaboration to produce high-resolution time-frequency maps of transient noise (glitches) and potential gravitational-wave signals.">

.. only:: html

  .. image:: /examples/timeseries/images/thumb/sphx_glr_qscan_thumb.png
    :alt:

  :ref:`sphx_glr_examples_timeseries_qscan.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Generate the Q-transform of a TimeSeries</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="It can often be useful to add some known signal to an inherently random or noisy timeseries. For example, one might want to examine what would happen if a binary black hole merger signal occured at or near the time of a glitch. In LIGO data analysis, this procedure is referred to as an injection.">

.. only:: html

  .. image:: /examples/timeseries/images/thumb/sphx_glr_inject_thumb.png
    :alt:

  :ref:`sphx_glr_examples_timeseries_inject.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Inject a known signal into a TimeSeries</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Confident detection of gravitational-wave signals is critically dependent on understanding the quality of the data searched. Alongside the strain h(t) data, |GWOSC|_ also releases a Data Quality state vector &lt;gwpy-statevector&gt;. We can use this to check on the quality of the data from the LIGO Livingston detector around |GW170817|_.">

.. only:: html

  .. image:: /examples/timeseries/images/thumb/sphx_glr_statevector_thumb.png
    :alt:

  :ref:`sphx_glr_examples_timeseries_statevector.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting segments for a StateVector</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Most data recorded from a gravitational-wave interferometer carry information across a wide band of frequencies, typically up to a few kiloHertz, but often it is the case that the low-frequency amplitude dwarfs that of the high-frequency content, making discerning high-frequency features difficult. This is especially true of the LIGO differential arm strain measurement, which encodes any gravitational wave signals that are present.">

.. only:: html

  .. image:: /examples/timeseries/images/thumb/sphx_glr_whiten_thumb.png
    :alt:

  :ref:`sphx_glr_examples_timeseries_whiten.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Whitening a TimeSeries</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /examples/frequencyseries/index.rst
   /examples/miscellaneous/index.rst
   /examples/segments/index.rst
   /examples/signal/index.rst
   /examples/spectrogram/index.rst
   /examples/table/index.rst
   /examples/timeseries/index.rst



.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_