Development documentation · 0.2.3 30c2f8ba · Intro examples tested with 0.2.3 · Version details · Known limitations

Plotting#

Matplotlib-based plotting extensions including GPS-aware axes, Bode plots, colorbars, and segment visualization.

Plotting helpers.

Note: This module intentionally avoids importing optional/heavy dependencies (e.g. ligo.skymap) at import time because Sphinx autodoc imports gwexpy.

class gwexpy.plot.Plot(*args, **kwargs)#

Bases: Plot

GWexpy-aware plotting facade for series, matrices, and spectrogram grids.

Plot keeps the familiar gwpy.plot.Plot constructor while adding conveniences needed by GWexpy collections:

  • SeriesMatrix and SpectrogramMatrix inputs are expanded into per-axis subplots automatically.

  • Layout hints such as separate, geometry, and shared-axis labeling are inferred from the input shape.

  • Spectrogram plots can receive automatic colorbar management and adaptive decimation for large overlays.

Parameters:

  • *args – Series-like objects, matrices, lists, or dictionaries accepted by the GWexpy plotting registry.

  • **kwargs – Standard gwpy.plot.Plot keyword arguments plus GWexpy-specific layout helpers such as separate, geometry, monitor, decimate_threshold, and decimate_points.

Examples

Plot a matrix as aligned subplots:

>>> from gwexpy.plot import Plot
>>> fig = Plot(ts_matrix, separate=True, figsize=(10, 6))
>>> len(fig.axes) >= 1
True

Overlay summary curves with a shaded min/max envelope:

>>> fig = Plot(median_series)
>>> _ = fig.plot_mmm(median_series, min_series, max_series, alpha_fill=0.15)

See also

plot_mmm

Convenience helper for median/min/max overlays.

gwexpy.types.SeriesMatrix

Matrix container expanded automatically by this plot class.

plot_mmm(median, min_s, max_s, ax=None, **kwargs)#

Plot median line with a min/max envelope.

This is a convenience wrapper around gwexpy.plot.plot_mmm().

Parameters:

  • median (gwpy.types.Series) – Median series to plot as a line.

  • min_s (gwpy.types.Series) – Minimum series defining the lower envelope.

  • max_s (gwpy.types.Series) – Maximum series defining the upper envelope.

  • ax (matplotlib.axes.Axes, optional) – Target axes. If omitted, uses the current axes of this Plot.

  • **kwargs –

    Passed to ax.plot for the median line. Additional keys supported:

    • alpha_fill: opacity for the filled envelope

    • label_fill: label for the filled envelope

Returns:

The list of Line2D objects returned by ax.plot.

Return type:

list

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, canvas=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, constrained_layout=<UNSET>, constrained_layout_pads=<UNSET>, dpi=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, figheight=<UNSET>, figwidth=<UNSET>, frameon=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, layout_engine=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, size_inches=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, tight_layout=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)#

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Properties:

agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: float or None animated: bool canvas: FigureCanvas clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None constrained_layout: unknown constrained_layout_pads: unknown dpi: float edgecolor: color facecolor: color figheight: float figure: unknown figwidth: float frameon: bool gid: str in_layout: bool label: object layout_engine: {‘constrained’, ‘compressed’, ‘tight’, ‘none’, .LayoutEngine, None} linewidth: number mouseover: bool path_effects: list of .AbstractPathEffect picker: None or bool or float or callable rasterized: bool size_inches: (float, float) or float sketch_params: (scale: float, length: float, randomness: float) snap: bool or None tight_layout: unknown transform: ~matplotlib.transforms.Transform url: str visible: bool zorder: float

show(warn: bool = True, block: bool | None = None, *, close: bool = False) → None#

Show the figure with GWpy-compatible positional arguments.

Parameters:

  • warn (bool, optional) – Unused, kept for API compatibility. Default is True.

  • block (bool or None, optional) – Whether to block execution until the figure window is closed. If None (default), uses matplotlib’s default behavior. Set to False to continue execution immediately after showing, which allows savefig() to work in scripted workflows.

  • close (bool, keyword-only, optional) – Explicit GWexpy extension. If True, close the figure after the GWpy display path returns. The default is False so that plain show() has the same lifecycle as GWpy.

Examples

>>> plot = Plot(data)
>>> plot.show(block=False)  # Non-blocking, keep figure
>>> plot.savefig("output.png")  # Works because figure is still open

Notes

warn and block retain GWpy’s positional layout. Use the keyword-only close=True extension in notebooks when explicitly closing after display is desired.

gwexpy.plot.plot_mmm(median, min_s, max_s, ax=None, **kwargs)#

Plot Median, Min, and Max series with a filled area between Min and Max.

Parameters:

  • median (Series) – Median series to plot as the central line.

  • min_s (Series) – Lower envelope series.

  • max_s (Series) – Upper envelope series.

  • ax (Axes, optional) – Target axes. Uses the current axes when omitted.

  • **kwargs – Passed to ax.plot for the median line.

class gwexpy.plot.SkyMap(*args, **kwargs)#

Bases: Plot

A Plot subclass for all‑sky maps.

This class provides convenient methods to display HEALPix probability maps (using ligo.skymap) and to overlay astronomical targets.

add_healpix(map_data, **kwargs)#

Add a HEALPix probability map to the sky plot.

