Plotting Module

The nereus.plotting module provides visualization tools for unstructured mesh data.

Map Plotting

2D map plotting for unstructured data.

This module provides functions for plotting unstructured geophysical data on various map projections.

nereus.plotting.maps.plot(data, lon=None, lat=None, *, projection='pc', extent=None, resolution=1.0, interpolator=None, method='nearest', influence_radius=80000.0, cmap='viridis', vmin=None, vmax=None, coastlines=True, land=False, gridlines=False, colorbar=True, colorbar_label=None, title=None, figsize=None, ax=None, use_cache=True, **kwargs)

Plot 2D map of unstructured data.

This function regrids unstructured data to a regular grid and plots it on a map with the specified projection.

The function accepts various input formats and automatically transforms them to 1D arrays for plotting:

• All 1D arrays of same size: used directly (no warning)

• 2D data with 2D lon/lat (same shape): all raveled to 1D

• 1D data with 2D lon/lat: lon/lat raveled to match data

• 2D data with 1D lon/lat: meshgrid created, then all raveled

A warning is issued whenever array transformations are applied.

If lon/lat are not provided and data is an xarray DataArray, the function will attempt to extract coordinates automatically by looking for common coordinate names (lon/lat, longitude/latitude, x/y, etc.).

Parameters:

• data (array_like) – Data values at unstructured points. Can be 1D or 2D array. If xarray DataArray, coordinates may be extracted automatically.

• lon (array_like, optional) – Longitude coordinates. Can be 1D or 2D array. If None, will attempt to extract from data (xarray only).

• lat (array_like, optional) – Latitude coordinates. Can be 1D or 2D array. If None, will attempt to extract from data (xarray only).

• projection (str or Projection) – Map projection. Options: “pc”, “rob”, “merc”, “npstere”, “spstere”, “moll”, “ortho”, “lcc”, or a Cartopy Projection.

• extent (tuple of float, optional) – Map extent (lon_min, lon_max, lat_min, lat_max).

• resolution (float or tuple of int) – Grid resolution for regridding.

• interpolator (RegridInterpolator, optional) – Pre-computed interpolator. If None, one will be created.

• method ({"nearest", "idw", "linear", "cubic"}) – Interpolation method. “nearest” uses nearest-neighbor lookup (fast). “idw” uses inverse distance weighting (fast, smooth). “linear” uses Delaunay triangulation with barycentric interpolation. “cubic” uses Clough-Tocher C1 interpolation (smoothest). Default is “nearest”.

• influence_radius (float) – Maximum influence radius in meters for interpolation. Default is 80 km.

• cmap (str) – Colormap name.

• vmin (float, optional) – Color scale limits.

• vmax (float, optional) – Color scale limits.

• coastlines (bool) – Whether to draw coastlines.

• land (bool) – Whether to fill land areas.

• gridlines (bool) – Whether to draw gridlines.

• colorbar (bool) – Whether to add a colorbar.

• colorbar_label (str, optional) – Label for the colorbar.

• title (str, optional) – Plot title.

• figsize (tuple of float, optional) – Figure size (width, height) in inches.

• ax (Axes, optional) – Existing axes to plot on. If None, creates new figure.

• use_cache (bool) – Whether to use the interpolator cache.

• **kwargs (Any) – Additional arguments passed to pcolormesh.

Returns:

• fig (Figure) – The matplotlib Figure.

• ax (Axes) – The matplotlib Axes (GeoAxes).

• interpolator (RegridInterpolator) – The interpolator used (can be reused).

Return type:

tuple[‘Figure’, ‘Axes’, RegridInterpolator]

Examples

>>> fig, ax, interp = nr.plot(temp, mesh.lon, mesh.lat)
>>> fig, ax, _ = nr.plot(salinity, mesh.lon, mesh.lat, interpolator=interp)

nereus.plotting.maps.plot(data, lon=None, lat=None, *, projection='pc', extent=None, resolution=1.0, interpolator=None, method='nearest', influence_radius=80000.0, cmap='viridis', vmin=None, vmax=None, coastlines=True, land=False, gridlines=False, colorbar=True, colorbar_label=None, title=None, figsize=None, ax=None, use_cache=True, **kwargs)

Plot 2D map of unstructured data.

