.. _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=(
           "mass_1_source",
           "mass_2_source",
           "chirp_mass_source",
           "luminosity_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(
       "mass_1_source", "mass_2_source",
       color="chirp_mass_source"
   )
   plot.colorbar(label="Chirp_mass [{}]".format(r"M$_{\odot}$"))
   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["mass_1_source"] + events["mass_2_source"],
       name="mtotal"
   )

and now can make a new scatter plot:

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

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