fesomp.plotting

Plotting and visualization for unstructured data.

fesomp.plotting.plot(data, lon, lat, *, box=None, res=(360, 180), interp='nn', influence=80000, interpolator=None, cmap=None, levels=None, ptype='cf', mapproj='pc', figsize=(10, 6), rowscol=(1, 1), titles=None, units=None, colorbar=True, coastlines=True, land=False, gridlines=False, ax=None, fig=None)[source]

Plot unstructured data on a map.

Data is interpolated to a regular grid and plotted with cartopy.

Parameters:

  • data (np.ndarray or list of np.ndarray) – Data to plot. Can be a single array (npoints,) or a list of arrays for multiple subplots.

  • lon (np.ndarray) – Longitudes of data points in degrees.

  • lat (np.ndarray) – Latitudes of data points in degrees.

  • box (tuple, optional) – Bounding box (lon_min, lon_max, lat_min, lat_max). Default depends on projection: - ‘np’: (-180, 180, 60, 90) - ‘sp’: (-180, 180, -90, -60) - others: (-180, 180, -90, 90)

  • res (tuple) – Interpolation resolution (nlon, nlat). Default is (360, 180).

  • interp (str) – Interpolation method: ‘nn’ (nearest neighbor), ‘idw’, or ‘linear’.

  • influence (float) – Radius of influence for interpolation in meters. Default is 80000.

  • interpolator (RegridInterpolator, optional) – Pre-computed interpolator for caching. Speeds up repeated plots.

  • cmap (str, optional) – Colormap name. Default is ‘RdBu_r’.

  • levels (tuple or list, optional) – Contour levels. Can be (min, max, nlevels) or explicit list. Default is auto from data.

  • ptype (str) – Plot type: ‘cf’ (contourf) or ‘pcm’ (pcolormesh).

  • mapproj (str) – Map projection: ‘pc’ (Plate Carree), ‘rob’ (Robinson), ‘merc’ (Mercator), ‘np’ (North Polar), ‘sp’ (South Polar).

  • figsize (tuple) – Figure size in inches.

  • rowscol (tuple) – Subplot layout (nrows, ncols).

  • titles (str or list) – Title(s) for subplot(s).

  • units (str, optional) – Units label for colorbar.

  • colorbar (bool) – Whether to show colorbar. Default is True.

  • coastlines (bool) – Whether to draw coastlines. Default is True.

  • land (bool) – Whether to fill land areas. Default is False.

  • gridlines (bool) – Whether to draw gridlines. Default is False.

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

  • fig (matplotlib.figure.Figure, optional) – Existing figure to use.

Return type:

tuple[Figure, ndarray, RegridInterpolator]

Returns:

  • fig (matplotlib.figure.Figure) – The figure object.

  • axes (np.ndarray) – Array of axes objects.

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

Example

>>> # Simple plot
>>> fig, axes, interp = fesomp.plot(temp, mesh.lon, mesh.lat)
>>>
>>> # Multiple subplots with cached interpolator
>>> fig, axes, interp = fesomp.plot(
...     [temp_surface, temp_100m, temp_500m],
...     mesh.lon, mesh.lat,
...     rowscol=(1, 3),
...     titles=['Surface', '100m', '500m'],
...     interpolator=interp,  # reuse from previous
... )
fesomp.plotting.regrid(data, lon, lat, box=(-180, 180, -90, 90), res=(360, 180), method='nn', influence=80000, fill_value=nan, interpolator=None)[source]

Interpolate unstructured data to a regular grid.

Parameters:

  • data (np.ndarray) – Data values at unstructured points, shape (npoints,).

  • lon (np.ndarray) – Longitudes of data points in degrees, shape (npoints,).

  • lat (np.ndarray) – Latitudes of data points in degrees, shape (npoints,).

  • box (tuple) – Bounding box as (lon_min, lon_max, lat_min, lat_max). Default is global (-180, 180, -90, 90).

  • res (tuple) – Output resolution as (nlon, nlat). Default is (360, 180).

  • method (str) – Interpolation method: - ‘nn’: Nearest neighbor (fast, default) - ‘idw’: Inverse distance weighting - ‘linear’: Linear interpolation (scipy griddata)

  • influence (float) – Radius of influence in meters. Points outside this radius from any source point will be set to fill_value. Default is 80000 (80 km).

  • fill_value (float) – Value for grid points with no data. Default is NaN.

  • interpolator (RegridInterpolator, optional) – Pre-computed interpolator for caching. If provided, lon, lat, box, res, method, and influence are ignored.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

  • data_reg (np.ndarray) – Interpolated data on regular grid, shape (nlat, nlon).

  • lon_reg (np.ndarray) – 1D array of output longitudes.

  • lat_reg (np.ndarray) – 1D array of output latitudes.

