Last updated on Feb 20, 2026.

netsse.tools.viz#

Data visualisation functions for NetSSE.

Last updated on 09-02-2026 by R.E.G. Mounet

Functions#

`plot_bathymetry`(depths, shp_dict, ax[, cmap])	Plots the bathymetry map for a given area.
`plot_dirwavespec`(spec, dirs, freqs[, unit_dirs, ...])	Plots the input directional wave spectrum in a polar diagram.
`plot_sea_state_scatter`(y_data, x_data[, y_bin, x_bin, ...])	Create a sea state scatter diagram (2-D histogram heatmap) of counts for two wave parameters.

Module Contents#

netsse.tools.viz.plot_bathymetry(depths, shp_dict, ax, cmap='Blues_r')[source]#

Plots the bathymetry map for a given area.

The function plots the bathymetry map for a given area using the shapefiles contained in the dictionary shp_dict. The shapefiles are sorted by depth, from the surface to the bottom.

Parameters:

depths (list) – List of the depths in the shapefiles for the specified area.
shp_dict (dict) – Dictionary containing the shapefiles.
ax (matplotlib.axes) – Axes object to plot on.
cmap (str, optional) –
Colormap to use for the plot. Default is 'Blues_r'.

Note

Other colormap options include 'plasma', 'inferno', 'magma', 'viridis'. Visit the Matplotlib documentation for an overview of the options.

Returns:

ax (matplotlib.axes._subplots.AxesSubplot) – The axes object with the plot.
colormap (matplotlib.colors.ListedColormap) – The colormap used for the plot.

See also

netsse.model.bathymetry.load_bathymetry: Retrieve and read bathymetry shapefiles.

Example

import matplotlib.pyplot as plt
import cartopy.crs as ccrs
import cartopy.feature as cfeature
from netsse.model.bathymetry import load_bathymetry
from netsse.tools.viz import plot_bathymetry

depths, shp_dict = load_bathymetry(lonmin=-5, lonmax=15, latmin=35, latmax=45)
fig, ax = plt.subplots(subplot_kw={'projection':ccrs.Mercator(central_longitude=5,min_latitude=35,max_latitude=45)},figsize=(6,6))
ax.set_extent([-5, 15, 35, 45], crs=ccrs.PlateCarree())
ax, colormap = plot_bathymetry(depths, shp_dict, ax)
ax.add_feature(cfeature.LAND,edgecolor='black',facecolor='gainsboro',alpha=0.5)

netsse.tools.viz.plot_dirwavespec(spec, dirs, freqs, unit_dirs='deg', unit_freqs='Hz', levels=None, cmap='turbo', vmin=None, vmax=None, freq_max=None, show_dirlabels=True, show_freqlabels=True, rscale='linear', ax=None)[source]#

Plots the input directional wave spectrum in a polar diagram.

The plot shows the power spectral density (PSD) distribution over wave frequencies and directions.

Parameters:

spec (array_like) – Directional wave spectrum to be plotted. This must be a 2-D array of shape either (Ndirs,Nfreqs) or (Nfreqs,Ndirs).
dirs (array_like of shape (Ndirs,)) – Directions of the spectrum.
freqs (array_like of shape (Nfreqs,)) – Frequencies of the spectrum.
unit_dirs ({'deg','rad'}, optional) – Unit of the directions, either 'deg' for degrees or 'rad' for radians. Default is 'deg'.
unit_freqs ({'Hz','rad/s'}, optional) – Unit of the frequencies, either 'Hz' for Hertz or 'rad/s' for radians per second. Default is 'Hz'.
levels (array_like, optional) –
Contour levels to use for the plot. If None, levels are automatically determined according to the formula below:

\(vmin*(vmax/vmin)^{i/29}\) for \(i=0,1,...,29\). Default is None.
cmap (str, optional) –
Colormap to use for the plot. Default is 'turbo'.

Note

