Plotting API

This document provides a reference for the following Figure class objects:

Plot An extension of the core matplotlib Figure
TimeSeriesPlot Figure for displaying a TimeSeries.
FrequencySeriesPlot Figure for displaying a FrequencySeries
SpectrogramPlot Figure for displaying a Spectrogram.
SegmentPlot Plot for displaying a DataQualityFlag
EventTablePlot Figure for displaying a EventTable
BodePlot A Plot class for visualising transfer functions

and the following Axes class objects:

Axes An extension of the core matplotlib Axes.
TimeSeriesAxes Custom Axes for a TimeSeriesPlot.
FrequencySeriesAxes Custom Axes for a FrequencySeriesPlot.
SegmentAxes Custom Axes for a SegmentPlot.
EventTableAxes Custom Axes for an ~gwpy.plotter.EventTablePlot`.

Figure objects

Each of the below classes represents a figure object; for brevity inherited methods and attributes are not documented here, please follow links to the parent classes for documentation of available methods and attributes.

class gwpy.plotter.Plot(*args, **kwargs)[source]

Bases: matplotlib.figure.Figure

An extension of the core matplotlib Figure

The Plot provides a number of methods to simplify generating figures from GWpy data objects, and modifying them on-the-fly in interactive mode.

add_array(*args, **kwargs)[source]

Add a Array to this plot

Parameters:

array : Array

the Array to display

projection : str

name of the Axes projection on which to plot

ax : Axes

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional

force data to plot on a fresh set of Axes

**kwargs

other keyword arguments for the Plot.add_line function

Returns:

artist : Artist

the layer return from the relevant plotting function

add_colorbar(*args, **kwargs)[source]

Add a colorbar to the current Plot

A colorbar must be associated with an Axes on this Plot, and an existing mappable element (e.g. an image) (if visible=True).

Parameters:

mappable : matplotlib data collection

collection against which to map the colouring

ax : Axes

axes from which to steal space for the colorbar

location : str, optional

position of the colorbar

width : float, optional

width of the colorbar as a fraction of the axes

pad : float, optional

gap between the axes and the colorbar as a fraction of the axes

log : bool, optional

display the colorbar with a logarithmic scale, or not

label : str, optional

label for the colorbar

clim : pair of float

(lower, upper) limits for the colorbar scale, values outside of these limits will be clipped to the edges

visible : bool, optional

make the colobar visible on the figure, this is useful to make two plots, each with and without a colorbar, but guarantee that the axes will be the same size

**kwargs

other keyword arguments to be passed to the colorbar() generator

Returns:

cbar : Colorbar

the newly added Colorbar

Examples

>>> import numpy
>>> from gwpy.plotter import Plot

To plot a simple image and add a colorbar:

>>> plot = Plot()
>>> ax = plot.gca()
>>> ax.imshow(numpy.random.randn(120).reshape((10, 12)))
>>> plot.add_colorbar(label='Value')
>>> plot.show()

(png)

../_images/api-1.png
add_dataqualityflag(flag, projection=None, ax=None, newax=False, sharex=None, sharey=None, **kwargs)[source]

Add a DataQualityFlag to this plot

Parameters:

flag : DataQualityFlag

the DataQualityFlag to display

projection : str

name of the Axes projection on which to plot

ax : Axes

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional

force data to plot on a fresh set of Axes

**kwargs

other keyword arguments for the Plot.add_line function

Returns:

collection : Collection

the newly added patch collection

add_frequencyseries(*args, **kwargs)[source]

Add a FrequencySeries trace to this plot

Parameters:

spectrum : FrequencySeries

the FrequencySeries to display

ax : Axes

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional

force data to plot on a fresh set of Axes

**kwargs

other keyword arguments for the Plot.add_line function

Returns:

line : Line2D

the newly added line

add_image(*args, **kwargs)[source]

Add a 2-D image to this plot

Parameters:

image : numpy.ndarray

2-D array of data for the image

**kwargs

other keyword arguments are passed to the matplotlib.axes.Axes.imshow() function

Returns:

image : AxesImage

the newly added image

add_legend(*args, **kwargs)[source]

Add a legend to this Plot on the most favourable Axes

All non-keyword args and kwargs are passed directly to the legend() generator

Returns:

legend : Legend

the new legend

add_line(*args, **kwargs)[source]

Add a line to the current plot

Parameters:

x : array-like

x positions of the line points (in axis coordinates)

y : array-like

y positions of the line points (in axis coordinates)

projection : str, optional

name of the Axes projection on which to plot

ax : Axes

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional

force data to plot on a fresh set of Axes

**kwargs

additional keyword arguments passed directly on to the axes plot() method.

Returns:

line : Line2D

the newly added line

add_scatter(*args, **kwargs)[source]

Add a set or points to the current plot

Parameters:

x : array-like

x-axis data points

y : array-like

y-axis data points

projection : str, optional

name of the Axes projection on which to plot

ax : Axes

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional

force data to plot on a fresh set of Axes

**kwargs.

other keyword arguments passed to the matplotlib.axes.Axes.scatter() function

Returns:

collection : Collection

the Collection for this new scatter

add_spectrogram(*args, **kwargs)[source]

Add a Spectrogram to this plot

Parameters:

spectrogram : Spectrogram

the Spectrogram to display

ax : Axes

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional

force data to plot on a fresh set of Axes

**kwargs

other keyword arguments for the Plot.add_line function

Returns:

qm : QuadMesh

the new QuadMesh layer representing the spectrogram display

add_subplot(*args, **kwargs)[source]

Add a subplot.

Parameters:

*args

Either a 3-digit integer or three separate integers describing the position of the subplot. If the three integers are R, C, and P in order, the subplot will take the Pth position on a grid with R rows and C columns.

projection : [‘aitoff’ | ‘hammer’ | ‘lambert’ | ‘mollweide’ | ‘polar’ | ‘rectilinear’], optional

The projection type of the axes.

polar : boolean, optional

If True, equivalent to projection=’polar’.

**kwargs

This method also takes the keyword arguments for Axes.

Returns:

axes : Axes

The axes of the subplot.

See also

matplotlib.pyplot.subplot
for an explanation of the args.

Notes

If the figure already has a subplot with key (args, kwargs) then it will simply make that subplot current and return it. This behavior is deprecated.

Examples

fig.add_subplot(111)

# equivalent but more general
fig.add_subplot(1, 1, 1)

# add subplot with red background
fig.add_subplot(212, facecolor='r')

# add a polar subplot
fig.add_subplot(111, projection='polar')

# add Subplot instance sub
fig.add_subplot(sub)
add_timeseries(*args, **kwargs)[source]

Add a TimeSeries trace to this plot

Parameters:

timeseries : TimeSeries

the TimeSeries to display

ax : Axes

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional

force data to plot on a fresh set of Axes

**kwargs

other keyword arguments for the Plot.add_array function

Returns:

line : Line2D

the newly added line object

close()[source]

Close the plot and release its memory.

gca(*args, **kwargs)[source]

Get the current axes, creating one if necessary

The following kwargs are supported for ensuring the returned axes adheres to the given projection etc., and for axes creation if the active axes does not exist:

adjustable: [ ‘box’ | ‘datalim’] agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array alpha: float (0.0 transparent through 1.0 opaque) anchor: [ ‘C’ | ‘SW’ | ‘S’ | ‘SE’ | ‘E’ | ‘NE’ | ‘N’ | ‘NW’ | ‘W’ ] animated: bool aspect: unknown autoscale_on: bool autoscalex_on: bool autoscaley_on: bool axes_locator: a callable object which takes an axes instance and renderer and returns a bbox. axisbelow: [ bool | ‘line’ ] clip_box: a Bbox instance clip_on: bool clip_path: [(Path, Transform) | Patch | None] contains: a callable function facecolor: color fc: color figure: Figure frame_on: bool gid: an id string label: object navigate: bool navigate_mode: unknown path_effects: AbstractPathEffect picker: [None | bool | float | callable] position: unknown rasterization_zorder: float or None rasterized: bool or None sketch_params: (scale: float, length: float, randomness: float) snap: bool or None title: unknown transform: Transform url: a url string visible: bool xbound: (lower: float, upper: float) xlabel: unknown xlim: (left: float, right: float) xmargin: float greater than -0.5 xscale: [ ‘linear’ | ‘log’ | ‘symlog’ | ‘logit’ | … ] xticklabels: list of string labels xticks: list of tick locations. ybound: (lower: float, upper: float) ylabel: unknown ylim: (bottom: float, top: float) ymargin: float greater than -0.5 yscale: [ ‘linear’ | ‘log’ | ‘symlog’ | ‘logit’ | … ] yticklabels: list of string labels yticks: list of tick locations. zorder: float
get_auto_refresh()[source]

Return the auto-refresh setting for this Plot.

get_axes(projection=None)[source]

Find all Axes, optionally matching the given projection

Parameters:

projection : str

name of axes types to return

Returns:
axlist : list of Axes
get_title(*args, **kwargs)[source]

Get an axes title.

Get one of the three available axes titles. The available titles are positioned above the axes in the center, flush with the left edge, and flush with the right edge.

Parameters:

loc : {‘center’, ‘left’, ‘right’}, str, optional

Which title to get, defaults to ‘center’.

Returns:

title : str

The title text string.

get_xlabel(*args, **kwargs)[source]

Get the xlabel text string.

get_xlim(*args, **kwargs)[source]

Get the x-axis range

Returns:

xlimits : tuple

Returns the current x-axis limits as the tuple (left, right).

Notes

The x-axis may be inverted, in which case the left value will be greater than the right value.

get_xscale(*args, **kwargs)[source]

Return the xaxis scale string: linear, log, logit, symlog

get_ylabel(*args, **kwargs)[source]

Get the ylabel text string.

get_ylim(*args, **kwargs)[source]

Get the y-axis range

Returns:

ylimits : tuple

Returns the current y-axis limits as the tuple (bottom, top).

Notes

The y-axis may be inverted, in which case the bottom value will be greater than the top value.

get_yscale(*args, **kwargs)[source]

Return the yaxis scale string: linear, log, logit, symlog

html_map(*args, **kwargs)[source]

Create an HTML map for some data contained in these Axes

Parameters:

data : Artist, Series, array-like

data to map, one of an Artist already drawn on these axes ( via plot() or scatter(), for example) or a data set

imagefile : str

path to image file on disk for the containing Figure

mapname : str, optional

ID to connect <img> tag and <map> tags, default: 'points'. This should be unique if multiple maps are to be written to a single HTML file.

shape : str, optional

shape for <area> tag, default: 'circle'

standalone : bool, optional

wrap map HTML with required HTML5 header and footer tags, default: True

title : str, optional

title name for standalone HTML page

jquery : str, optional

URL of jquery script, defaults to googleapis.com URL

Returns:

HTML : str

string of HTML markup that defines the <img> and <map>

logx

View x-axis in logarithmic scale

logy

View y-axis in logarithmic scale

refresh()[source]

Refresh the current figure

save(*args, **kwargs)[source]

Save the figure to disk.

This method is an alias to savefig(), all arguments are passed directory to that method.

set_auto_refresh(refresh)[source]

Set the auto-refresh setting for this Plot.

With auto_refresh set to True, all modifications of the underlying Axes will trigger the plot to be re-drawn

Parameters:
refresh : True or False
set_title(*args, **kwargs)[source]

Set a title for the axes.

Set one of the three available axes titles. The available titles are positioned above the axes in the center, flush with the left edge, and flush with the right edge.

Parameters:

label : str

Text to use for the title

fontdict : dict

A dictionary controlling the appearance of the title text, the default fontdict is:

{'fontsize': rcParams['axes.titlesize'],
 'fontweight' : rcParams['axes.titleweight'],
 'verticalalignment': 'baseline',
 'horizontalalignment': loc}

loc : {‘center’, ‘left’, ‘right’}, str, optional

Which title to set, defaults to ‘center’

pad : float

The offset of the title from the top of the axes, in points. Default is None to use rcParams[‘axes.titlepad’].

Returns:

text : Text

The matplotlib text instance representing the title

Other Parameters:
 

**kwargs : Text properties

Other keyword arguments are text properties, see Text for a list of valid text properties.

set_xlabel(*args, **kwargs)[source]

Set the label for the x-axis.

Parameters:

xlabel : str

The label text.

labelpad : scalar, optional, default: None

Spacing in points between the label and the x-axis.

Other Parameters:
 

**kwargs : Text properties

Text properties control the appearance of the label.

See also

text
for information on how override and the optional args work
set_xlim(*args, **kwargs)[source]

Set the data limits for the x-axis

Parameters:

left : scalar, optional

The left xlim (default: None, which leaves the left limit unchanged).

right : scalar, optional

The right xlim (default: None, which leaves the right limit unchanged).

emit : bool, optional

Whether to notify observers of limit change (default: True).

auto : bool or None, optional

Whether to turn on autoscaling of the x-axis. True turns on, False turns off (default action), None leaves unchanged.

xlimits : tuple, optional

The left and right xlims may be passed as the tuple (left, right) as the first positional argument (or as the left keyword argument).

Returns:

xlimits : tuple

Returns the new x-axis limits as (left, right).

Notes

The left value may be greater than the right value, in which case the x-axis values will decrease from left to right.

Examples

>>> set_xlim(left, right)
>>> set_xlim((left, right))
>>> left, right = set_xlim(left, right)

One limit may be left unchanged.

>>> set_xlim(right=right_lim)

Limits may be passed in reverse order to flip the direction of the x-axis. For example, suppose x represents the number of years before present. The x-axis limits might be set like the following so 5000 years ago is on the left of the plot and the present is on the right.

>>> set_xlim(5000, 0)
set_xscale(*args, **kwargs)[source]

Set the x-axis scale.

Parameters:

value : {“linear”, “log”, “symlog”, “logit”}

scaling strategy to apply

Notes

Different kwargs are accepted, depending on the scale. See the scale module for more information.

set_ylabel(*args, **kwargs)[source]

Set the label for the y-axis.

Parameters:

ylabel : str

The label text.

labelpad : scalar, optional, default: None

Spacing in points between the label and the y-axis.

Other Parameters:
 

**kwargs : Text properties

Text properties control the appearance of the label.

See also

text
for information on how override and the optional args work
set_ylim(*args, **kwargs)[source]

Set the data limits for the y-axis

Parameters:

bottom : scalar, optional

The bottom ylim (default: None, which leaves the bottom limit unchanged).

top : scalar, optional

The top ylim (default: None, which leaves the top limit unchanged).

emit : bool, optional

Whether to notify observers of limit change (default: True).

auto : bool or None, optional

Whether to turn on autoscaling of the y-axis. True turns on, False turns off (default action), None leaves unchanged.

ylimits : tuple, optional

The bottom and top yxlims may be passed as the tuple (bottom, top) as the first positional argument (or as the bottom keyword argument).

Returns:

ylimits : tuple

Returns the new y-axis limits as (bottom, top).

Notes

The bottom value may be greater than the top value, in which case the y-axis values will decrease from bottom to top.

Examples

>>> set_ylim(bottom, top)
>>> set_ylim((bottom, top))
>>> bottom, top = set_ylim(bottom, top)

One limit may be left unchanged.

>>> set_ylim(top=top_lim)

Limits may be passed in reverse order to flip the direction of the y-axis. For example, suppose y represents depth of the ocean in m. The y-axis limits might be set like the following so 5000 m depth is at the bottom of the plot and the surface, 0 m, is at the top.

>>> set_ylim(5000, 0)
set_yscale(*args, **kwargs)[source]

Set the y-axis scale.

Parameters:

value : {“linear”, “log”, “symlog”, “logit”}

scaling strategy to apply

Notes

Different kwargs are accepted, depending on the scale. See the scale module for more information.

show(block=None, warn=True)[source]

Display the current figure (if possible)

Parameters:

block : bool, default: None

open the figure and block until the figure is closed, otherwise open the figure as a detached window. If block=None, GWpy will block if using an interactive backend and not in an ipython session.

warn : bool, default: True

if block=False is given, print a warning if matplotlib is not running in an interactive backend and cannot display the figure.

Notes

If blocking is employed, this method calls the pyplot.show function, otherwise the show() method of this Figure is used.

title

title for the current axes

xlabel

x-axis label for the current axes

xlim

x-axis limits for the current axes

ylabel

y-axis label for the current axes

ylim

y-axis limits for the current axes

class gwpy.plotter.TimeSeriesPlot(*series, **kwargs)[source]

Bases: gwpy.plotter.series.SeriesPlot

Figure for displaying a TimeSeries.

Parameters:

*series : TimeSeries

any number of TimeSeries to display on the plot

**kwargs

other keyword arguments as applicable for the Plot

add_state_segments(segments, ax=None, height=0.2, pad=0.1, location='bottom', plotargs={})[source]

Add a SegmentList to this TimeSeriesPlot indicating state information about the main Axes data.

By default, segments are displayed in a thin horizontal set of Axes sitting immediately below the x-axis of the main

Parameters:

segments : DataQualityFlag

A data-quality flag, or SegmentList denoting state segments about this Plot

ax : Axes

specific Axes set against which to anchor new segment Axes

plotargs

keyword arguments passed to plot()

add_timeseries(timeseries, **kwargs)[source]

Add a TimeSeries trace to this plot

Parameters:

timeseries : TimeSeries

the TimeSeries to display

ax : Axes

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional

force data to plot on a fresh set of Axes

**kwargs

other keyword arguments for the Plot.add_array function

Returns:

line : Line2D

the newly added line object

epoch

The GPS epoch of this plot

get_epoch()[source]

Return the GPS epoch of this plot

set_epoch(*args, **kwargs)[source]

Set the GPS epoch of this plot

class gwpy.plotter.FrequencySeriesPlot(*series, **kwargs)[source]

Bases: gwpy.plotter.series.SeriesPlot

Figure for displaying a FrequencySeries

class gwpy.plotter.SpectrogramPlot(*args, **kwargs)[source]

Bases: gwpy.plotter.timeseries.TimeSeriesPlot

Figure for displaying a Spectrogram.

class gwpy.plotter.SegmentPlot(*flags, **kwargs)[source]

Bases: gwpy.plotter.timeseries.TimeSeriesPlot

Plot for displaying a DataQualityFlag

Parameters:

*flags : DataQualityFlag

any number of DataQualityFlag to display on the plot

insetlabels : bool, default: False

display segment labels inside the axes. Prevents very long segment names from getting squeezed off the end of a standard figure

**kwargs

other keyword arguments as applicable for the Plot

add_bitmask(mask, ax=None, width=0.2, pad=0.1, visible=True, axes_class=<class 'gwpy.plotter.segments.SegmentAxes'>, topdown=False, **plotargs)[source]

Display a state-word bitmask on a new set of Axes.

add_dataqualityflag(flag, **kwargs)[source]

Add a DataQualityFlag to this plot

Parameters:

flag : DataQualityFlag

the DataQualityFlag to display

projection : str

name of the Axes projection on which to plot

ax : Axes

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional

force data to plot on a fresh set of Axes

**kwargs

other keyword arguments for the Plot.add_line function

Returns:

collection : Collection

the newly added patch collection

class gwpy.plotter.EventTablePlot(*args, **kwargs)[source]

Bases: gwpy.plotter.timeseries.TimeSeriesPlot, gwpy.plotter.frequencyseries.FrequencySeriesPlot, gwpy.plotter.core.Plot

Figure for displaying a EventTable

Parameters:

table : EventTable

Table to display

x : str

name of column to display on the X-axis

y : str

name of column to display on the Y-axis

c : str, optional

name of column by which to colour the data

**kwargs

any other arguments applicable to the Plot constructor, and the Table plotter.

Returns:

plot : EventTablePlot

new plot for displaying tabular data.

Notes

The form of the returned EventTablePlot is decided at run-time, rather than when the module was imported. If tables are passed directly to the constructor, for example:

>>> plot = EventTablePlot(table1, 'time', 'snr')

the columns as given are used to determine the appropriate parent class for the output.

If the input x-column (the first string argument) ends with ‘time’ the output is a child of the TimeSeriesPlot, allowing easy formatting of GPS times, while if the x-column ends with ‘frequency’, the output comes from the FrequencySeriesPlot, otherwise the parent is the core Plot.

add_table(table, x, y, color=None, projection='triggers', ax=None, newax=None, **kwargs)[source]

Add a Table to this Plot

Parameters:

table : Table, EventTable

Table to display

x : str

name of column to display on the X-axis

y : str

name of column to display on the Y-axis

c : str, optional

name of column by which to colour the data

projection : str, optiona, default: 'triggers'

name of the Axes projection on which to plot data

ax : Axes, optional

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional, default: False

force data to plot on a fresh set of Axes

**kwargs.

other keyword arguments passed to the EventTableAxes.plot_table() method

Returns:

scatter : Collection

the displayed collection for this Table

See also

EventTableAxes.plot_table()
for details on arguments and keyword arguments other than ax and newax for this method.
add_tiles(table, x, y, width, height, color=None, anchor='center', projection='triggers', ax=None, newax=None, **kwargs)[source]

Add a Table to this Plot

Parameters:

table : Table, EventTable

Table to display

x : str

name of column for tile x-anchor

y : str

name of column for tile y-anchor

width : str

name of column for tile width

height : str

name of column for tile height

color : str, optional

name of column by which to colour the data

anchor : str, optional, default: 'center'

position of (x, y) vertex on tile, default ‘center’. Other options: ‘ll’, ‘lr’, ‘ul’, ‘ur’.

projection : str, optiona, default: 'triggers'

name of the Axes projection on which to plot data

ax : Axes, optional

the Axes on which to add these data, if this is not given, a guess will be made as to the best Axes to use. If no appropriate axes are found, new Axes will be created

newax : bool, optional, default: False

force data to plot on a fresh set of Axes

**kwargs.

other keyword arguments passed to the EventTableAxes.plot_table() method

Returns:

scatter : Collection

the displayed collection for this Table

See also

EventTableAxes.plot_table()
for details on arguments and keyword arguments other than ax and newax for this method.
class gwpy.plotter.BodePlot(*filters, **kwargs)[source]

Bases: gwpy.plotter.core.Plot

A Plot class for visualising transfer functions

Parameters:

*filters : lti, FrequencySeries

any number of the following:

  • linear time-invariant filters, either lti or tuple of the following length and form: - 2: (numerator, denominator) - 3: (zeros, poles, gain) - 4: (A, B, C, D)
  • complex-valued spectra representing a transfer function

frequencies : numpy.ndarray, optional

list of frequencies (in Hertz) at which to plot

db : bool, optional, default: True

if True, display magnitude in decibels, otherwise display amplitude.

**kwargs

other keyword arguments as applicable for Plot or plot()

Returns:

plot : BodePlot

a new BodePlot with two Axes - maxes and paxes - representing the magnitude and phase of the input transfer function(s) respectively.

add_filter(filter_, frequencies=None, dB=True, analog=False, sample_rate=None, **kwargs)[source]

Add a linear time-invariant filter to this BodePlot

Parameters:

filter_ : lti, tuple

the filter to plot, either as a lti, or a tuple with the following number and meaning of elements

  • 2: (numerator, denominator)
  • 3: (zeros, poles, gain)
  • 4: (A, B, C, D)

frequencies : numpy.ndarray, optional

list of frequencies (in Hertz) at which to plot

dB : bool, optional

if True, display magnitude in decibels, otherwise display amplitude, default: True

**kwargs

any other keyword arguments accepted by plot()

Returns:

mag, phase : tuple of lines

the lines drawn for the magnitude and phase of the filter.

add_frequencyseries(spectrum, dB=True, power=False, **kwargs)[source]

Plot the magnitude and phase of a complex-valued FrequencySeries

Parameters:

spectrum : FrequencySeries

the (complex-valued) FrequencySeries to display

db : bool, optional, default: True

if True, display magnitude in decibels, otherwise display amplitude.

power : bool, optional, default: False

give True to incidate that spectrum holds power values, so dB = 10 * log(abs(spectrum)), otherwise db = 20 * log(abs(spectrum)). This argument is ignored if db=False.

**kwargs

any other keyword arguments accepted by plot()

Returns:

mag, phase : tuple of lines

the lines drawn for the magnitude and phase of the filter.

maxes

FrequencySeriesAxes for the Bode magnitude

paxes

FrequencySeriesAxes for the Bode phase

Axes objects

Each of the below classes represents a set of axes on which data are displayed; for brevity inherited methods and attributes are not documented here, please follow links to the parent classes for documentation of available methods and attributes.

class gwpy.plotter.Axes(fig, rect, facecolor=None, frameon=True, sharex=None, sharey=None, label=u'', xscale=None, yscale=None, **kwargs)[source]

Bases: matplotlib.axes._axes.Axes

An extension of the core matplotlib Axes.

These custom Axes provide only some simpler attribute accessors.

Notes

A new set of Axes should be constructed via:

>>> plot.add_subplots(111, projection='xxx')

where plot is a Plot, and 'xxx' is the name of the Axes you want to add.

html_map(imagefile, data=None, **kwargs)[source]

Create an HTML map for some data contained in these Axes

Parameters:

data : Artist, Series, array-like

data to map, one of an Artist already drawn on these axes ( via plot() or scatter(), for example) or a data set

imagefile : str

path to image file on disk for the containing Figure

mapname : str, optional

ID to connect <img> tag and <map> tags, default: 'points'. This should be unique if multiple maps are to be written to a single HTML file.

shape : str, optional

shape for <area> tag, default: 'circle'

standalone : bool, optional

wrap map HTML with required HTML5 header and footer tags, default: True

title : str, optional

title name for standalone HTML page

jquery : str, optional

URL of jquery script, defaults to googleapis.com URL

Returns:

HTML : str

string of HTML markup that defines the <img> and <map>

logx[source]

Display the x-axis with a logarithmic scale

Type:bool
logy[source]

Display the y-axis with a logarithmic scale

Type:bool
resize(*args, **kwargs)[source]

Set the axes position with:

>>> pos = [left, bottom, width, height]

in relative 0,1 coords, or pos can be a Bbox

There are two position variables: one which is ultimately used, but which may be modified by apply_aspect(), and a second which is the starting point for apply_aspect().

xlabel[source]

Label for the x-axis

Type:Text
xlim[source]

Limits for the x-axis

Type:tuple
ylabel[source]

Label for the y-axis

Type:Text
ylim[source]

Limits for the y-axis

Type:tuple
class gwpy.plotter.TimeSeriesAxes(*args, **kwargs)[source]

Bases: gwpy.plotter.series.SeriesAxes

Custom Axes for a TimeSeriesPlot.

auto_gps_label()[source]

Automatically set the x-axis label based on the current GPS scale

auto_gps_scale()[source]

Automagically set the GPS scale for the time-axis of this plot based on the current view limits

draw(renderer, *args, **kwargs)[source]

Draw everything (plot lines, axes, labels)

epoch

Return the current GPS epoch (t=0)

get_epoch()[source]

Return the current GPS epoch (t=0)

plot(*args, **kwargs)[source]

Plot data onto these Axes.

Parameters:

args

a single TimeSeries (or sub-class) or standard (x, y) data arrays

kwargs

keyword arguments applicable to plot()

Returns:

Line2D

the Line2D for this line layer

See also

matplotlib.axes.Axes.plot
for a full description of acceptable *args and **kwargs
plot_array2d(spectrogram, **kwargs)[source]

Plot a 2D array onto these axes

Parameters:

array : Array2D,

Data to plot (e.g. a Spectrogram)

imshow : bool, optional

If True, use imshow() to render the array as an image, otherwise use pcolormesh(), default is True with matplotlib >= 2.0, otherwise False.

norm : 'log', Normalize

A Normalize` instance used to scale the colour data, or 'log' to use LogNorm.