Example

>>> # Simple one-off interpolation
>>> data_reg, lon_reg, lat_reg = regrid(temp, mesh.lon, mesh.lat)
>>>
>>> # With caching for multiple variables
>>> interp = RegridInterpolator(mesh.lon, mesh.lat)
>>> temp_reg, lon_reg, lat_reg = regrid(temp, mesh.lon, mesh.lat, interpolator=interp)
>>> salt_reg, _, _ = regrid(salt, mesh.lon, mesh.lat, interpolator=interp)
class fesomp.plotting.RegridInterpolator[source]

Bases: object

Cached interpolator for regridding unstructured data.

This class pre-computes and caches the KDTree and interpolation indices/weights, allowing fast repeated interpolation of different variables on the same grid.

Parameters:

  • lon (np.ndarray) – Longitudes of source points in degrees.

  • lat (np.ndarray) – Latitudes of source points in degrees.

  • box (tuple) – Target bounding box as (lon_min, lon_max, lat_min, lat_max).

  • res (tuple) – Target resolution as (nlon, nlat).

  • method (str) – Interpolation method: ‘nn’, ‘idw’, or ‘linear’.

  • influence (float) – Radius of influence in meters.

  • k (int) – Number of neighbors for IDW interpolation.

Example

>>> # Create interpolator once
>>> interp = RegridInterpolator(mesh.lon, mesh.lat, box=(-180, 180, -90, 90))
>>>
>>> # Use many times for different variables
>>> temp_reg, lon_reg, lat_reg = interp(ds['temp'].values)
>>> salt_reg, _, _ = interp(ds['salt'].values)
lon: ndarray
lat: ndarray
box: tuple[float, float, float, float] = (-180, 180, -90, 90)
res: tuple[int, int] = (360, 180)
method: Literal['nn', 'idw', 'linear'] = 'nn'
influence: float = 80000
k: int = 10
__post_init__()[source]

Build KDTree and compute interpolation indices.

__call__(data, fill_value=nan)[source]

Interpolate data to regular grid.

Parameters:

  • data (np.ndarray) – Data values at source points, shape (npoints,).

  • fill_value (float) – Value for points outside influence radius.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

  • data_reg (np.ndarray) – Interpolated data, shape (nlat, nlon).

  • lon_reg (np.ndarray) – 1D array of output longitudes.

  • lat_reg (np.ndarray) – 1D array of output latitudes.

__init__(lon, lat, box=(-180, 180, -90, 90), res=(360, 180), method='nn', influence=80000, k=10)
Parameters:
Return type:

None

fesomp.plotting.transect(data, mesh, start, end, *, depth=None, npoints=100, method='nn', influence=80000, fill_value=nan, interpolator=None, ax=None, fig=None, figsize=(12, 5), cmap=None, levels=None, ptype='cf', title=None, xlabel=None, ylabel=None, units=None, colorbar=True, distance_units='km', depth_limits=None, invert_yaxis=True)[source]

Interpolate and plot a vertical transect through 3D ocean data.

This is a convenience function combining interpolate_transect and plot_transect. Automatically detects: - Horizontal location: nodes (n2d points) vs elements (nelem points) - Vertical coordinate: levels (interfaces) vs layers (centers)

Parameters:

  • data (np.ndarray) – Data values at unstructured points: - Shape (nlev, n2d) for data on nodes - Shape (nlev, nelem) for data on elements Can be defined on either levels (interfaces) or layers (centers).

  • mesh (Mesh) – The mesh object containing lon, lat, and depth information.

  • start (tuple) – Starting point of transect as (lon, lat) in degrees.

  • end (tuple) – Ending point of transect as (lon, lat) in degrees.

  • depth (np.ndarray, optional) – Depth coordinates in meters. If not provided, automatically selects mesh.depth_levels or mesh.depth_layers based on data shape.

  • npoints (int) – Number of points along the transect. Default is 100.

  • method (str) – Interpolation method: ‘nn’, ‘idw’, or ‘linear’.

  • influence (float) – Radius of influence in meters. Default is 80000 (80 km).

  • fill_value (float) – Value for transect points with no data. Default is NaN.

  • interpolator (TransectInterpolator, optional) – Pre-computed interpolator for caching.

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

  • fig (matplotlib.figure.Figure, optional) – Existing figure to use.

  • figsize (tuple) – Figure size in inches if creating new figure.

  • cmap (str, optional) – Colormap name. Default is ‘RdBu_r’.

  • levels (tuple or list, optional) – Contour levels. Can be (min, max, nlevels) or explicit list.

  • ptype (str) – Plot type: ‘cf’ (contourf) or ‘pcm’ (pcolormesh).

  • title (str, optional) – Plot title.

  • xlabel (str, optional) – X-axis label.

  • ylabel (str, optional) – Y-axis label.

  • units (str, optional) – Units string for colorbar label.

  • colorbar (bool) – Whether to show colorbar. Default is True.

  • distance_units (str) – Units for distance axis: ‘m’ or ‘km’. Default is ‘km’.

  • depth_limits (tuple, optional) – Depth range to display as (min_depth, max_depth).

  • invert_yaxis (bool) – Whether to invert y-axis. Default is True.

