.. _gwpy-example-table-scatter:

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

.. currentmodule:: gwpy.table

Plotting an `EventTable` in a scatter
#####################################

I would like to study the event triggers generated by the `ExcessPower <link>`_
gravitational-wave burst detection algorithm, over a small stretch of data.

The data from which these events were generated contain a simulated
gravitational-wave signal, or hardware injection, used to validate
the performance of the LIGO detectors and downstream data analysis procedures.


First, we import the `EventTable` object and read in a set of events from
a LIGO_LW-format XML file containing a
:class:`sngl_burst <glue.ligolw.lsctables.SnglBurstTable>` table

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

   from gwpy.table import EventTable
   events = EventTable.read(
       'H1-LDAS_STRAIN-968654552-10.xml.gz', tablename='sngl_burst',
       columns=['time', 'central_freq', 'snr'])

.. note::

   Here we manually specify the `columns` to read in order to optimise
   the `read()` operation to parse only the data we actually need.

We can now make a scatter plot by specifying the x- and y-axis columns,
and (optionally) the colour:

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

   plot = events.plot('time', 'central_freq', color='snr')
   ax = plot.gca()
   ax.set_yscale('log')
   ax.set_ylabel('Frequency [Hz]')
   ax.set_epoch(968654552)
   ax.set_xlim(968654552, 968654552+10)
   ax.set_title('LIGO-Hanford event triggers for HW100916')
   plot.add_colorbar(clim=[1, 10], cmap='YlGnBu',
                     label='Signal-to-noise ratio (SNR)')
   plot.show()

This shows the central time and frequency of each event trigger (row
in the ``events`` table). Alternatively we can visualise each trigger
as a two-dimensional tile on the time-frequency plane - for more details
see the example :ref:`gwpy-example-table-tiles`.