Other colormap options include 'viridis', 'plasma', 'inferno', 'magma'. Visit the Matplotlib documentation for an overview of the options.
vmin (float, optional) – Minimum value for the colormap. Default is None, which means to use the value \(10^{-1/2}\).
vmax (float, optional) –
Maximum value for the colormap. Default is None, which means to use the maximum value in spec.

Warning

vmin and vmax are used to set the colormap limits. These options will override the lower and upper limits of levels, if the latter option is used.
freq_max (float, optional) – Maximum frequency to plot. Default is None, which means to use the maximum frequency in the input data.
show_dirlabels ({True,False,'compass'}, optional) – Whether to show direction labels. If True, shows labels in degrees. If 'compass', shows compass directions. If False, no labels are shown. Default is True.
show_freqlabels ({True,False,'all'}, optional) – Whether to show frequency labels. If True, shows only the maximum frequency label. If 'all', shows all labels. If False, no labels are shown. Default is True.
rscale ({'linear', 'log'}, optional) – Scale for the radial axis (frequencies). Default is 'linear'.
ax (matplotlib.axes, optional) – Axes object to plot on. If None, a new figure and axes are created. Default is None.

Returns:

ax – The axes object with the plot.

Return type:

matplotlib.axes._subplots.PolarAxesSubplot

Example

>>> # Generate some example data
>>> freqs = np.linspace(0.05, 0.5, 50)
>>> dirs = np.linspace(0, 360, 36)
>>> spec = np.random.rand(36, 50)
>>> # Plot the directional wave spectrum
>>> plot_dirwavespec(spec, dirs, freqs)

netsse.tools.viz.plot_sea_state_scatter(y_data, x_data, y_bin=0.25, x_bin=0.2, y_range=None, x_range=None, y_label=None, x_label=None, cmap='viridis', norm='log', annotate=True, min_count_annot=1, ax=None, colorbar=True, grid=True)[source]#

Create a sea state scatter diagram (2-D histogram heatmap) of counts for two wave parameters.

Parameters:

y_data (array-like) – Values to be displayed on the vertical axis. Typically, this some wave height parameter [in metres].
x_data (array-like) – Values to be displayed on the horizontal axis. Typically, this is some wave period parameter [in seconds]. Must be same length as y_data.
y_bin (float, optional) – Bin size for y_data. Default is 0.25 [m].
x_bin (float, optional) – Bin size for x_data. Default is 0.20 [s].
y_range (tuple(float, float), optional) – (min, max) explicit range for y_data. If None, inferred from data.
x_range (tuple(float, float), optional) – (min, max) explicit range for x_data. If None, inferred from data.
y_label (str, optional.) – Y-axis label for scatter diagram. If None, the scatter diagram display a y-axis label.
x_label (str, optional.) – X-axis label for scatter diagram. If None, the scatter diagram display an x-axis label.
cmap (str, optional) – Matplotlib colormap name.
norm ({"log", "linear"}, optional) – Color normalization. "log" helps when counts vary widely.
annotate (bool, optional) – If True, annotate counts inside cells.
min_count_annot (int, optional) – Minimum count to annotate a cell (avoids clutter).
ax (matplotlib.axes.Axes, optional) – Axes to draw on. If None, a new figure and axes are created.
colorbar (bool, optional) – If True, add a colorbar.
grid (bool, optional) – If True, show grid lines.

Returns:

fig (matplotlib.figure.Figure)
ax (matplotlib.axes.Axes)
H (2-D ndarray) – Counts matrix of shape (len(y_edges)-1, len(x_edges)-1), where rows correspond to y_data bins and columns to x_data bins.
y_edges (1-D ndarray) – Bin edges for x_data.
x_edges (1-D ndarray) – Bin edges for y_data.

Notes

NaNs and non-finite values are ignored.

Example

>>> fig, ax, counts, hs_edges, tp_edges = plot_sea_state_scatter(
...    Hs, Tp,
...    y_bin=0.25,
...    x_bin=0.20,
...    norm="log",           # try "linear" if you prefer
...    annotate=False,       # set True to print counts in cells
... )

netsse.tools.viz#

Functions#

Module Contents#

This Page