.. _gwpy-example-table-scatter:

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

.. currentmodule:: gwpy.table

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

We can use GWpy's `EventTable` to download the catalogue of gravitational-wave
detections, and create a scatter plot to investigate the mass distribution
of events.


First, we can download the ``'GWTC-1-confident'`` catalogue using
:meth:`EventTable.fetch_open_data`:


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

   from gwpy.table import EventTable
   events = EventTable.fetch_open_data(
       "GWTC-1-confident",
       columns=("mass1", "mass2", "E_rad", "distance"),
   )

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


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

   plot = events.scatter("mass1", "mass2", color="E_rad")
   plot.colorbar(label="E_rad [{}]".format(r"M$_{\odot}$ c$^{2}$"))
   plot.show()

We can similarly plot how the total event mass is distributed with
distance.  First we have to build the total mass (``'mtotal'``) column
from the component masses:


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

   events.add_column(events["mass1"] + events["mass2"], name="mtotal")

and now can make a new scatter plot:

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

   plot = events.scatter("distance", "mtotal")
   plot.show()