Parameters:

  • map_data (array‑like) – HEALPix map data (e.g., a numpy array of probabilities).

  • **kwargs – Additional keyword arguments passed to imshow_hpx.

add_heatmap(ra, dec, values, **kwargs)#

Overlay a heatmap defined on sky coordinates.

Parameters:

  • ra (array‑like (degrees)) – Grid of right‑ascension and declination values.

  • dec (array‑like (degrees)) – Grid of right‑ascension and declination values.

  • values (2‑D array) – Data values corresponding to each (ra, dec) point.

  • **kwargs – Additional keyword arguments passed to pcolormesh.

mark_target(ra, dec, label=None, **kwargs)#

Mark a sky position on the map.

Parameters:

  • ra (array‑like or Quantity) – Right‑ascension and declination. If plain numbers are supplied they are interpreted as degrees.

  • dec (array‑like or Quantity) – Right‑ascension and declination. If plain numbers are supplied they are interpreted as degrees.

  • label (str, optional) – Text label to place next to the marker.

  • **kwargs (additional arguments passed to the underlying Matplotlib scatter) – or plot_coord call.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, canvas=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, constrained_layout=<UNSET>, constrained_layout_pads=<UNSET>, dpi=<UNSET>, edgecolor=<UNSET>, facecolor=<UNSET>, figheight=<UNSET>, figwidth=<UNSET>, frameon=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, layout_engine=<UNSET>, linewidth=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, size_inches=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, tight_layout=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)#

Set multiple properties at once.

a.set(a=A, b=B, c=C)

is equivalent to

a.set_a(A)
a.set_b(B)
a.set_c(C)

In addition to the full property names, aliases are also supported, e.g. set(lw=2) is equivalent to set(linewidth=2), but it is an error to pass both simultaneously.

The order of the individual setter calls matches the order of parameters in set(). However, most properties do not depend on each other so that order is rarely relevant.

Supported properties are

Properties:

agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: float or None animated: bool canvas: FigureCanvas clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None constrained_layout: unknown constrained_layout_pads: unknown dpi: float edgecolor: color facecolor: color figheight: float figure: unknown figwidth: float frameon: bool gid: str in_layout: bool label: object layout_engine: {‘constrained’, ‘compressed’, ‘tight’, ‘none’, .LayoutEngine, None} linewidth: number mouseover: bool path_effects: list of .AbstractPathEffect picker: None or bool or float or callable rasterized: bool size_inches: (float, float) or float sketch_params: (scale: float, length: float, randomness: float) snap: bool or None tight_layout: unknown transform: ~matplotlib.transforms.Transform url: str visible: bool zorder: float

class gwexpy.plot.GeoMap(projection='Robinson', center_lon=0, width='15c', **kwargs)#

Bases: object

A PyGMT wrapper that provides a Cartopy-like interface.

add_coastlines(resolution='low', color='black', linewidth=0.5)#

Draw coastlines (Cartopy-like API).

add_scale_bar(width='500k', position='jBL', offset='0.5c/0.5c', fancy=True)#

Add a scale bar to the map.

Parameters:

  • width (str, optional) – Width of the scale bar (e.g., ‘500k’ for 500 km, ‘100k’ for 100 km).

  • position (str, optional) – Position anchor (e.g., ‘jBL’ for Bottom Left).

  • offset (str, optional) – Offset from the anchor (e.g., ‘0.5c/0.5c’).

  • fancy (bool, optional) – If True, use a fancy scale bar.

fill_continents(color='lightgray')#

Fill land colors.

fill_oceans(color='azure')#

Fill water colors.

plot(x, y, color='blue', marker='o', markersize=10, label=None, **kwargs)#

Plot points (Matplotlib-like API).

plot_detector(name, label=True, label_offset=None, **kwargs)#

Plot a gravitational wave detector by name (e.g., ‘K1’).

Parameters:

  • name (str) – Name of the detector.

  • label (bool, optional) – If True, plot a label above the marker.

  • label_offset (float, optional) – Manual latitude offset for the label. If None, it’s calculated dynamically.

  • **kwargs – Additional arguments for GeoMap.plot (e.g., color, markersize).

save(filename, **kwargs)#

Save the plot.

show()#

Display the plot.

text(x, y, text, **kwargs)#

Add text at (x, y).

class gwexpy.plot.PairPlot(data: Any, *, corner: bool = True, diag: str = 'hist', offdiag: str = 'hist2d', bins: int = 50, figsize: tuple | None = None, **kwargs)#

Bases: object

Pair plot for Series collections.

Visualizes pairwise relationships between series in a collection.

Parameters:

  • data (list, tuple, dict, TimeSeriesDict, TimeSeriesList, etc.) – Collection of series to plot.

  • corner (bool, default True) – If True, show only lower triangle.

  • diag (str, default 'hist') – Diagonal plot type: ‘hist’, ‘kde’.

  • offdiag (str, default 'hist2d') – Off-diagonal plot type: ‘hist2d’, ‘scatter’.

  • bins (int, default 50) – Number of bins for histograms.

  • figsize (tuple, optional) – Figure size. Auto-calculated if None.

  • **kwargs – Additional arguments.

Examples

>>> from gwexpy.plot import PairPlot
>>> plot = PairPlot(timeseries_dict)
>>> plot.show()
property axes: ndarray#

Return the axes array.

property figure: Figure#

Return the matplotlib Figure.

savefig(*args, **kwargs)#

Save the figure.

show()#

Show the plot.