Return type:

tuple[Figure, Axes, TransectInterpolator]

Returns:

  • fig (matplotlib.figure.Figure) – The figure object.

  • ax (matplotlib.axes.Axes) – The axes object.

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

Example

>>> # Plot temperature transect (data on layers)
>>> fig, ax, interp = fesomp.transect(
...     temp_3d,  # shape (nlev-1, n2d) - on layers
...     mesh,
...     start=(-30, -60), end=(-30, 60),
...     title="Temperature along 30W",
...     units="degC",
...     depth_limits=(0, 1000),
... )
>>>
>>> # Reuse interpolator for salinity
>>> fig2, ax2, _ = fesomp.transect(
...     salt_3d, mesh,
...     start=(-30, -60), end=(-30, 60),
...     interpolator=interp,
...     title="Salinity along 30W",
... )
fesomp.plotting.interpolate_transect(data, lon, lat, start, end, *, npoints=100, method='nn', influence=80000, fill_value=nan, interpolator=None)[source]

Interpolate unstructured data along a great circle transect.

Parameters:

  • data (np.ndarray) – Data values at unstructured points: - Shape (n2d,) for surface data - Shape (nlev, n2d) for 3D data

  • lon (np.ndarray) – Longitudes of data points in degrees.

  • lat (np.ndarray) – Latitudes of data points in degrees.

  • start (tuple) – Starting point of transect as (lon, lat) in degrees.

  • end (tuple) – Ending point of transect as (lon, lat) in degrees.

  • npoints (int) – Number of points along the transect. Default is 100.

  • method (str) – Interpolation method: - ‘nn’: Nearest neighbor (fast, default) - ‘idw’: Inverse distance weighting - ‘linear’: Linear interpolation (scipy griddata)

  • influence (float) – Radius of influence in meters. Default is 80000 (80 km).

  • fill_value (float) – Value for transect points with no data. Default is NaN.

  • interpolator (TransectInterpolator, optional) – Pre-computed interpolator for caching.

Return type:

tuple[ndarray, ndarray, TransectInterpolator]

Returns:

  • data_transect (np.ndarray) – Interpolated data along transect: - Shape (npoints,) if input was 1D - Shape (nlev, npoints) if input was 2D

  • transect_distance (np.ndarray) – Distance from start along transect in meters.

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

Example

>>> # 3D ocean data transect
>>> temp_t, dist, interp = interpolate_transect(
...     temp_3d,  # shape (nlev, n2d)
...     mesh.lon, mesh.lat,
...     start=(-30, -60), end=(-30, 60),
... )
>>> # temp_t has shape (nlev, npoints)
fesomp.plotting.plot_transect(data, distance, depth, *, ax=None, fig=None, figsize=(12, 5), cmap=None, levels=None, ptype='cf', title=None, xlabel=None, ylabel=None, units=None, colorbar=True, distance_units='km', depth_limits=None, invert_yaxis=True)[source]

Plot a vertical transect as a 2D cross-section.

Parameters:

  • data (np.ndarray) – Data values along transect, shape (nlev, npoints).

  • distance (np.ndarray) – Distance along transect in meters, shape (npoints,).

  • depth (np.ndarray) – Depth levels in meters (positive downward), shape (nlev,).

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

  • fig (matplotlib.figure.Figure, optional) – Existing figure to use.

  • figsize (tuple) – Figure size in inches if creating new figure.

  • cmap (str, optional) – Colormap name. Default is ‘RdBu_r’.

  • levels (tuple or list, optional) – Contour levels. Can be (min, max, nlevels) or explicit list. Default is auto from data.

  • ptype (str) – Plot type: ‘cf’ (contourf) or ‘pcm’ (pcolormesh).

  • title (str, optional) – Plot title.

  • xlabel (str, optional) – X-axis label. Default is ‘Distance (km)’ or ‘Distance (m)’.

  • ylabel (str, optional) – Y-axis label. Default is ‘Depth (m)’.

  • units (str, optional) – Units string for colorbar label.

  • colorbar (bool) – Whether to show colorbar. Default is True.

  • distance_units (str) – Units for distance axis: ‘m’ or ‘km’. Default is ‘km’.

  • depth_limits (tuple, optional) – Depth range to display as (min_depth, max_depth).

  • invert_yaxis (bool) – Whether to invert y-axis (so depth increases downward). Default is True.

