roms_tools.plot.plot

Contents

roms_tools.plot.plot#

roms_tools.plot.plot(field: DataArray, grid_ds: DataArray, zeta: DataArray | float = 0.0, s: int | None = None, eta: int | None = None, xi: int | None = None, depth: float | None = None, lat: float | None = None, lon: float | None = None, include_boundary: bool = True, depth_contours: bool = False, layer_contours: bool = False, max_nr_layer_contours: int | None = 10, yincrease: bool | None = None, use_coarse_grid: bool = False, with_dim_names: bool = False, apply_mask: bool = True, ax: Axes | None = None, save_path: str | None = None, cmap_name: str = 'YlOrRd', add_colorbar: bool = True) → None#

Generate a plot of a 2D or 3D ROMS field for a horizontal or vertical slice.

This function supports plotting:

  • horizontal slices at a specific vertical level or depth,

  • vertical sections along constant indices or geographic lines,

  • or 2D fields directly.

Parameters:

  • field (xr.DataArray) – ROMS variable already selected at a single time index.

  • grid_ds (xr.DataArray) – ROMS grid dataset containing the grid geometry, including latitude/longitude, inverse grid spacing (pm, pn), depth (h), and land/sea mask. It must also include the attribute “straddle” to indicate whether the grid crosses the dateline.

  • zeta (xr.DataArray or float, optional) – Sea surface height for computing vertical coordinates. Defaults to 0.0 (flat surface).

  • s (int, optional) – Vertical layer index (s_rho) to plot. Cannot be used with depth. Default is None.

  • eta (int, optional) – Eta index for vertical sections or constant-eta horizontal slices. Cannot be used with lat or lon. Default is None.

  • xi (int, optional) – Xi index for vertical sections or constant-xi horizontal slices. Cannot be used with lat or lon. Default is None.

  • depth (float, optional) – Physical depth (in meters) for horizontal slices. Cannot be used with s. Default is None.

  • lat (float, optional) – Latitude (in degrees) for vertical sections. Cannot be combined with eta or xi. Default is None.

  • lon (float, optional) – Longitude (in degrees) for vertical sections. Cannot be combined with eta or xi. Default is None.

  • include_boundary (bool, optional) – Whether to include the outermost grid cells along the eta- and xi-boundaries in the plot. Useful to exclude ghost points. Default is True.

  • depth_contours (bool, optional) – If True, add contours of constant bathymetry to horizontal plots. Ignored otherwise. Default is False.

  • layer_contours (bool, optional) – If True, show vertical layer boundaries in vertical sections. Default is False.

  • max_nr_layer_contours (int, optional) – Maximum number of vertical layer contours to draw. Default is 10.

  • yincrease (bool, optional) – If True, the y-axis values increase upward (standard orientation). If False, the y-axis values decrease upward (inverted axis). If None (default), the orientation is determined by the default behavior of the underlying plotting function.

  • use_coarse_grid (bool, optional) – Use precomputed coarse-resolution grid. Default is False.

  • with_dim_names (bool, optional) – Add grid dimension names (xi, eta) to the outer plot edges. Only for 2D plots. Default is False.

  • apply_mask (bool, optional) – Whether to apply the land mask to the field. Default is True.

  • ax (Axes, optional) – Matplotlib axes object. If None, a new figure is created. Default is None.

  • save_path (str, optional) – File path to save the plot. If None, the plot is shown interactively. Default is None.

  • cmap_name (str, optional) – Name of matplotlib colormap. Default is “YlOrRd”.

  • add_colorbar (bool, optional) – Whether to add a colorbar to the plot. Default is True.

Returns:

None – The function generates and shows or saves a plot. No value is returned.

Raises:

ValueError –

  • If no plotting dimensions are specified for 3D fields. - If conflicting dimensions are specified (e.g., both s and depth). - If incompatible combinations of grid indices and geographic coordinates are provided. - If specified eta or xi indices are out of bounds. - If boundary indices are used when include_boundary=False.

Contents