roms_tools.ROMSOutput.plot

roms_tools.ROMSOutput.plot#

ROMSOutput.plot(var_name: str, time: int = 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 = False, depth_contours: bool = False, ax: Axes | None = None, save_path: str | None = None) → None#

Generate a plot of a ROMS output field for a specified vertical or horizontal slice.

Parameters:

  • var_name (str) –

    Name of the variable to plot. Supported options include:

    • Oceanographic fields: “temp”, “salt”, “zeta”, “u”, “v”, “w”, etc.

    • Biogeochemical tracers: “PO4”, “NO3”, “O2”, “DIC”, “ALK”, etc.

  • time (int, optional) – Index of the time dimension to plot. Default is 0.

  • s (int, optional) – The index of the vertical layer (s_rho) to plot. If specified, the plot will display a horizontal slice at that layer. Cannot be used simultaneously with depth. Default is None.

  • eta (int, optional) – The eta-index to plot. Used for generating vertical sections or plotting horizontal slices along a constant eta-coordinate. Cannot be used simultaneously with lat or lon, but can be combined with xi. Default is None.

  • xi (int, optional) – The xi-index to plot. Used for generating vertical sections or plotting horizontal slices along a constant xi-coordinate. Cannot be used simultaneously with lat or lon, but can be combined with eta. Default is None.

  • depth (float, optional) – Depth (in meters) to plot a horizontal slice at a specific depth level. If specified, the plot will interpolate the field to the given depth. Cannot be used simultaneously with s or for fields that are inherently 2D (such as “zeta”). Default is None.

  • lat (float, optional) – Latitude (in degrees) to plot a vertical section at a specific latitude. This option is useful for generating zonal (west-east) sections. Cannot be used simultaneously with eta or xi, bu can be combined with lon. Default is None.

  • lon (float, optional) – Longitude (in degrees) to plot a vertical section at a specific longitude. This option is useful for generating meridional (south-north) sections. Cannot be used simultaneously with eta or xi, but can be combined with lat. Default is None.

  • include_boundary (bool, optional) – Whether to include the outermost grid cells along the eta- and xi-boundaries in the plot. In diagnostic ROMS output fields, these boundary cells are set to zero, so excluding them can improve visualization. Default is False.

  • depth_contours (bool, optional) – If True, overlays contours representing lines of constant depth on the plot. This option is only relevant when the s parameter is provided (i.e., not None). By default, depth contours are not shown (False).

  • ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure is created. Note that this argument is ignored for 2D horizontal plots. Default is None.

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

Returns:

None – This method does not return any value. It generates and displays a plot.

Raises:

ValueError –

  • If the specified var_name is not one of the valid options. - If the field specified by var_name is 3D and none of s, eta, xi, depth, lat, or lon are specified. - If the field specified by var_name is 2D and both eta and xi or both lat and lon are specified. - If conflicting dimensions are specified (e.g., specifying eta/xi with lat/lon or both s and depth). - If more than two dimensions are specified for a 3D field. - If time exceeds the bounds of the time dimension. - If time is specified for a field that does not have a time dimension. - If eta or xi indices are out of bounds. - If eta or xi lie on the boundary when include_boundary=False.