Command line plotting with GWpy

The gwpy-plot command-line script provides a terminal-based user interface to querying data and generating images. Functionality for this tool is primarily inspired by LigoDV-web (LDVW, https://ldvw.ligo.caltech.edu), a web tool for viewing LIGO data, available to members of the joint LIGO-Virgo collaboration. LDVW, written in Java, uses the gwpy-plot command-line script provided by GWpy to generate the plots based on web-form input from the user.

The basic usage for gwpy-plot is as follows:

gwpy-plot <ACTION> --chan <channel-name> --start <gps-start-time> [OPTIONS]

Where <ACTION> is the type of plot to make.

You can run gwpy-plot --help to list the plot types (‘actions’) you can use:

$ gwpy-plot --help
usage: gwpy-plot [-h] [-V]
                 {timeseries,spectrum,spectrogram,coherence,coherencegram,qtransform}
                 ...

Generate plots of GW observatory data using GWpy

Help options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit

Actions:
  Select one of the following actions:

  {timeseries,spectrum,spectrogram,coherence,coherencegram,qtransform}
    timeseries          Plot one or more time series
    spectrum            Plot the ASD spectrum of one or more time series
    spectrogram         Plot the spectrogram of a time series
    coherence           Plot coherence between a reference time series and one
    coherencegram       Plot the coherence-spectrogram comparing two time
                        series
    qtransform          Plot the Q-transform (Omega)

To see the arguments and options for a given action, you can run, for example, gwpy-plot timeseries --help:

$ gwpy-plot timeseries --help
usage: gwpy-plot timeseries [-h] [-v] [-s] --chan CHAN [CHAN ...]
                            [--start START [START ...]] [--duration DURATION]
                            [-c FRAMECACHE | -n HOSTNAME | --frametype FRAMETYPE]
                            [--highpass HIGHPASS] [--lowpass LOWPASS]
                            [--notch [NOTCH [NOTCH ...]]] [-g WxH] [--dpi DPI]
                            [--interactive] [--title TITLE]
                            [--suptitle SUPTITLE] [--out OUT]
                            [--legend LEGEND [LEGEND ...]] [--nolegend]
                            [--nogrid] [--style FILE] [--xlabel XLABEL]
                            [--xmin XMIN] [--xmax XMAX]
                            [--xscale XSCALE | --logx] [--epoch EPOCH]
                            [--std-seg] [--seg SEG [SEG ...]]
                            [--ylabel YLABEL] [--ymin YMIN] [--ymax YMAX]
                            [--yscale YSCALE | --logy]

Help options:
  -h, --help            show this help message and exit

Verbosity options:
  -v, --verbose         increase verbose output (default: 1)
  -s, --silent          show only fatal errors (default: False)

Data options:
  What data to load

  --chan CHAN [CHAN ...]
                        channels to load (default: None)
  --start START [START ...]
                        Starting GPS times (required) (default: None)
  --duration DURATION   Duration (seconds) [10] (default: 10)

Data source options:
  Where to get the data

  -c FRAMECACHE, --framecache FRAMECACHE
                        read data from cache (default: None)
  -n HOSTNAME, --nds2-server HOSTNAME
                        name of nds2 server to use, default is to try all of
                        them (default: None)
  --frametype FRAMETYPE
                        GWF frametype to read from (default: None)

Signal processing options:
  What to do with the data before plotting

  --highpass HIGHPASS   Frequency for highpass filter (default: None)
  --lowpass LOWPASS     Frequency for lowpass filter (default: None)
  --notch [NOTCH [NOTCH ...]]
                        Frequency for notch (can give multiple) (default:
                        None)

Plot options:
  -g WxH, --geometry WxH
                        size of resulting image (default: 1200x600)
  --dpi DPI             dots-per-inch for figure (default: 100.0)
  --interactive         when running from ipython allows experimentation
                        (default: False)
  --title TITLE         Set title (below suptitle, defaults to parameter
                        summary (default: None)
  --suptitle SUPTITLE   1st title line (larger than the others) (default:
                        None)
  --out OUT             output filename (default: gwpy.png)
  --legend LEGEND [LEGEND ...]
                        strings to match data files (default: [])
  --nolegend            do not display legend (default: False)
  --nogrid              do not display grid lines (default: False)
  --style FILE          path to custom matplotlib style sheet, see
                        http://matplotlib.org/users/style_sheets.html#style-
                        sheets for details of how to write one (default: None)

X axis options:
  --xlabel XLABEL       X axis label (default: None)
  --xmin XMIN           min value for X axis (default: None)
  --xmax XMAX           max value for X axis (default: None)
  --xscale XSCALE       scale for X axis (default: None)
  --logx                use logarithmic X axis (default: None)
  --epoch EPOCH         center X axis on this GPS time, may beabsolute
                        date/time or delta (default: None)
  --std-seg             add DQ segment describing IFO state (default: False)
  --seg SEG [SEG ...]   specify one or more DQ segment names (default: None)

Y axis options:
  --ylabel YLABEL       Y axis label (default: None)
  --ymin YMIN           min value for Y axis (default: None)
  --ymax YMAX           max value for Y axis (default: None)
  --yscale YSCALE       scale for Y axis (default: None)
  --logy                use logarithmic Y axis (default: None)

The options for each action vary but many are common.

Specifying input data

The following table summarises the allowed number of inputs for each action

Action

Number of channels

Number of times

timeseries

>=1

>=1

spectrum

>=1

>=1

coherence

>=2

>=1

spectrogram

1

1

coherencegram

2

1

qtransform

1

1

By default all data are retrieved using TimeSeriesDict.get(), which uses nds2 for data access, but the --framcache option allows you to pass your own data via a LAL-format cache file.

Interactive mode

The --interactive argument uses pyplot to display the image and allow interactive manipulations, (zoom, pan, etc).