Return type:

tuple[Figure, Axes]

Returns:

  • fig (matplotlib.figure.Figure) – The figure object.

  • ax (matplotlib.axes.Axes) – The axes object.

Example

>>> fig, ax = plot_transect(
...     temp_transect,  # shape (nlev, npoints)
...     transect_distance,
...     mesh.depth_levels,
...     title="Temperature",
...     units="degC",
... )
class fesomp.plotting.TransectInterpolator[source]

Bases: object

Cached interpolator for extracting vertical transects from unstructured 3D data.

This class pre-computes the KDTree and interpolation indices/weights, allowing fast repeated interpolation of different variables along the same transect.

Parameters:

  • lon (np.ndarray) – Longitudes of source points in degrees, shape (n2d,).

  • lat (np.ndarray) – Latitudes of source points in degrees, shape (n2d,).

  • start (tuple) – Starting point of transect as (lon, lat) in degrees.

  • end (tuple) – Ending point of transect as (lon, lat) in degrees.

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

  • method (str) – Interpolation method: ‘nn’, ‘idw’, or ‘linear’.

  • influence (float) – Radius of influence in meters.

  • k (int) – Number of neighbors for IDW interpolation.

transect_lon

Longitudes of transect points.

Type:

np.ndarray

transect_lat

Latitudes of transect points.

Type:

np.ndarray

transect_distance

Distances from start along transect in meters.

Type:

np.ndarray

Example

>>> # Create interpolator once
>>> interp = TransectInterpolator(
...     mesh.lon, mesh.lat,
...     start=(-30, -60), end=(-30, 60),
...     npoints=100,
... )
>>>
>>> # Use for different 3D variables - data shape: (nlev, n2d)
>>> temp_transect = interp(temp_3d)  # Returns (nlev, npoints)
>>> salt_transect = interp(salt_3d)
lon: ndarray
lat: ndarray
start: tuple[float, float]
end: tuple[float, float]
npoints: int = 100
method: Literal['nn', 'idw', 'linear'] = 'nn'
influence: float = 80000
k: int = 10
transect_lon: ndarray
transect_lat: ndarray
transect_distance: ndarray
__post_init__()[source]

Build KDTree and compute interpolation indices.

__call__(data, fill_value=nan)[source]

Interpolate data along the transect.

Parameters:

  • data (np.ndarray) – Data values at source points. Can be: - 1D array of shape (n2d,) for surface data - 2D array of shape (nlev, n2d) for 3D data

  • fill_value (float) – Value for points outside influence radius.

Returns:

data_transect – Interpolated data along transect: - Shape (npoints,) if input was 1D - Shape (nlev, npoints) if input was 2D

Return type:

np.ndarray

get_coordinates()[source]

Get transect coordinates.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

  • lon (np.ndarray) – Longitudes along transect.

  • lat (np.ndarray) – Latitudes along transect.

  • distance (np.ndarray) – Distance from start in meters.

__init__(lon, lat, start, end, npoints=100, method='nn', influence=80000, k=10)
Parameters:
Return type:

None

fesomp.plotting.great_circle_path(start, end, npoints=100)[source]

Compute points along a great circle path between two points.

Uses spherical linear interpolation (slerp) on a unit sphere for accurate great circle computation.

Parameters:

  • start (tuple) – Starting point as (lon, lat) in degrees.

  • end (tuple) – Ending point as (lon, lat) in degrees.

  • npoints (int) – Number of points along the path (including endpoints).

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

  • lon (np.ndarray) – Longitudes along the path in degrees, shape (npoints,).

  • lat (np.ndarray) – Latitudes along the path in degrees, shape (npoints,).

  • distance (np.ndarray) – Distance from start in meters, shape (npoints,).

Example

>>> lon, lat, dist = great_circle_path((0, 0), (90, 0), npoints=10)
>>> print(f"Total distance: {dist[-1] / 1000:.0f} km")
fesomp.plotting.great_circle_distance(start, end)[source]

Compute great circle distance between two points.

Parameters:

  • start (tuple) – Starting point as (lon, lat) in degrees.

  • end (tuple) – Ending point as (lon, lat) in degrees.

Returns:

distance – Distance in meters.

Return type:

float

Plot

Plotting functions for unstructured data.

fesomp.plotting.plot.plot(data, lon, lat, *, box=None, res=(360, 180), interp='nn', influence=80000, interpolator=None, cmap=None, levels=None, ptype='cf', mapproj='pc', figsize=(10, 6), rowscol=(1, 1), titles=None, units=None, colorbar=True, coastlines=True, land=False, gridlines=False, ax=None, fig=None)[source]

Plot unstructured data on a map.

