GW Data Plotter is a desktop application that simplifies access to Gravitational Wave (GW) data and facilitates basic visualization and analysis. We provide the following versions of executables for various types of Operating Systems:

• GW_data_plotter_LinuxOS for Linux users (developed on Ubuntu);
• GW_data_plotter_MacOS_arm64 for Mac users with Apple processor (to verify which processor you have, click on the Apple logo on the top left of your screen, and then on "About this Mac");
• GW_data_plotter_MacOS_x86_64 for Mac users with Intel processor (macOS 11.0.0 or later);
• GW_data_plotter_WindowsOS for Windows users.

This Desktop App was developed within the AHEAD2020 project, funded by the Horizon 2020 Framewrok Program of the European Union (Grant Agreement 871158).

• Note for Linux Users: Since the app is an executable file, the user must grant execution rights to it. This can be done via the terminal with the command: chmod u=rwx /the path where the App is saved/GW_data_plotter_LinuxOS
  
  
• Note for Windows Users: When trying to run the app you may get a Windows security message, intended to remind users not to open untrusted files downloaded from the Internet. You will have to confirm your decision to open the file to proceed and run the app.
  
  
• Note for Mac Users: Since this app doesn't come from the Apple App Store and is not directly notarized by Apple, when you try to open it by double-clicking on the icon the system will display a warning message that doesn't allow you to open it. To avoid this problem you can change the Privacy & Security settings as explained in this link. Alternatively, you can also press CTRL while clicking on the icon. This will open a menu, from which you have to select "Open". At this point, you will see the same warning window you saw before with the option "Open" in addition.

Description of the App

GW Data Plotter contains 3 tabs labelled: "Get Data", "Plot Data" and "Explore GW Event Parameters". All the tabs have 2 common features: an "help" button and a log window. The "help" button can be used to get a documentation for each tab in a separate window. The log window is meant to contain the output of the operations ongoing or tips, so we suggest to always keep an eye on it. The news messages will appear in the upper part of the window. The user is also guided by warning messages to make the use more interactive.

Get Data tab

The "Get Data" tab allows users to download publicly available GW data originally hosted on the gwosc website. Users can download data in one of the following ways:

1. by choosing a specific time interval. Under the "Select Data by time interval section" the user can type the starting and ending times in GPS format, which is the convention used by the GW community. In this convention, the time is calculated by counting seconds from a reference date (6th January 1980). To convert UTC to GPS time format visit the link: https://gwosc.org/gps/.
2. by selecting a known GW event published by the LIGO-Virgo-KAGRA (LVK) collaboration. Under the "Select a known GW event" section, users can choose to download a few showcase GW events or type the name of a specific GW event. Check this page https://gwosc.org/eventapi/ to get the GPS times and names of all known detections. The subsection "Select duration of data segment" can be used to decide how many seconds of data you want to download before and after the merger time of the event. The starting time for the data download is calculated as the (merger time) + (time before the merger) so the time before the merger is expected to be a negative number.
3. by selecting a known glitch, i.e. a transient noise already identified in the LVK data. Under the "Select an example of a known glitch" section, users can select to download a few examples of glitches. A good source to get the full list of known glitches (with their GPS times of occurrence) in the first three observing runs is this Zenodo entry: GravitySpy repository.

The tab contains 3 buttons:

• Download Data: download the data and save them in a local variable for later plotting (no file will be saved on your PC) 
• Load data: load data from a file already saved locally in one of the formats: *.hdf5, *.gwf and *.txt. The loading can read any file previously saved with the GW Data Plotter app or downloaded from the gwosc website.
• Save data: save data already downloaded in a local file. Also in this case the formats available are  *.hdf5, *.gwf and *.txt.

Additional comments about this tab:

• We suggest downloading at least 2 seconds of data to whiten them. The whitening procedure allows data to be re-weighted according to the detector noise at each frequency, so it is equivalent to a sort of noise removal and we strongly advise using it when possible.
• Remember to select a detector if you are downloading the data via time interval or selecting a known GW event.

KNOWN ISSUES (to be solved in the next versions):

• The executable files currently do not support saving and loading of '.gwf' files. If you need this you will have to use the Python script from this public GitHub repository.
• The download cannot be stopped after it starts, please be patient and wait for the "Done" message to appear on the log window.

Plot Data tab

The "Plot Data" tab allows users to visualize the GW data. Two buttons are available to plot the data in two different ways:

• "Plot strain" allows you to plot the gravitational wave data (called strain) as a function of time.
• "Plot Qscan" allows you to plot the time-frequency evolution of the gravitational wave data. In particular, we use a time-frequency commonly used by the GW community based on the Q-transform (see also this paper). This plot depends on a quality factor Q, check this tutorial to have an idea of which value of Q you should use for your plot.

Under the "Plot setting" section, the user can select plotting options applied to both plots:

• A check box can be used to decide if whitening the data (as said before we advise to do so by downloading a stretch of data longer than 2 seconds).
• A bandpass filter will be applied unless the "No freq selection" is clicked (band passing is filtering within a specific frequency range). The user can choose the frequency range with which to filter the data.
• To zoom in time users can select a time window using as reference the central time of the available segment.

Under the "Q scan section" section, the user can select additional settings, specific to the Q scan plot:

• Maximum and minimum values of Q.
• Set the y-axis to log scale.
• Set the maximum Energy for the colour bar.

Additional comments about this tab:

• After changing the parameters, click the buttons "Plot Qscan" and "Plot Qscan" again to update the plots.
• If you have downloaded data for GW events or glitches from the dropdown menus, the default values of all the plot settings will be automatically fixed to the values that allow optimal plots. In addition, the time x-axis will have the zero at the expected time of the merger for the GW event or at the central time for the glitch (what is called "event_time" in the GravitySpy repository.
• Consider that only the most intense events are visible by eye with the minimal post-processing allowed by this app.

Explore GW Event Parameters tab

The "Explore GW event parameters" tab allows users to get parameters of known GW events. To understand the meaning of the parameters names you can have a look at this link (under "Event Portal"). This tab is organised in two main sections: 

• The section "Event parameters" is useful to explore the parameters of a single known GW event. Users can select an event from a list of showcase events or type the name of an event. By clicking on "Get/print event parameters" users can, then, get the event main parameters, that will be written in the log window. It is also possible to download the skymap for the selected event (skymap is the event's localization on the sky) using the button "Download skymap". Note that in this last case, the skymap will be downloaded on you PC as a *png file and then shown.
• The section "Parameters Distributions" gives the possibility to get the values of some GW event parameters in all published catalogs and plot them as a single histogram or a bi-dimensional scatter plot. The procedure is the following:
  • Use the button "Get parameters for all events" to download a table with the values of all parameters for all published events (this will create a local variable so no file will be saved in your PC).
  • Select one parameter from the drop-down menu.
  • Use the button "Plot histogram" to get the distribution of values on that parameter.
  • Select another parameter from the lower drop-down menu.
  • Use the button "2D scatter plot" to get a scatter plot with the first parameter on the x-axis and the second on the y-axis.
  • If users have previously downloaded the parameters of a specific GW event, they have the option to highlight it in the histogram and scatter plots by selecting the check box "Highlight current event"
  • The axes of the plots can be set to logarithmic scale by using the corresponding checkboxes. Note, however, that if you enable "Log x-axis" when plotting a histogram you will have a histogram of the logarithm of the parameter value. 

How to send comments

The best way to send comments is opening an issue in the GitHub repository that hosts the code by clicking on "New Issue" in this page.

Acknowledgement

This research has made use of data or software obtained from the Gravitational Wave Open Science Center (gwosc.org), a service of the LIGO Scientific Collaboration, the Virgo Collaboration, and KAGRA. This material is based upon work supported by NSF's LIGO Laboratory which is a major facility fully funded by the National Science Foundation, as well as the Science and Technology Facilities Council (STFC) of the United Kingdom, the Max-Planck-Society (MPS), and the State of Niedersachsen/Germany for support of the construction of Advanced LIGO and construction and operation of the GEO600 detector. Additional support for Advanced LIGO was provided by the Australian Research Council. Virgo is funded, through the European Gravitational Observatory (EGO), by the French Centre National de Recherche Scientifique (CNRS), the Italian Istituto Nazionale di Fisica Nucleare (INFN) and the Dutch Nikhef, with contributions by institutions from Belgium, Germany, Greece, Hungary, Ireland, Japan, Monaco, Poland, Portugal, Spain. KAGRA is supported by Ministry of Education, Culture, Sports, Science and Technology (MEXT), Japan Society for the Promotion of Science (JSPS) in Japan; National Research Foundation (NRF) and Ministry of Science and ICT (MSIT) in Korea; Academia Sinica (AS) and National Science and Technology Council (NSTC) in Taiwan.

This work was supported by AHEAD2020, a Research and Innovation Action funded by the Horizon 2020 Framewrok Program of the European Union (Grant Agreement 871158).

We thank the students Pietro Maggi and Giovanni Basaglia for testing this App!