**kwargs

Any other keyword arguments acceptable for imshow() (if imshow=True), or pcolormesh() (imshow=False)

Returns:

layer : QuadMesh, Image

the layer for this array

See also

matplotlib.axes.Axes.imshow

matplotlib.axes.Axes.pcolormesh
for a full description of acceptable *args and **kwargs
plot_series(*args, **kwargs)[source]

Plot a Series onto these axes

Parameters:

series : Series

data to plot

**kwargs

any other keyword arguments acceptable for plot()

Returns:

line : Line2D

the newly added line

See also

matplotlib.axes.Axes.plot
for a full description of acceptable *args and **kwargs
plot_spectrogram(spectrogram, **kwargs)[source]

Plot a 2D array onto these axes

Parameters:

array : Array2D,

Data to plot (e.g. a Spectrogram)

imshow : bool, optional

If True, use imshow() to render the array as an image, otherwise use pcolormesh(), default is True with matplotlib >= 2.0, otherwise False.

norm : 'log', Normalize

A Normalize` instance used to scale the colour data, or 'log' to use LogNorm.

**kwargs

Any other keyword arguments acceptable for imshow() (if imshow=True), or pcolormesh() (imshow=False)

Returns:

layer : QuadMesh, Image

the layer for this array

See also

matplotlib.axes.Axes.imshow

matplotlib.axes.Axes.pcolormesh
for a full description of acceptable *args and **kwargs
plot_timeseries(*args, **kwargs)[source]

Plot a Series onto these axes

Parameters:

series : Series

data to plot

**kwargs

any other keyword arguments acceptable for plot()

Returns:

line : Line2D

the newly added line

See also

matplotlib.axes.Axes.plot
for a full description of acceptable *args and **kwargs
set_epoch(epoch)[source]

Set the GPS epoch (t=0) for these axes

set_xlim(left=None, right=None, emit=True, auto=False, **kw)[source]

Set the data limits for the x-axis

Parameters:

left : scalar, optional

The left xlim (default: None, which leaves the left limit unchanged).

right : scalar, optional

The right xlim (default: None, which leaves the right limit unchanged).

emit : bool, optional

Whether to notify observers of limit change (default: True).

auto : bool or None, optional

Whether to turn on autoscaling of the x-axis. True turns on, False turns off (default action), None leaves unchanged.

xlimits : tuple, optional

The left and right xlims may be passed as the tuple (left, right) as the first positional argument (or as the left keyword argument).

Returns:

xlimits : tuple

Returns the new x-axis limits as (left, right).

Notes

The left value may be greater than the right value, in which case the x-axis values will decrease from left to right.

Examples

>>> set_xlim(left, right)
>>> set_xlim((left, right))
>>> left, right = set_xlim(left, right)

One limit may be left unchanged.

>>> set_xlim(right=right_lim)

Limits may be passed in reverse order to flip the direction of the x-axis. For example, suppose x represents the number of years before present. The x-axis limits might be set like the following so 5000 years ago is on the left of the plot and the present is on the right.

>>> set_xlim(5000, 0)
set_xscale(scale, *args, **kwargs)[source]

Set the x-axis scale.

Parameters:

value : {“linear”, “log”, “symlog”, “logit”}

scaling strategy to apply

Notes

Different kwargs are accepted, depending on the scale. See the scale module for more information.

class gwpy.plotter.FrequencySeriesAxes(*args, **kwargs)[source]

Bases: gwpy.plotter.series.SeriesAxes

Custom Axes for a FrequencySeriesPlot.

plot(*args, **kwargs)[source]

Plot data onto these Axes.

Parameters:

args

a single FrequencySeries (or sub-class) or standard (x, y) data arrays

kwargs

keyword arguments applicable to plot()

Returns:

Line2D

the Line2D for this line layer

See also

matplotlib.axes.Axes.plot
for a full description of acceptable *args and **kwargs
plot_frequencyseries(*args, **kwargs)[source]

Plot a Series onto these axes

Parameters:

series : Series

data to plot

**kwargs

any other keyword arguments acceptable for plot()

Returns:

line : Line2D

the newly added line

See also

matplotlib.axes.Axes.plot
for a full description of acceptable *args and **kwargs
plot_variance(*args, **kwargs)[source]

Plot a SpectralVariance onto these axes

Parameters:

spectrum : class:SpectralVariance

data to plot

**kwargs

any other eyword arguments acceptable for pcolormesh()

Returns:

mesh : MeshGrid

the collection that has just been added

See also

matplotlib.axes.Axes.pcolormesh
for a full description of acceptable *args and **kwargs
class gwpy.plotter.SegmentAxes(*args, **kwargs)[source]

Bases: gwpy.plotter.timeseries.TimeSeriesAxes

Custom Axes for a SegmentPlot.

This SegmentAxes provides custom methods for displaying any of

Parameters:

insetlabels : bool, default: False

display segment labels inside the axes. Prevents very long segment names from getting squeezed off the end of a standard figure

See also

gwpy.plotter.TimeSeriesAxes
for documentation of other args and kwargs
static build_segment(segment, y, height=0.8, valign='center', **kwargs)[source]

Build a Rectangle to display a single Segment

Parameters:

segment : Segment

[start, stop) GPS segment

y : float

y-axis position for segment

height : float, optional, default: 1

height (in y-axis units) for segment

valign : str

alignment of segment on y-axis value: top, center, or bottom

**kwargs

any other keyword arguments acceptable for Rectangle

Returns:

box : Rectangle

rectangle patch for segment display

draw(renderer, *args, **kwargs)[source]

Draw everything (plot lines, axes, labels)

get_collections(ignore=None)[source]

Return the collections matching the given _ignore value

Parameters:

ignore : bool, or None

value of _ignore to match

Returns:

collections : list

if ignore=None, simply returns all collections, otherwise returns those collections matching the ignore parameter

get_insetlabels()[source]

Returns the inset labels state

get_next_y()[source]

Find the next y-axis value at which a segment list can be placed

This method simply counts the number of independent segmentlists or flags that have been plotted onto these axes.

insetlabels

Returns the inset labels state

plot(*args, **kwargs)[source]

Plot data onto these axes

Parameters:

args

a single instance of

or equivalent types upstream from ligo.segments

kwargs

keyword arguments applicable to plot

Returns:

Line2D

the Line2D for this line layer

See also

matplotlib.axes.Axes.plot()
for a full description of acceptable *args` and ``**kwargs
plot_dqdict(*args, **kwargs)[source]