Data is interpolated to a regular grid and plotted with cartopy.

Parameters:

  • data (np.ndarray or list of np.ndarray) – Data to plot. Can be a single array (npoints,) or a list of arrays for multiple subplots.

  • lon (np.ndarray) – Longitudes of data points in degrees.

  • lat (np.ndarray) – Latitudes of data points in degrees.

  • box (tuple, optional) – Bounding box (lon_min, lon_max, lat_min, lat_max). Default depends on projection: - ‘np’: (-180, 180, 60, 90) - ‘sp’: (-180, 180, -90, -60) - others: (-180, 180, -90, 90)

  • res (tuple) – Interpolation resolution (nlon, nlat). Default is (360, 180).

  • interp (str) – Interpolation method: ‘nn’ (nearest neighbor), ‘idw’, or ‘linear’.

  • influence (float) – Radius of influence for interpolation in meters. Default is 80000.

  • interpolator (RegridInterpolator, optional) – Pre-computed interpolator for caching. Speeds up repeated plots.

  • cmap (str, optional) – Colormap name. Default is ‘RdBu_r’.

  • levels (tuple or list, optional) – Contour levels. Can be (min, max, nlevels) or explicit list. Default is auto from data.

  • ptype (str) – Plot type: ‘cf’ (contourf) or ‘pcm’ (pcolormesh).

  • mapproj (str) – Map projection: ‘pc’ (Plate Carree), ‘rob’ (Robinson), ‘merc’ (Mercator), ‘np’ (North Polar), ‘sp’ (South Polar).

  • figsize (tuple) – Figure size in inches.

  • rowscol (tuple) – Subplot layout (nrows, ncols).

  • titles (str or list) – Title(s) for subplot(s).

  • units (str, optional) – Units label for colorbar.

  • colorbar (bool) – Whether to show colorbar. Default is True.

  • coastlines (bool) – Whether to draw coastlines. Default is True.

  • land (bool) – Whether to fill land areas. Default is False.

  • gridlines (bool) – Whether to draw gridlines. Default is False.

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

  • fig (matplotlib.figure.Figure, optional) – Existing figure to use.

Return type:

tuple[Figure, ndarray, RegridInterpolator]

Returns:

  • fig (matplotlib.figure.Figure) – The figure object.

  • axes (np.ndarray) – Array of axes objects.

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

Example

>>> # Simple plot
>>> fig, axes, interp = fesomp.plot(temp, mesh.lon, mesh.lat)
>>>
>>> # Multiple subplots with cached interpolator
>>> fig, axes, interp = fesomp.plot(
...     [temp_surface, temp_100m, temp_500m],
...     mesh.lon, mesh.lat,
...     rowscol=(1, 3),
...     titles=['Surface', '100m', '500m'],
...     interpolator=interp,  # reuse from previous
... )

Regrid

Interpolation from unstructured to regular grids.

fesomp.plotting.regrid.create_regular_grid(box=(-180, 180, -90, 90), res=(360, 180))[source]

Create a regular lon/lat grid.

Parameters:

  • box (tuple) – Bounding box as (lon_min, lon_max, lat_min, lat_max).

  • res (tuple) – Resolution as (nlon, nlat).

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

Returns:

  • lon1d (np.ndarray) – 1D array of longitudes.

  • lat1d (np.ndarray) – 1D array of latitudes.

  • lon2d (np.ndarray) – 2D meshgrid of longitudes.

  • lat2d (np.ndarray) – 2D meshgrid of latitudes.

class fesomp.plotting.regrid.RegridInterpolator[source]

Bases: object

Cached interpolator for regridding unstructured data.

This class pre-computes and caches the KDTree and interpolation indices/weights, allowing fast repeated interpolation of different variables on the same grid.

Parameters:

  • lon (np.ndarray) – Longitudes of source points in degrees.

  • lat (np.ndarray) – Latitudes of source points in degrees.

  • box (tuple) – Target bounding box as (lon_min, lon_max, lat_min, lat_max).

  • res (tuple) – Target resolution as (nlon, nlat).

  • method (str) – Interpolation method: ‘nn’, ‘idw’, or ‘linear’.

  • influence (float) – Radius of influence in meters.

  • k (int) – Number of neighbors for IDW interpolation.

Example

>>> # Create interpolator once
>>> interp = RegridInterpolator(mesh.lon, mesh.lat, box=(-180, 180, -90, 90))
>>>
>>> # Use many times for different variables
>>> temp_reg, lon_reg, lat_reg = interp(ds['temp'].values)
>>> salt_reg, _, _ = interp(ds['salt'].values)
lon: ndarray
lat: ndarray
box: tuple[float, float, float, float] = (-180, 180, -90, 90)
res: tuple[int, int] = (360, 180)
method: Literal['nn', 'idw', 'linear'] = 'nn'
influence: float = 80000
k: int = 10
__post_init__()[source]

