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,transferfunction}
                 ...

Generate plots of GW observatory data using GWpy

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,transferfunction}
    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)
    transferfunction    Plot transfer function between a reference time series and one

Examples:

    $ gwpy-plot timeseries --chan H1:GDS-CALIB_STRAIN --start 1126259457

    $ gwpy-plot spectrum --chan H1:GDS-CALIB_STRAIN L1:GDS-CALIB_STRAIN --chan V1:Hrec_hoft_16384Hz --start 1187008866 --duration 32 --xmin 10 --xmax 4000

    $ gwpy-plot coherencegram --chan H1:GDS-CALIB_STRAIN H1:PEM-CS_ACC_PSL_PERISCOPE_X_DQ --start 1126260017 --duration 600

Written by Joseph Areeda <joseph.areeda@ligo.org>.
Report bugs to https://gitlab.com/gwpy/gwpy/-/issues/.

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 | --gwosc]
                            [--highpass HIGHPASS] [--lowpass LOWPASS]
                            [--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]

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 ...], --channel CHAN [CHAN ...], --ifo CHAN [CHAN ...]
                        channels to load (or IFO prefix for GWOSC data)
                        (default: None)
  --start START [START ...]
                        one or more starting times (integer GPS or date/time
                        string) (default: None)
  --duration DURATION   Duration (seconds) [10] (default: 10)

Data source options:
  Where to get the data

  -c FRAMECACHE, --framecache FRAMECACHE
                        path to a file containing a list of paths from which
                        to read data (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)
  --gwosc               get data from GWOSC (default: False)

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 ...]   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         presents display in an interactive window, see https:/
                        /matplotlib.org/stable/users/explain/interactive.html#
                        default-ui for details (default: False)
  --title TITLE         Set title (below suptitle, defaults to parameter
                        summary (default: None)
  --suptitle SUPTITLE   topmost title line (larger than the others) (default:
                        None)
  --out OUT             output filename (extension determines format: png,
                        pdf, svg are available) (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 be absolute
                        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).

Command line plotting with GWpy¶

Specifying input data¶

Interactive mode¶

Examples¶