Plot a DataQualityDict onto these axes

Parameters:

flags : DataQualityDict

data-quality dict to display

label : str, optional

labelling system to use, or fixed label for all DataQualityFlags. Special values include

  • 'key': use the key of the DataQualityDict,
  • 'name': use the name of the DataQualityFlag

If anything else, that fixed label will be used for all lines.

known : str, dict, None, default: ‘/’

display known segments with the given hatching, or give a dict of keyword arguments to pass to plot_segmentlist(), or None to hide.

**kwargs

any other keyword arguments acceptable for Rectangle

Returns:

collection : PatchCollection

list of Rectangle patches

plot_dqflag(*args, **kwargs)[source]

Plot a DataQualityFlag onto these axes

Parameters:

flag : DataQualityFlag

data-quality flag to display

y : float, optional

y-axis value for new segments

height : float, optional, default: 0.8

height for each segment block

known : str, dict, None, default: ‘/’

display known segments with the given hatching, or give a dict of keyword arguments to pass to plot_segmentlist(), or None to hide.

**kwargs

any other keyword arguments acceptable for Rectangle

Returns:

collection : PatchCollection

list of Rectangle patches

plot_segmentlist(*args, **kwargs)[source]

Plot a SegmentList onto these axes

Parameters:

segmentlist : SegmentList

