Plotting

Stability: Stable

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)[source]

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)[source]

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

show(warn: bool = True, close: bool = True, block: bool | None = None) → None[source]

Show the figure.

Parameters:

warn (bool, optional) – Unused, kept for API compatibility. Default is True.
close (bool, optional) – If True (default), close the figure after showing to free resources and prevent double display in Jupyter. Set to False if you need to call savefig() after show().
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.

Examples

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

Notes

In Jupyter notebooks, setting close=True prevents the figure from being displayed twice (once by show() and once by the notebook’s automatic display).

In script mode, plt.show() blocks by default until the window is closed. Use block=False if you need to save after showing.

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.

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

gwexpy.plot.plot_mmm(median, min_s, max_s, ax=None, **kwargs)[source]

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)[source]

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)[source]

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.

mark_target(ra, dec, label=None, **kwargs)[source]

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.

add_heatmap(ra, dec, values, **kwargs)[source]

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.

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.

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)[source]

Bases: object

A PyGMT wrapper that provides a Cartopy-like interface.

add_coastlines(resolution='low', color='black', linewidth=0.5)[source]: Draw coastlines (Cartopy-like API).

fill_continents(color='lightgray')[source]: Fill land colors.

fill_oceans(color='azure')[source]: Fill water colors.

plot(x, y, color='blue', marker='o', markersize=10, label=None, **kwargs)[source]: Plot points (Matplotlib-like API).

text(x, y, text, **kwargs)[source]: Add text at (x, y).

plot_detector(name, label=True, label_offset=None, **kwargs)[source]

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

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

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.

show()[source]: Display the plot.

save(filename, **kwargs)[source]: Save the plot.

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

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 figure: Figure: Return the matplotlib Figure.

property axes: ndarray: Return the axes array.

show()[source]: Show the plot.

savefig(*args, **kwargs)[source]: Save the figure.