Plotting API¶

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.

Attributes Summary

logx	View x-axis in logarithmic scale
logy	View y-axis in logarithmic scale
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

Methods Summary

add_array(artist, *args, **kwargs)	Add a Array to this plot
add_colorbar(artist, *args, **kwargs)	Add a colorbar to the current Axes
add_dataqualityflag(flag[, projection, ax, ...])	Add a DataQualityFlag to this plot
add_frequencyseries(artist, *args, **kwargs)	Add a FrequencySeries trace to this plot
add_image(artist, *args, **kwargs)	Add a 2-D image to this plot
add_legend(artist, *args, **kwargs)	Add a legend to this Plot on the most favourable Axes
add_line(artist, *args, **kwargs)	Add a line to the current plot
add_scatter(artist, *args, **kwargs)	Add a set or points to the current plot
add_spectrogram(artist, *args, **kwargs)	Add a Spectrogram trace to
add_spectrum(artist, *args, **kwargs)	Add a FrequencySeries trace to this plot
add_subplot(*args, **kwargs)	Add a subplot.
add_timeseries(artist, *args, **kwargs)	Add a TimeSeries trace to this plot
close()	Close the plot and release its memory.
get_auto_refresh()	Return this `Plot`s auto-refresh setting
get_axes([projection])	Find all Axes, optionally matching the given projection
get_title(figure, *args, **kwargs)	Get an axes title.
get_xlabel(figure, *args, **kwargs)	Get the xlabel text string.
get_xlim(figure, *args, **kwargs)	Get the x-axis range [left, right]
get_xscale(figure, *args, **kwargs)	Return the xaxis scale string: linear, log, logit, symlog
get_ylabel(figure, *args, **kwargs)	Get the ylabel text string.
get_ylim(figure, *args, **kwargs)	Get the y-axis range [bottom, top]
get_yscale(figure, *args, **kwargs)	Return the yaxis scale string: linear, log, logit, symlog
html_map(figure, *args, **kwargs)	Create an HTML map for some data contained in these Axes
refresh()	Refresh the current figure
save(*args, **kwargs)	Save the figure to disk.
set_auto_refresh(b)	Set this `Plot`s auto-refresh setting
set_title(artist, *args, **kwargs)	Set a title for the axes.
set_xlabel(figure, *args, **kwargs)	Set the label for the xaxis.
set_xlim(artist, *args, **kwargs)	Call signature:
set_xscale(artist, *args, **kwargs)	Call signature:
set_ylabel(artist, *args, **kwargs)	Set the label for the yaxis
set_ylim(artist, *args, **kwargs)	Call signature:
set_yscale(artist, *args, **kwargs)	Call signature:
show([block, warn])	Display the current figure (if possible)

Attributes Documentation

logx¶

View x-axis in logarithmic scale

logy¶

View y-axis in logarithmic scale

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

Methods Documentation

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

Add a Array to this plot

Parameters:	array : Array the Array to display projection : str 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, default: False 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(artist, *args, **kwargs)[source]¶

Add a colorbar to the current Axes

Parameters:

mappable : matplotlib data collection collection against which to map the colouring ax : Axes axes from which to steal space for the colour-bar location : str, optional, default: ‘right’ position of the colorbar width : float, optional default: 0.2 width of the colorbar as a fraction of the axes pad : float, optional, default: 0.1 gap between the axes and the colorbar as a fraction of the axes log : bool, optional, default: False display the colorbar with a logarithmic scale label : str, optional, default: ‘’ (no label) label for the colorbar clim : pair of floats, optional (lower, upper) limits for the colorbar scale, values outside of these limits will be clipped to the edges visible : bool, optional, default: True 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:

Colorbar : the Colorbar added to this plot

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

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

Add a FrequencySeries trace to this plot

Parameters:

spectrum : FrequencySeries the FrequencySeries to display projection : str, optional, default: 'frequencyseries' 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, default: False force data to plot on a fresh set of Axes **kwargs : other keyword arguments for the Plot.add_line function

Returns:

Line2D : the Line2D for this line layer