This function regrids unstructured data to a regular grid and plots it on a map with the specified projection.

The function accepts various input formats and automatically transforms them to 1D arrays for plotting:

• All 1D arrays of same size: used directly (no warning)

• 2D data with 2D lon/lat (same shape): all raveled to 1D

• 1D data with 2D lon/lat: lon/lat raveled to match data

• 2D data with 1D lon/lat: meshgrid created, then all raveled

A warning is issued whenever array transformations are applied.

If lon/lat are not provided and data is an xarray DataArray, the function will attempt to extract coordinates automatically by looking for common coordinate names (lon/lat, longitude/latitude, x/y, etc.).

Parameters:

• data (array_like) – Data values at unstructured points. Can be 1D or 2D array. If xarray DataArray, coordinates may be extracted automatically.

• lon (array_like, optional) – Longitude coordinates. Can be 1D or 2D array. If None, will attempt to extract from data (xarray only).

• lat (array_like, optional) – Latitude coordinates. Can be 1D or 2D array. If None, will attempt to extract from data (xarray only).

• projection (str or Projection) – Map projection. Options: “pc”, “rob”, “merc”, “npstere”, “spstere”, “moll”, “ortho”, “lcc”, or a Cartopy Projection.

• extent (tuple of float, optional) – Map extent (lon_min, lon_max, lat_min, lat_max).

• resolution (float or tuple of int) – Grid resolution for regridding.

• interpolator (RegridInterpolator, optional) – Pre-computed interpolator. If None, one will be created.

• method ({"nearest", "idw", "linear", "cubic"}) – Interpolation method. “nearest” uses nearest-neighbor lookup (fast). “idw” uses inverse distance weighting (fast, smooth). “linear” uses Delaunay triangulation with barycentric interpolation. “cubic” uses Clough-Tocher C1 interpolation (smoothest). Default is “nearest”.

• influence_radius (float) – Maximum influence radius in meters for interpolation. Default is 80 km.

• cmap (str) – Colormap name.

• vmin (float, optional) – Color scale limits.

• vmax (float, optional) – Color scale limits.

• coastlines (bool) – Whether to draw coastlines.

• land (bool) – Whether to fill land areas.

• gridlines (bool) – Whether to draw gridlines.

• colorbar (bool) – Whether to add a colorbar.

• colorbar_label (str, optional) – Label for the colorbar.

• title (str, optional) – Plot title.

• figsize (tuple of float, optional) – Figure size (width, height) in inches.

• ax (Axes, optional) – Existing axes to plot on. If None, creates new figure.

• use_cache (bool) – Whether to use the interpolator cache.

• **kwargs (Any) – Additional arguments passed to pcolormesh.

Returns:

• fig (Figure) – The matplotlib Figure.

• ax (Axes) – The matplotlib Axes (GeoAxes).

• interpolator (RegridInterpolator) – The interpolator used (can be reused).

Return type:

tuple[‘Figure’, ‘Axes’, RegridInterpolator]

Examples

>>> fig, ax, interp = nr.plot(temp, mesh.lon, mesh.lat)
>>> fig, ax, _ = nr.plot(salinity, mesh.lon, mesh.lat, interpolator=interp)

Projections

Projection utilities for nereus plotting.

This module provides convenient aliases and configuration for Cartopy projections.

nereus.plotting.projections.get_projection(name, **kwargs)

Get a Cartopy projection from name or alias.

Parameters:

• name (str or Projection) – Projection name/alias or an existing Cartopy Projection.

• **kwargs (Any) – Additional keyword arguments passed to the projection constructor.

Returns:

A Cartopy projection instance.

Return type:

Projection

Raises:

ValueError – If the projection name is not recognized.

Examples

>>> proj = get_projection("pc")
>>> proj = get_projection("npstere")
>>> proj = get_projection("ortho", central_longitude=10, central_latitude=50)

nereus.plotting.projections.is_global_projection(name)

Check if a projection should use set_global().

Parameters:

name (str or Projection) – Projection name/alias or Cartopy Projection.

Returns:

True if the projection is global.

Return type:

bool

nereus.plotting.projections.is_polar_projection(name)

Check if a projection is polar.

Parameters:

name (str or Projection) – Projection name/alias or Cartopy Projection.

Returns:

“north” for north polar, “south” for south polar, None otherwise.

Return type:

str or None

nereus.plotting.projections.get_data_bounds_for_projection(projection, extent=None)

Get appropriate data bounds for a projection.

For polar projections, expands the bounds to fill the circular plot area.

Parameters:

• projection (str or Projection) – The projection being used.

• extent (tuple of float, optional) – Desired extent (lon_min, lon_max, lat_min, lat_max).

Returns:

lon_bounds, lat_bounds – Longitude and latitude bounds for data fetching.

Return type:

tuple of tuples

Supported Projections

Alias(es)	Projection Class	Description
"pc", "platecarree"	ccrs.PlateCarree	Equirectangular projection
"rob", "robinson"	ccrs.Robinson	Robinson projection (global)
"merc", "mercator"	ccrs.Mercator	Mercator projection
"moll", "mollweide"	ccrs.Mollweide	Mollweide projection (global, equal-area)
"np", "npstere", "northpolarstereo"	ccrs.NorthPolarStereo	North Polar Stereographic
"sp", "spstere", "southpolarstereo"	ccrs.SouthPolarStereo	South Polar Stereographic
"ortho", "orthographic"	ccrs.Orthographic	Orthographic projection
"lcc", "lambertconformal"	ccrs.LambertConformal	Lambert Conformal Conic

Functions

nereus.plotting.projections.get_projection(name, **kwargs)

Get a Cartopy projection from name or alias.

Parameters:

• name (str or Projection) – Projection name/alias or an existing Cartopy Projection.

• **kwargs (Any) – Additional keyword arguments passed to the projection constructor.

Returns:

A Cartopy projection instance.

Return type:

Projection

Raises:

ValueError – If the projection name is not recognized.

Examples

>>> proj = get_projection("pc")
>>> proj = get_projection("npstere")
>>> proj = get_projection("ortho", central_longitude=10, central_latitude=50)

nereus.plotting.projections.is_global_projection(name)

Check if a projection should use set_global().

Parameters:

name (str or Projection) – Projection name/alias or Cartopy Projection.

Returns:

True if the projection is global.

Return type:

bool

nereus.plotting.projections.is_polar_projection(name)

Check if a projection is polar.

Parameters:

name (str or Projection) – Projection name/alias or Cartopy Projection.

Returns:

“north” for north polar, “south” for south polar, None otherwise.

Return type:

str or None

nereus.plotting.projections.get_data_bounds_for_projection(projection, extent=None)

Get appropriate data bounds for a projection.

For polar projections, expands the bounds to fill the circular plot area.

Parameters:

• projection (str or Projection) – The projection being used.

• extent (tuple of float, optional) – Desired extent (lon_min, lon_max, lat_min, lat_max).

Returns:

lon_bounds, lat_bounds – Longitude and latitude bounds for data fetching.

Return type:

tuple of tuples

Constants

nereus.plotting.projections.PROJECTION_ALIASES

Dictionary mapping projection aliases to their configurations.

Example structure:

{
    "pc": {"class": "PlateCarree", "global": False},
    "rob": {"class": "Robinson", "global": True},
    "np": {"class": "NorthPolarStereo", "global": False, "polar": "north"},
    ...
}

Transect Plotting

Vertical transect plotting for nereus.

This module provides functions for plotting vertical transects (cross-sections) of 3D data along arbitrary paths.

nereus.plotting.transect.transect(data, lon=None, lat=None, depth=None, start=None, end=None, *, n_points=100, cmap='viridis', vmin=None, vmax=None, depth_lim=None, invert_depth=True, colorbar=True, colorbar_label=None, title=None, figsize=None, ax=None, **kwargs)

Plot vertical transect along a great circle path.

The function accepts various coordinate formats and automatically transforms them to 1D arrays:

• Both 1D with same size: used directly (no warning)

• Both 2D with same shape: raveled to 1D

• Both 1D with different sizes: meshgrid created, then raveled

A warning is issued whenever coordinate transformations are applied.

If lon/lat are not provided and data is an xarray DataArray, the function will attempt to extract coordinates automatically by looking for common coordinate names (lon/lat, longitude/latitude, x/y, etc.).

Parameters:

• data (array_like) – Data values with shape (nlevels, npoints) for 2D, or (nlevels, nlat, nlon) for 3D regular grids. 3D data is automatically reshaped to 2D. If xarray DataArray, coordinates may be extracted automatically.

• lon (array_like, optional) – Longitude coordinates. Can be 1D or 2D array. If None, will attempt to extract from data (xarray only).

• lat (array_like, optional) – Latitude coordinates. Can be 1D or 2D array. If None, will attempt to extract from data (xarray only).

• depth (array_like) – 1D array of depth levels (positive downward).

• start (tuple of float) – Start point (lon, lat).

• end (tuple of float) – End point (lon, lat).

• n_points (int) – Number of points along the transect.

• cmap (str) – Colormap name.

• vmin (float, optional) – Color scale limits.

• vmax (float, optional) – Color scale limits.

• depth_lim (tuple of float, optional) – Depth/height limits (min, max). If None, uses data range.

• invert_depth (bool) – Whether to invert vertical axis. Default True for ocean (0 at top, depth increases downward). Set False for atmosphere (height increases upward).

• colorbar (bool) – Whether to add a colorbar.

• colorbar_label (str, optional) – Label for the colorbar.

• title (str, optional) – Plot title.

• figsize (tuple of float, optional) – Figure size.

• ax (Axes, optional) – Existing axes to plot on.

• **kwargs (Any) – Additional arguments passed to pcolormesh.

Returns:

• fig (Figure) – The matplotlib Figure.

• ax (Axes) – The matplotlib Axes.

Return type:

tuple[‘Figure’, ‘Axes’]

Examples

>>> fig, ax = nr.transect(
...     temp, mesh.lon, mesh.lat, depth,
...     start=(-30, 60), end=(30, 60)
... )

nereus.plotting.transect.transect(data, lon=None, lat=None, depth=None, start=None, end=None, *, n_points=100, cmap='viridis', vmin=None, vmax=None, depth_lim=None, invert_depth=True, colorbar=True, colorbar_label=None, title=None, figsize=None, ax=None, **kwargs)

Plot vertical transect along a great circle path.

The function accepts various coordinate formats and automatically transforms them to 1D arrays:

• Both 1D with same size: used directly (no warning)

• Both 2D with same shape: raveled to 1D

• Both 1D with different sizes: meshgrid created, then raveled

A warning is issued whenever coordinate transformations are applied.

If lon/lat are not provided and data is an xarray DataArray, the function will attempt to extract coordinates automatically by looking for common coordinate names (lon/lat, longitude/latitude, x/y, etc.).

Parameters:

• data (array_like) – Data values with shape (nlevels, npoints) for 2D, or (nlevels, nlat, nlon) for 3D regular grids. 3D data is automatically reshaped to 2D. If xarray DataArray, coordinates may be extracted automatically.

• lon (array_like, optional) – Longitude coordinates. Can be 1D or 2D array. If None, will attempt to extract from data (xarray only).

• lat (array_like, optional) – Latitude coordinates. Can be 1D or 2D array. If None, will attempt to extract from data (xarray only).

• depth (array_like) – 1D array of depth levels (positive downward).

• start (tuple of float) – Start point (lon, lat).

• end (tuple of float) – End point (lon, lat).

• n_points (int) – Number of points along the transect.

• cmap (str) – Colormap name.

• vmin (float, optional) – Color scale limits.

• vmax (float, optional) – Color scale limits.

• depth_lim (tuple of float, optional) – Depth/height limits (min, max). If None, uses data range.

• invert_depth (bool) – Whether to invert vertical axis. Default True for ocean (0 at top, depth increases downward). Set False for atmosphere (height increases upward).

• colorbar (bool) – Whether to add a colorbar.

• colorbar_label (str, optional) – Label for the colorbar.

• title (str, optional) – Plot title.

• figsize (tuple of float, optional) – Figure size.

• ax (Axes, optional) – Existing axes to plot on.

• **kwargs (Any) – Additional arguments passed to pcolormesh.

Returns:

• fig (Figure) – The matplotlib Figure.

• ax (Axes) – The matplotlib Axes.

Return type:

tuple[‘Figure’, ‘Axes’]

Examples

>>> fig, ax = nr.transect(
...     temp, mesh.lon, mesh.lat, depth,
...     start=(-30, 60), end=(30, 60)
... )