Build KDTree and compute interpolation indices.

__call__(data, fill_value=nan)[source]

Interpolate data to regular grid.

Parameters:

  • data (np.ndarray) – Data values at source points, shape (npoints,).

  • fill_value (float) – Value for points outside influence radius.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

  • data_reg (np.ndarray) – Interpolated data, shape (nlat, nlon).

  • lon_reg (np.ndarray) – 1D array of output longitudes.

  • lat_reg (np.ndarray) – 1D array of output latitudes.

__init__(lon, lat, box=(-180, 180, -90, 90), res=(360, 180), method='nn', influence=80000, k=10)
Parameters:
Return type:

None

fesomp.plotting.regrid.regrid(data, lon, lat, box=(-180, 180, -90, 90), res=(360, 180), method='nn', influence=80000, fill_value=nan, interpolator=None)[source]

Interpolate unstructured data to a regular grid.

Parameters:

  • data (np.ndarray) – Data values at unstructured points, shape (npoints,).

  • lon (np.ndarray) – Longitudes of data points in degrees, shape (npoints,).

  • lat (np.ndarray) – Latitudes of data points in degrees, shape (npoints,).

  • box (tuple) – Bounding box as (lon_min, lon_max, lat_min, lat_max). Default is global (-180, 180, -90, 90).

  • res (tuple) – Output resolution as (nlon, nlat). Default is (360, 180).

  • method (str) – Interpolation method: - ‘nn’: Nearest neighbor (fast, default) - ‘idw’: Inverse distance weighting - ‘linear’: Linear interpolation (scipy griddata)

  • influence (float) – Radius of influence in meters. Points outside this radius from any source point will be set to fill_value. Default is 80000 (80 km).

  • fill_value (float) – Value for grid points with no data. Default is NaN.

  • interpolator (RegridInterpolator, optional) – Pre-computed interpolator for caching. If provided, lon, lat, box, res, method, and influence are ignored.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

  • data_reg (np.ndarray) – Interpolated data on regular grid, shape (nlat, nlon).

  • lon_reg (np.ndarray) – 1D array of output longitudes.

  • lat_reg (np.ndarray) – 1D array of output latitudes.

Example

>>> # Simple one-off interpolation
>>> data_reg, lon_reg, lat_reg = regrid(temp, mesh.lon, mesh.lat)
>>>
>>> # With caching for multiple variables
>>> interp = RegridInterpolator(mesh.lon, mesh.lat)
>>> temp_reg, lon_reg, lat_reg = regrid(temp, mesh.lon, mesh.lat, interpolator=interp)
>>> salt_reg, _, _ = regrid(salt, mesh.lon, mesh.lat, interpolator=interp)

Transect

Transect interpolation and plotting for unstructured 3D ocean data.

This module provides functionality for extracting and visualizing vertical cross-sections (transects) through unstructured ocean model data.

fesomp.plotting.transect.great_circle_path(start, end, npoints=100)[source]

Compute points along a great circle path between two points.

Uses spherical linear interpolation (slerp) on a unit sphere for accurate great circle computation.

Parameters:

  • start (tuple) – Starting point as (lon, lat) in degrees.

  • end (tuple) – Ending point as (lon, lat) in degrees.

  • npoints (int) – Number of points along the path (including endpoints).

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

  • lon (np.ndarray) – Longitudes along the path in degrees, shape (npoints,).

  • lat (np.ndarray) – Latitudes along the path in degrees, shape (npoints,).

  • distance (np.ndarray) – Distance from start in meters, shape (npoints,).

Example

>>> lon, lat, dist = great_circle_path((0, 0), (90, 0), npoints=10)
>>> print(f"Total distance: {dist[-1] / 1000:.0f} km")
fesomp.plotting.transect.great_circle_distance(start, end)[source]

Compute great circle distance between two points.

Parameters:

  • start (tuple) – Starting point as (lon, lat) in degrees.

  • end (tuple) – Ending point as (lon, lat) in degrees.

Returns:

distance – Distance in meters.

Return type:

float

class fesomp.plotting.transect.TransectInterpolator[source]

Bases: object

Cached interpolator for extracting vertical transects from unstructured 3D data.

This class pre-computes the KDTree and interpolation indices/weights, allowing fast repeated interpolation of different variables along the same transect.

Parameters:

  • lon (np.ndarray) – Longitudes of source points in degrees, shape (n2d,).

  • lat (np.ndarray) – Latitudes of source points in degrees, shape (n2d,).

  • start (tuple) – Starting point of transect as (lon, lat) in degrees.

  • end (tuple) – Ending point of transect as (lon, lat) in degrees.

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

  • method (str) – Interpolation method: ‘nn’, ‘idw’, or ‘linear’.

  • influence (float) – Radius of influence in meters.

  • k (int) – Number of neighbors for IDW interpolation.

