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.

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

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(artist, *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(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 the newly added image

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 : Legend the new legend

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

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 axisbelow: [ True | False | ‘line’ ] clip_box: a matplotlib.transforms.Bbox instance clip_on: [True | False] clip_path: [ (Path, Transform) | Patch | None ] color_cycle: unknown contains: a callable function facecolor: unknown fc: unknown 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: unknown xmargin: unknown xscale: [u’linear’ | u’log’ | u’logit’ | u’symlog’] xticklabels: sequence of strings xticks: sequence of floats ybound: unknown ylabel: unknown ylim: unknown 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 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.

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(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

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(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

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(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>

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

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

Set the x-axis scale

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

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

Set the y-axis scale

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.

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()

epoch¶

The GPS epoch of this plot

get_epoch()[source]¶

Return the GPS epoch of this plot

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

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, axisbg=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(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().

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

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

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.

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

Bases: gwpy.plotter.series.SeriesAxes

Custom Axes for a FrequencySeriesPlot.

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

• 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

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

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 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 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 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 ~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