add_image(artist, *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

add_legend(artist, *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 : the Legend for this plot

add_line(artist, *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, default: None 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, default: False force data to plot on a fresh set of Axes **kwargs : additional keyword arguments passed directly on to the axes plot() method.

Returns:

Line2D : the Line2D for this line layer

add_scatter(artist, *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, default: None 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, default: False force data to plot on a fresh set of Axes **kwargs. : other keyword arguments passed to the matplotlib.axes.Axes.scatter() function

Returns:

Collection : the Collection for this scatter layer

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

Add a Spectrogram trace to this plot

Parameters:

spectrogram : Spectrogram the Spectrogram to display projection : str, optional, default: timeseries 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, default: False force data to plot on a fresh set of Axes **kwargs : other keyword arguments for the Plot.add_line function

Returns:

Line2D : the Line2D for this line layer

add_spectrum(artist, *args, **kwargs)[source]¶

Add a FrequencySeries trace to this plot

Parameters:

spectrum : FrequencySeries the FrequencySeries to display projection : str, optional, default: 'frequencyseries' 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, default: False force data to plot on a fresh set of Axes **kwargs : other keyword arguments for the Plot.add_line function

Returns:

Line2D : the Line2D for this line layer

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

Add a subplot. Examples:

fig.add_subplot(111)

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

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

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

# add Subplot instance sub
fig.add_subplot(sub)

kwargs are legal Axes kwargs plus projection, which chooses a projection type for the axes. (For backward compatibility, polar=True may also be provided, which is equivalent to projection=’polar’). Valid values for projection are: [u’aitoff’, u’hammer’, u’lambert’, u’mollweide’, u’polar’, u’rectilinear’]. Some of these projections support additional kwargs, which may be provided to add_axes().

The Axes instance will be returned.

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

See also

subplot() for an explanation of the args.

The following kwargs are supported:

adjustable: [ ‘box’ | ‘datalim’ | ‘box-forced’] agg_filter: unknown alpha: float (0.0 transparent through 1.0 opaque) anchor: unknown animated: [True | False] aspect: unknown autoscale_on: unknown autoscalex_on: unknown autoscaley_on: unknown axes: an Axes instance axes_locator: unknown axis_bgcolor: any matplotlib color - see colors() axisbelow: [ True | False ] clip_box: a matplotlib.transforms.Bbox instance clip_on: [True | False] clip_path: [ (Path, Transform) | Patch | None ] color_cycle: unknown contains: a callable function figure: unknown frame_on: [ True | False ] gid: an id string label: string or anything printable with ‘%s’ conversion. navigate: [ True | False ] navigate_mode: unknown path_effects: unknown picker: [None|float|boolean|callable] position: unknown rasterization_zorder: unknown rasterized: [True | False | None] sketch_params: unknown snap: unknown title: unknown transform: Transform instance url: a url string visible: [True | False] xbound: unknown xlabel: unknown xlim: length 2 sequence of floats xmargin: unknown xscale: [u’linear’ | u’log’ | u’logit’ | u’symlog’] xticklabels: sequence of strings xticks: sequence of floats ybound: unknown ylabel: unknown ylim: length 2 sequence of floats ymargin: unknown yscale: [u’linear’ | u’log’ | u’logit’ | u’symlog’] yticklabels: sequence of strings yticks: sequence of floats zorder: any number

add_timeseries(artist, *args, **kwargs)[source]¶

Add a TimeSeries trace to this plot

Parameters:

timeseries : TimeSeries the TimeSeries to display projection : str, optional, default: 'timeseries' 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, default: False force data to plot on a fresh set of Axes **kwargs : other keyword arguments for the Plot.add_line function

Returns:

Line2D : the Line2D for this line layer

close()[source]¶

Close the plot and release its memory.

get_auto_refresh()[source]¶

Return this `Plot`s auto-refresh setting

get_axes(projection=None)[source]¶

Find all Axes, optionally matching the given projection

Parameters:	projection : str name of axes types to return

get_title(figure, *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(figure, *args, **kwargs)[source]¶

Get the xlabel text string.

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

Get the x-axis range [left, right]

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

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

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

Get the ylabel text string.

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

Get the y-axis range [bottom, top]

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

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

html_map(figure, *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>

refresh()[source]¶

Refresh the current figure

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

Save the figure to disk.

All args and kwargs are passed directly to the savefig method of the underlying matplotlib.figure.Figure self.fig.savefig(*args, **kwargs)

set_auto_refresh(b)[source]¶

Set this `Plot`s auto-refresh setting

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

Parameters:	b : True or False

set_title(artist, *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’
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(figure, *args, **kwargs)[source]¶

Set the label for the xaxis.

Parameters:	xlabel : string x label labelpad : scalar, optional, default: None spacing in points between the label and the x-axis
Other Parameters:
	kwargs : Text properties

See also

text

for information on how override and the optional args work

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

Call signature:

set_xlim(self, *args, **kwargs):

Set the data limits for the xaxis

Examples:

set_xlim((left, right))
set_xlim(left, right)
set_xlim(left=1) # right unchanged
set_xlim(right=1) # left unchanged

Keyword arguments:

left: scalar

The left xlim; xmin, the previous name, may still be used

right: scalar

The right xlim; xmax, the previous name, may still be used

emit: [ True | False ]

Notify observers of limit change

auto: [ True | False | None ]

Turn x autoscaling on (True), off (False; default), or leave unchanged (None)

Note, the left (formerly xmin) value may be greater than the right (formerly xmax). For example, suppose x is years before present. Then one might use:

set_ylim(5000, 0)

so 5000 years ago is on the left of the plot and the present is on the right.

Returns the current xlimits as a length 2 tuple

ACCEPTS: length 2 sequence of floats

set_xscale(artist, *args, **kwargs)[source]¶

Call signature:

set_xscale(value)

Set the scaling of the x-axis: u’linear’ | u’log’ | u’logit’ | u’symlog’

ACCEPTS: [u’linear’ | u’log’ | u’logit’ | u’symlog’]

Different kwargs are accepted, depending on the scale:

‘linear’

‘log’

basex/basey:

The base of the logarithm

nonposx/nonposy: [‘mask’ | ‘clip’ ]

non-positive values in x or y can be masked as invalid, or clipped to a very small positive number

subsx/subsy:

Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]

will place 8 logarithmically spaced minor ticks between each major tick.

‘logit’

nonpos: [‘mask’ | ‘clip’ ]

values beyond ]0, 1[ can be masked as invalid, or clipped to a number very close to 0 or 1

‘symlog’

basex/basey:

The base of the logarithm

linthreshx/linthreshy:

The range (-x, x) within which the plot is linear (to avoid having the plot go to infinity around zero).

subsx/subsy:

Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]

will place 8 logarithmically spaced minor ticks between each major tick.

linscalex/linscaley:

This allows the linear range (-linthresh to linthresh) to be stretched relative to the logarithmic range. Its value is the number of decades to use for each half of the linear range. For example, when linscale == 1.0 (the default), the space used for the positive and negative halves of the linear range will be equal to one decade in the logarithmic range.

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

Set the label for the yaxis

Parameters:	ylabel : string y label labelpad : scalar, optional, default: None spacing in points between the label and the x-axis
Other Parameters:
	kwargs : Text properties

See also

text

for information on how override and the optional args work

set_ylim(artist, *args, **kwargs)[source]¶

Call signature:

set_ylim(self, *args, **kwargs):

Set the data limits for the yaxis

Examples:

set_ylim((bottom, top))
set_ylim(bottom, top)
set_ylim(bottom=1) # top unchanged
set_ylim(top=1) # bottom unchanged

Keyword arguments:

bottom: scalar

The bottom ylim; the previous name, ymin, may still be used

top: scalar

The top ylim; the previous name, ymax, may still be used

emit: [ True | False ]

Notify observers of limit change

auto: [ True | False | None ]

Turn y autoscaling on (True), off (False; default), or leave unchanged (None)

Note, the bottom (formerly ymin) value may be greater than the top (formerly ymax). For example, suppose y is depth in the ocean. Then one might use:

set_ylim(5000, 0)

so 5000 m depth is at the bottom of the plot and the surface, 0 m, is at the top.

Returns the current ylimits as a length 2 tuple

ACCEPTS: length 2 sequence of floats

set_yscale(artist, *args, **kwargs)[source]¶

Call signature:

set_yscale(value)

Set the scaling of the y-axis: u’linear’ | u’log’ | u’logit’ | u’symlog’

ACCEPTS: [u’linear’ | u’log’ | u’logit’ | u’symlog’]

Different kwargs are accepted, depending on the scale:

‘linear’

‘log’

basex/basey:

The base of the logarithm

nonposx/nonposy: [‘mask’ | ‘clip’ ]

non-positive values in x or y can be masked as invalid, or clipped to a very small positive number

subsx/subsy:

Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]

will place 8 logarithmically spaced minor ticks between each major tick.

‘logit’

nonpos: [‘mask’ | ‘clip’ ]

values beyond ]0, 1[ can be masked as invalid, or clipped to a number very close to 0 or 1

‘symlog’

basex/basey:

The base of the logarithm

linthreshx/linthreshy:

The range (-x, x) within which the plot is linear (to avoid having the plot go to infinity around zero).

subsx/subsy:

Where to place the subticks between each major tick. Should be a sequence of integers. For example, in a log10 scale: [2, 3, 4, 5, 6, 7, 8, 9]

will place 8 logarithmically spaced minor ticks between each major tick.

linscalex/linscaley:

This allows the linear range (-linthresh to linthresh) to be stretched relative to the logarithmic range. Its value is the number of decades to use for each half of the linear range. For example, when linscale == 1.0 (the default), the space used for the positive and negative halves of the linear range will be equal to one decade in the logarithmic range.

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.

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

Bases: gwpy.plotter.core.Plot

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

Attributes Summary

epoch

Find the GPS epoch of this plot

Methods Summary

add_state_segments(segments[, ax, height, ...])	Add a SegmentList to this TimeSeriesPlot indicating state information about the main Axes data.
add_timeseries(timeseries, **kwargs)
get_epoch()
set_epoch(artist, *args, **kwargs)	Set the GPS epoch of this plot

Attributes Documentation

epoch¶

Find the GPS epoch of this plot

Methods Documentation

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]¶

get_epoch()[source]¶

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

Set the GPS epoch of this plot

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

Bases: gwpy.plotter.core.Plot

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

Figure 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

Methods Summary

add_bitmask(mask[, ax, width, pad, visible, ...])	Display a state-word bitmask on a new set of Axes.
add_dataqualityflag(flag, **kwargs)	Add a DataQualityFlag to this plot

Methods Documentation

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

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

Bases: gwpy.plotter.timeseries.TimeSeriesPlot

Figure for displaying a Table.

Parameters:	table : Table LIGO_LW-format XML event 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.

Methods Summary

add_table(table, x, y[, color, projection, ...])	Add a LIGO_LW Table to this Plot
add_tiles(table, x, y, width, height[, ...])	Add a LIGO_LW Table to this Plot

Methods Documentation

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

Add a LIGO_LW Table to this Plot

Parameters:

table : Table LIGO_LW-format XML event 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 LIGO_LW Table to this Plot

Parameters:

table : Table LIGO_LW-format XML event 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, tuple 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.

Attributes Summary

maxes	FrequencySeriesAxes for the Bode magnitude
paxes	FrequencySeriesAxes for the Bode phase

Methods Summary

add_filter(filter_[, frequencies, dB])	Add a linear time-invariant filter to this BodePlot
add_frequencyseries(spectrum[, dB, power])	Plot the magnitude and phase of a complex-valued FrequencySeries
add_spectrum(*args, **kwargs)

Attributes Documentation

maxes¶

FrequencySeriesAxes for the Bode magnitude

paxes¶

FrequencySeriesAxes for the Bode phase

Methods Documentation

add_filter(filter_, frequencies=None, dB=True, **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, default: True if True, display magnitude in decibels, otherwise display amplitude. **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 given 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.

add_spectrum(*args, **kwargs)[source]¶

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(*args, **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 figure, and 'xxx' is the name of the Axes you want to add.

Attributes Summary

logx	Display the x-axis with a logarithmic scale
logy	Display the y-axis with a logarithmic scale
projection
xlabel	Label for the x-axis
xlim	Limits for the x-axis
ylabel	Label for the y-axis
ylim	Limits for the y-axis

Methods Summary

add_label_unit(artist, *args, **kwargs)
html_map(imagefile[, data])	Create an HTML map for some data contained in these Axes
resize(artist, *args, **kwargs)	Set the axes position with:

Attributes Documentation

logx¶

Display the x-axis with a logarithmic scale

Type:	bool

logy¶

Display the y-axis with a logarithmic scale

Type:	bool

projection = 'rectilinear'¶

xlabel¶

Label for the x-axis

Type:	Text

xlim¶

Limits for the x-axis

Type:	tuple

ylabel¶

Label for the y-axis

Type:	Text

ylim¶

Limits for the y-axis

Type:	tuple

Methods Documentation

add_label_unit(artist, *args, **kwargs)[source]¶

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>

resize(artist, *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().

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

Bases: gwpy.plotter.axes.Axes

Custom Axes for a TimeSeriesPlot.

Attributes Summary

epoch
name

Methods Summary

auto_gps_label()
auto_gps_scale()	Automagically set the GPS scale for the time-axis of this plot
draw(artist, renderer, *args, **kwargs)	Draw everything (plot lines, axes, labels)
get_epoch()
plot(artist, *args, **kwargs)	Plot data onto these Axes.
plot_spectrogram(artist, *args, **kwargs)	Plot a Spectrogram onto
plot_timeseries(artist, *args, **kwargs)	Plot a TimeSeries onto these
plot_timeseries_mmm(artist, *args, **kwargs)	Plot a TimeSeries onto these axes, with (min, max) shaded
set_epoch(epoch)
set_xlim([left, right, emit, auto])	Call signature:
set_xscale(scale, *args, **kwargs)

Attributes Documentation

epoch¶

name = 'timeseries'¶

Methods Documentation

auto_gps_label()[source]¶

auto_gps_scale()[source]¶

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

draw(artist, renderer, *args, **kwargs)¶

Draw everything (plot lines, axes, labels)

get_epoch()[source]¶

plot(artist, *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_spectrogram(artist, *args, **kwargs)[source]¶

Plot a Spectrogram onto these axes

Parameters:	spectrogram : Spectrogram data to plot **kwargs : any other keyword arguments acceptable for 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_timeseries(artist, *args, **kwargs)[source]¶

Plot a TimeSeries onto these axes

Parameters:	timeseries : TimeSeries data to plot **kwargs : any other keyword arguments acceptable for 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_timeseries_mmm(artist, *args, **kwargs)[source]¶

Plot a TimeSeries onto these axes, with (min, max) shaded regions

The mean_ TimeSeries is plotted normally, while the min_ and max_ `TimeSeries are plotted lightly below and above, with a fill between them and the mean_.

Parameters:	mean_ : TimeSeries data to plot normally min_ : TimeSeries first data set to shade to mean_ max_ : TimeSeries second data set to shade to mean_ **kwargs : any other keyword arguments acceptable for plot()
Returns:	artists : tuple a 5-tuple containing (Line2d for mean_, Line2D for min_, PolyCollection for min_ shading, Line2D for max_, and PolyCollection for max_ shading)

See also

matplotlib.axes.Axes.plot()

for a full description of acceptable *args` and ``**kwargs

set_epoch(epoch)[source]¶

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

Call signature:

set_xlim(self, *args, **kwargs):

Set the data limits for the xaxis

Examples:

set_xlim((left, right))
set_xlim(left, right)
set_xlim(left=1) # right unchanged
set_xlim(right=1) # left unchanged

Keyword arguments:

left: scalar

The left xlim; xmin, the previous name, may still be used

right: scalar

The right xlim; xmax, the previous name, may still be used

emit: [ True | False ]

Notify observers of limit change

auto: [ True | False | None ]

Turn x autoscaling on (True), off (False; default), or leave unchanged (None)

Note, the left (formerly xmin) value may be greater than the right (formerly xmax). For example, suppose x is years before present. Then one might use:

set_ylim(5000, 0)

so 5000 years ago is on the left of the plot and the present is on the right.

Returns the current xlimits as a length 2 tuple

ACCEPTS: length 2 sequence of floats

set_xscale(scale, *args, **kwargs)[source]¶

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

Bases: gwpy.plotter.axes.Axes

Custom Axes for a FrequencySeriesPlot.

Attributes Summary

name

Methods Summary

plot(artist, *args, **kwargs)	Plot data onto these Axes.
plot_spectrum(artist, *args, **kwargs)	Plot a FrequencySeries onto these axes
plot_spectrum_mmm(artist, *args, **kwargs)	Plot a FrequencySeries onto these axes, with (min, max) shaded
plot_variance(artist, *args, **kwargs)	Plot a SpectralVariance onto

Attributes Documentation

name = 'frequencyseries'¶

Methods Documentation

plot(artist, *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_spectrum(artist, *args, **kwargs)[source]¶

Plot a FrequencySeries onto these axes

Parameters:	spectrum : FrequencySeries data to plot **kwargs : any other keyword arguments acceptable for 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_spectrum_mmm(artist, *args, **kwargs)[source]¶

Plot a FrequencySeries onto these axes, with (min, max) shaded regions

The mean_ FrequencySeries is plotted normally, while the min_ and `max_ spectra are plotted lightly below and above, with a fill between them and the mean_.

Parameters:	mean_ : :class:`~gwpy.frequencyseries.FrequencySeries data to plot normally min_ : :class:`~gwpy.frequencyseries.FrequencySeries first data set to shade to mean_ max_ : :class:`~gwpy.frequencyseries.FrequencySeries second data set to shade to mean_ alpha : float, optional weight of filled region, 0.0 for transparent through 1.0 opaque **kwargs : any other keyword arguments acceptable for plot()
Returns:	artists : tuple a 5-tuple containing (Line2d for mean_, Line2D for min_, PolyCollection for min_ shading, Line2D for max_, and PolyCollection for max_ shading)

See also

matplotlib.axes.Axes.plot()

for a full description of acceptable *args` and ``**kwargs

plot_variance(artist, *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:	MeshGrid : the MeshGridD for this layer

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

• DataQualityFlag
• Segment or glue.segments.segment
• SegmentList or glue.segments.segmentlist
• SegmentListDict or glue.segments.segmentlistdict

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

Attributes Summary

insetlabels	Move the y-axis tick labels inside the axes
name

Methods Summary

build_segment(segment, y[, height, valign])	Build a Rectangle to display
draw(artist, renderer, *args, **kwargs)	Draw everything (plot lines, axes, labels)
get_collections([ignore])	Return the collections matching the given _ignore value
get_insetlabels()	Move the y-axis tick labels inside the axes
get_next_y()	Find the next y-axis value at which a segment list can be placed
plot(*args, **kwargs)	Plot data onto these axes
plot_dqdict(artist, *args, **kwargs)	Plot a DataQualityDict onto these axes
plot_dqflag(artist, *args, **kwargs)	Plot a DataQualityFlag
plot_segmentlist(artist, *args, **kwargs)	Plot a SegmentList onto these axes
plot_segmentlistdict(artist, *args, **kwargs)	Plot a SegmentListDict onto
set_insetlabels([inset])
set_xlim(*args, **kwargs)	Call signature:

Attributes Documentation

insetlabels¶

Move the y-axis tick labels inside the axes

name = 'segments'¶

Methods Documentation

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(artist, renderer, *args, **kwargs)¶

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]¶

Move the y-axis tick labels inside the axes

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.

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

Plot data onto these axes

Parameters:	args : a single instance of DataQualityFlag Segment SegmentList SegmentListDict or equivalent types upstream from glue.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(artist, *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(artist, *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(artist, *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(artist, *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_xlim(*args, **kwargs)[source]¶

Call signature:

set_xlim(self, *args, **kwargs):

Set the data limits for the xaxis

Examples:

set_xlim((left, right))
set_xlim(left, right)
set_xlim(left=1) # right unchanged
set_xlim(right=1) # left unchanged

Keyword arguments:

left: scalar

The left xlim; xmin, the previous name, may still be used

right: scalar

The right xlim; xmax, the previous name, may still be used

emit: [ True | False ]

Notify observers of limit change

auto: [ True | False | None ]

Turn x autoscaling on (True), off (False; default), or leave unchanged (None)

Note, the left (formerly xmin) value may be greater than the right (formerly xmax). For example, suppose x is years before present. Then one might use:

set_ylim(5000, 0)

so 5000 years ago is on the left of the plot and the present is on the right.

Returns the current xlimits as a length 2 tuple

ACCEPTS: length 2 sequence of floats

class gwpy.plotter.EventTableAxes(fig, *args, **kwargs)[source]¶

Bases: gwpy.plotter.timeseries.TimeSeriesAxes

Custom Axes for an EventTablePlot.

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

Attributes Summary

name

Methods Summary

add_loudest(table, rank, x, y, *columns, ...)	Display the loudest event according to some rank.
plot(*args, **kwargs)	Plot data onto these axes
plot_table(table, x, y[, color, size_by, ...])	Plot a LIGO_LW-format event Table onto these Axes
plot_tiles(table, x, y, width, height[, ...])

Attributes Documentation

name = 'triggers'¶

Methods Documentation

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 : Table LIGO_LW-format XML 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 color : str, optional name of column by which to colour the data **kwargs : any other arguments applicable to text()
Returns:	out : tuple (collection, text) tuple of items added to the Axes

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

Plot data onto these axes

Parameters:	*args : a single Table (or sub-class) or anything valid for plot(). **kwargs : keyword arguments applicable to plot()

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

Plot a LIGO_LW-format event Table onto these Axes

Parameters:	table : Table LIGO_LW-format XML event 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 scatter()
Returns:	collection :

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