transect_lon

Longitudes of transect points.

Type:

np.ndarray

transect_lat

Latitudes of transect points.

Type:

np.ndarray

transect_distance

Distances from start along transect in meters.

Type:

np.ndarray

Example

>>> # Create interpolator once
>>> interp = TransectInterpolator(
...     mesh.lon, mesh.lat,
...     start=(-30, -60), end=(-30, 60),
...     npoints=100,
... )
>>>
>>> # Use for different 3D variables - data shape: (nlev, n2d)
>>> temp_transect = interp(temp_3d)  # Returns (nlev, npoints)
>>> salt_transect = interp(salt_3d)
lon: ndarray
lat: ndarray
start: tuple[float, float]
end: tuple[float, float]
npoints: int = 100
method: Literal['nn', 'idw', 'linear'] = 'nn'
influence: float = 80000
k: int = 10
transect_lon: ndarray
transect_lat: ndarray
transect_distance: ndarray
__post_init__()[source]

Build KDTree and compute interpolation indices.

__call__(data, fill_value=nan)[source]

Interpolate data along the transect.

Parameters:

  • data (np.ndarray) – Data values at source points. Can be: - 1D array of shape (n2d,) for surface data - 2D array of shape (nlev, n2d) for 3D data

  • fill_value (float) – Value for points outside influence radius.

Returns:

data_transect – Interpolated data along transect: - Shape (npoints,) if input was 1D - Shape (nlev, npoints) if input was 2D

Return type:

np.ndarray

get_coordinates()[source]

Get transect coordinates.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

  • lon (np.ndarray) – Longitudes along transect.

  • lat (np.ndarray) – Latitudes along transect.

  • distance (np.ndarray) – Distance from start in meters.

__init__(lon, lat, start, end, npoints=100, method='nn', influence=80000, k=10)
Parameters:
Return type:

None

fesomp.plotting.transect.interpolate_transect(data, lon, lat, start, end, *, npoints=100, method='nn', influence=80000, fill_value=nan, interpolator=None)[source]

Interpolate unstructured data along a great circle transect.

Parameters:

  • data (np.ndarray) – Data values at unstructured points: - Shape (n2d,) for surface data - Shape (nlev, n2d) for 3D data

  • lon (np.ndarray) – Longitudes of data points in degrees.

  • lat (np.ndarray) – Latitudes of data points in degrees.

  • start (tuple) – Starting point of transect as (lon, lat) in degrees.

  • end (tuple) – Ending point of transect as (lon, lat) in degrees.

  • npoints (int) – Number of points along the transect. Default is 100.

  • method (str) – Interpolation method: - ‘nn’: Nearest neighbor (fast, default) - ‘idw’: Inverse distance weighting - ‘linear’: Linear interpolation (scipy griddata)

  • influence (float) – Radius of influence in meters. Default is 80000 (80 km).

  • fill_value (float) – Value for transect points with no data. Default is NaN.

  • interpolator (TransectInterpolator, optional) – Pre-computed interpolator for caching.

Return type:

tuple[ndarray, ndarray, TransectInterpolator]

Returns:

  • data_transect (np.ndarray) – Interpolated data along transect: - Shape (npoints,) if input was 1D - Shape (nlev, npoints) if input was 2D

  • transect_distance (np.ndarray) – Distance from start along transect in meters.

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

Example

>>> # 3D ocean data transect
>>> temp_t, dist, interp = interpolate_transect(
...     temp_3d,  # shape (nlev, n2d)
...     mesh.lon, mesh.lat,
...     start=(-30, -60), end=(-30, 60),
... )
>>> # temp_t has shape (nlev, npoints)
fesomp.plotting.transect.plot_transect(data, distance, depth, *, ax=None, fig=None, figsize=(12, 5), cmap=None, levels=None, ptype='cf', title=None, xlabel=None, ylabel=None, units=None, colorbar=True, distance_units='km', depth_limits=None, invert_yaxis=True)[source]

Plot a vertical transect as a 2D cross-section.