list of segments to display

y : float, optional

y-axis value for new segments

collection : bool, default: True

add all patches as a PatchCollection, doesn’t seem to work for hatched rectangles

label : str, optional

custom descriptive name to print as y-axis tick label

**kwargs

any other keyword arguments acceptable for Rectangle

Returns:

collection : PatchCollection

list of Rectangle patches

plot_segmentlistdict(*args, **kwargs)[source]

Plot a SegmentListDict onto these axes

Parameters:

segmentlistdict : SegmentListDict

(name, SegmentList) dict

y : float, optional

starting y-axis value for new segmentlists

**kwargs

any other keyword arguments acceptable for Rectangle

Returns:

collections : list

list of PatchCollection sets for each segmentlist

set_insetlabels(inset=None)[source]

Set the labels to be inset or not

Parameters:

inset : bool, None

if None, toggle the inset state, otherwise set the labels to be inset (True) or not (`False)

set_xlim(*args, **kwargs)[source]

Set the data limits for the x-axis

Parameters:

left : scalar, optional

The left xlim (default: None, which leaves the left limit unchanged).

right : scalar, optional

The right xlim (default: None, which leaves the right limit unchanged).

emit : bool, optional

Whether to notify observers of limit change (default: True).

auto : bool or None, optional

Whether to turn on autoscaling of the x-axis. True turns on, False turns off (default action), None leaves unchanged.

xlimits : tuple, optional

The left and right xlims may be passed as the tuple (left, right) as the first positional argument (or as the left keyword argument).

Returns:

xlimits : tuple

Returns the new x-axis limits as (left, right).

Notes

The left value may be greater than the right value, in which case the x-axis values will decrease from left to right.

Examples

>>> set_xlim(left, right)
>>> set_xlim((left, right))
>>> left, right = set_xlim(left, right)

One limit may be left unchanged.

>>> set_xlim(right=right_lim)

Limits may be passed in reverse order to flip the direction of the x-axis. For example, suppose x represents the number of years before present. The x-axis limits might be set like the following so 5000 years ago is on the left of the plot and the present is on the right.

>>> set_xlim(5000, 0)
class gwpy.plotter.EventTableAxes(fig, *args, **kwargs)[source]

Bases: gwpy.plotter.timeseries.TimeSeriesAxes

Custom Axes for an ~gwpy.plotter.EventTablePlot`.

The EventTableAxes inherit from ~gwpy.plotter.TimeSeriesAxes` as a convenience to optionally displaying a time-column. That choice has no effect on the rest of the Axes functionality.

add_loudest(table, rank, x, y, *columns, **kwargs)[source]

Display the loudest event according to some rank.

The loudest event is displayed as a gold star at its position given by the values in columns x, and y, and those values are displayed in a text box.

Parameters:

table : EventTable

event table in which to find the loudest event

rank : str

name of column to use for ranking

x : str

name of column to display on the X-axis

y : str

name of column to display on the Y-axis

**kwargs

any other arguments applicable to text()

Returns:

collection : PolyCollection

the collection returned by Axesscatter() when marking the loudest event

text : Text

the text added to these Axes with loudest event parameters

plot(*args, **kwargs)[source]

Plot data onto these axes

Parameters:

*args

a single ~astropy.tableTable` (or sub-class) or anything valid for plot()

**kwargs

keyword arguments applicable to plot()

plot_table(table, x, y, color=None, edgecolor='none', size_by=None, size_by_log=None, size_range=None, **kwargs)[source]

Plot a Table onto these Axes

Parameters:

table : Table, EventTable

data table to plot

x : str

name of column to display on the X-axis

y : str

name of column to display on the Y-axis

color : str, optional

name of column by which to colour the data

**kwargs

any other arguments applicable to scatter()

Returns:
collection
plot_tiles(table, x, y, width, height, color=None, anchor='center', edgecolors='face', linewidth=0.8, **kwargs)[source]

Plot a Table onto these Axes using rectangular tiles

Parameters:

table : Table, EventTable

data table to plot

x : str

name of column to display on the X-axis

y : str

name of column to display on the Y-axis

width : str

name of column defining horizontal extent of tiles

height : str

name of column defining vertical extent of tiles

color : str, optional

name of column by which to colour the data

anchor : str, optional

anchor point for tiles relative to (x, y) coordinates, one of

  • 'center' - center tile on (x, y)
  • 'll' - (x, y) defines lower-left corner of tile
  • 'lr' - (x, y) defines lower-right corner of tile
  • 'ul' - (x, y) defines upper-left corner of tile
  • 'ur' - (x, y) defines upper-right corner of tile

**kwargs

any other arguments applicable to scatter()

Returns:

collection : PolyCollection

the collection of tiles drawn