Parameters:

  • data (np.ndarray) – Data values along transect, shape (nlev, npoints).

  • distance (np.ndarray) – Distance along transect in meters, shape (npoints,).

  • depth (np.ndarray) – Depth levels in meters (positive downward), shape (nlev,).

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

  • fig (matplotlib.figure.Figure, optional) – Existing figure to use.

  • figsize (tuple) – Figure size in inches if creating new figure.

  • cmap (str, optional) – Colormap name. Default is ‘RdBu_r’.

  • levels (tuple or list, optional) – Contour levels. Can be (min, max, nlevels) or explicit list. Default is auto from data.

  • ptype (str) – Plot type: ‘cf’ (contourf) or ‘pcm’ (pcolormesh).

  • title (str, optional) – Plot title.

  • xlabel (str, optional) – X-axis label. Default is ‘Distance (km)’ or ‘Distance (m)’.

  • ylabel (str, optional) – Y-axis label. Default is ‘Depth (m)’.

  • units (str, optional) – Units string for colorbar label.

  • colorbar (bool) – Whether to show colorbar. Default is True.

  • distance_units (str) – Units for distance axis: ‘m’ or ‘km’. Default is ‘km’.

  • depth_limits (tuple, optional) – Depth range to display as (min_depth, max_depth).

  • invert_yaxis (bool) – Whether to invert y-axis (so depth increases downward). Default is True.

Return type:

tuple[Figure, Axes]

Returns:

  • fig (matplotlib.figure.Figure) – The figure object.

  • ax (matplotlib.axes.Axes) – The axes object.

Example

>>> fig, ax = plot_transect(
...     temp_transect,  # shape (nlev, npoints)
...     transect_distance,
...     mesh.depth_levels,
...     title="Temperature",
...     units="degC",
... )
fesomp.plotting.transect.transect(data, mesh, start, end, *, depth=None, npoints=100, method='nn', influence=80000, fill_value=nan, interpolator=None, ax=None, fig=None, figsize=(12, 5), cmap=None, levels=None, ptype='cf', title=None, xlabel=None, ylabel=None, units=None, colorbar=True, distance_units='km', depth_limits=None, invert_yaxis=True)[source]

Interpolate and plot a vertical transect through 3D ocean data.

This is a convenience function combining interpolate_transect and plot_transect. Automatically detects: - Horizontal location: nodes (n2d points) vs elements (nelem points) - Vertical coordinate: levels (interfaces) vs layers (centers)

Parameters:

  • data (np.ndarray) – Data values at unstructured points: - Shape (nlev, n2d) for data on nodes - Shape (nlev, nelem) for data on elements Can be defined on either levels (interfaces) or layers (centers).

  • mesh (Mesh) – The mesh object containing lon, lat, and depth information.

  • start (tuple) – Starting point of transect as (lon, lat) in degrees.

  • end (tuple) – Ending point of transect as (lon, lat) in degrees.

  • depth (np.ndarray, optional) – Depth coordinates in meters. If not provided, automatically selects mesh.depth_levels or mesh.depth_layers based on data shape.

  • npoints (int) – Number of points along the transect. Default is 100.

  • method (str) – Interpolation method: ‘nn’, ‘idw’, or ‘linear’.

  • influence (float) – Radius of influence in meters. Default is 80000 (80 km).

  • fill_value (float) – Value for transect points with no data. Default is NaN.

  • interpolator (TransectInterpolator, optional) – Pre-computed interpolator for caching.

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

  • fig (matplotlib.figure.Figure, optional) – Existing figure to use.

  • figsize (tuple) – Figure size in inches if creating new figure.

  • cmap (str, optional) – Colormap name. Default is ‘RdBu_r’.

  • levels (tuple or list, optional) – Contour levels. Can be (min, max, nlevels) or explicit list.

  • ptype (str) – Plot type: ‘cf’ (contourf) or ‘pcm’ (pcolormesh).

  • title (str, optional) – Plot title.

  • xlabel (str, optional) – X-axis label.

  • ylabel (str, optional) – Y-axis label.

  • units (str, optional) – Units string for colorbar label.

  • colorbar (bool) – Whether to show colorbar. Default is True.

  • distance_units (str) – Units for distance axis: ‘m’ or ‘km’. Default is ‘km’.

  • depth_limits (tuple, optional) – Depth range to display as (min_depth, max_depth).

  • invert_yaxis (bool) – Whether to invert y-axis. Default is True.

Return type:

tuple[Figure, Axes, TransectInterpolator]

Returns:

  • fig (matplotlib.figure.Figure) – The figure object.

  • ax (matplotlib.axes.Axes) – The axes object.

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

Example

>>> # Plot temperature transect (data on layers)
>>> fig, ax, interp = fesomp.transect(
...     temp_3d,  # shape (nlev-1, n2d) - on layers
...     mesh,
...     start=(-30, -60), end=(-30, 60),
...     title="Temperature along 30W",
...     units="degC",
...     depth_limits=(0, 1000),
... )
>>>
>>> # Reuse interpolator for salinity
>>> fig2, ax2, _ = fesomp.transect(
...     salt_3d, mesh,
...     start=(-30, -60), end=(-30, 60),
...     interpolator=interp,
...     title="Salinity along 30W",
... )