easyclimate.plot.icon¶

Convenience imports for ICON native-grid plotting helpers.

Submodules¶

Functions¶

`plot_cell_contour`(ds, da, *[, ax, lon_min, lon_max, ...])	Draw contour lines for ICON cell-centered scalar data.
`plot_cell_contourf`(ds, da, *[, ax, lon_min, lon_max, ...])	Draw filled contour for ICON cell-centered scalar data.
`plot_cell_barbs`(ds, u_da, v_da, *[, ax, lon_min, ...])	Plot cell-centered vector wind as wind barbs on an ICON mesh.
`plot_cell_curved_quiver`(...)	Plot ICON cell-centered vector wind as curved quiver trajectories.
`plot_cell_quiver`(ds, u_da, v_da, *[, ax, lon_min, ...])	Plot cell-centered vector wind on an ICON mesh.
`plot_cell_streamplot`(ds, u_da, v_da, *[, ax, lon_min, ...])	Plot cell-centered vector wind as streamlines on an ICON mesh.
`plot_cell_triangular`(ds, da, *[, ax, transform, ...])	Plot ICON cell-centered scalar data on native triangular cells.
`plot_triangular_grid`(ds, *[, lon_min, lon_max, ...])	Plot ICON native triangular mesh edges.

Package Contents¶

easyclimate.plot.icon.plot_cell_contour(ds, da, *, ax=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, auto_extent=True, extent_margin=0.05, contour_margin=0.05, global_plot=False, center_lon=None, levels=10, colors=None, linewidths=0.8, linestyles=None, cmap=None, vmin=None, vmax=None, symmetric=False, percentile=98, extend=None, max_triangle_edge=None, input_radians=True, transform=None, title=None, lon_name_cell='clon', lat_name_cell='clat', use_triangulation_cache=True)¶

Draw contour lines for ICON cell-centered scalar data.

Labels are not added automatically. Add them outside this function with ax.clabel(cs, inline=True, fontsize=8, fmt="%g").

Parameters¶

dsxarray.Dataset: ICON dataset containing cell coordinate variables.
daxarray.DataArray or numpy.ndarray: Cell-centered scalar values. The data must be one-dimensional on ncells after any time or vertical-level selection.
axmatplotlib.axes.Axes, optional: Axes on which to draw. By default, use the current axes.
lon_min, lon_max, lat_min, lat_maxfloat, optional: Plot extent in degrees. Cross-dateline longitude windows are supported.
auto_extentbool, default: True: If True and no explicit extent is supplied, infer the extent from valid cell centers.
extent_marginfloat, default: 0.05: Fractional margin added to the automatically inferred extent.
contour_marginfloat, default: 0.05: Fractional padding used when selecting source cells for contouring.
global_plotbool, default: False: If True, draw a global extent centered on center_lon.
center_lonfloat, optional: Longitude center used for wrapping. If None, infer it from the extent or valid cell centers.
levelsint or array-like, default: 10: Number of contour levels, or explicit level values.
colorscolor or collections.abc.Sequence of colors, optional: Fixed line colors passed to Axes.tricontour. If omitted, use cmap.
linewidths, linestyles: Contour line style options passed to Axes.tricontour.
cmapstr or matplotlib.colors.Colormap, optional: Colormap used when colors is not supplied.
vmin, vmaxfloat, optional: Data limits used by contour levels and color mapping.
symmetricbool, default: False: If True, infer symmetric limits around zero when vmin or vmax is omitted.
percentilefloat, default: 98: Percentile used for automatic data-limit inference.
extend{“neither”, “both”, “min”, “max”}, optional: Contour extension mode. If None, infer it from data and levels.
max_triangle_edgefloat, optional: Maximum accepted edge length for triangles. Longer triangles are masked.
input_radiansbool, default: True: If True, ICON longitude and latitude variables are interpreted as radians and converted to degrees.
transformcartopy.crs.CRS, optional: Coordinate reference system of the input coordinates for Cartopy axes.
titlestr, optional: Axes title. If None, use the data long name.
lon_name_cell, lat_name_cellstr: ICON cell coordinate variable names.
use_triangulation_cachebool, default: True: If True, cache the triangulation for repeated calls on the same mesh and extent.

Returns¶

matplotlib.contour.QuadContourSet: Contour set returned by Axes.tricontour.

ICON Cell-centered contour plots

easyclimate.plot.icon.plot_cell_contourf(ds, da, *, ax=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, auto_extent=True, extent_margin=0.05, contour_margin=0.05, global_plot=False, center_lon=None, levels=10, cmap=None, vmin=None, vmax=None, symmetric=False, percentile=98, extend=None, max_triangle_edge=None, input_radians=True, transform=None, add_colorbar=True, cbar_kwargs=None, title=None, lon_name_cell='clon', lat_name_cell='clat', use_triangulation_cache=True)¶

Draw filled contour for ICON cell-centered scalar data.

The scalar values are drawn from ICON cell centers using matplotlib.tri.Triangulation.

Parameters¶

dsxarray.Dataset: ICON dataset containing cell coordinate variables.
daxarray.DataArray or numpy.ndarray: Cell-centered scalar values. The data must be one-dimensional on ncells after any time or vertical-level selection.
axmatplotlib.axes.Axes, optional: Axes on which to draw. By default, use the current axes.
lon_min, lon_max, lat_min, lat_maxfloat, optional: Plot extent in degrees. Cross-dateline longitude windows are supported.
auto_extentbool, default: True: If True and no explicit extent is supplied, infer the extent from valid cell centers.
extent_marginfloat, default: 0.05: Fractional margin added to the automatically inferred extent.
contour_marginfloat, default: 0.05: Fractional padding used when selecting source cells for contouring.
global_plotbool, default: False: If True, draw a global extent centered on center_lon.
center_lonfloat, optional: Longitude center used for wrapping. If None, infer it from the extent or valid cell centers.
levelsint or array-like, default: 10: Number of contour levels, or explicit level values.
cmapstr or matplotlib.colors.Colormap, optional: Colormap used for filled contours.
vmin, vmaxfloat, optional: Color/data limits used by contour levels and color mapping.
symmetricbool, default: False: If True, infer symmetric limits around zero when vmin or vmax is omitted.
percentilefloat, default: 98: Percentile used for automatic data-limit inference.
extend{“neither”, “both”, “min”, “max”}, optional: Colorbar extension mode. If None, infer it from data and levels.
max_triangle_edgefloat, optional: Maximum accepted edge length for triangles. Longer triangles are masked.
input_radiansbool, default: True: If True, ICON longitude and latitude variables are interpreted as radians and converted to degrees.
transformcartopy.crs.CRS, optional: Coordinate reference system of the input coordinates for Cartopy axes.
add_colorbarbool, default: True: If True, add a colorbar for the filled contour set.
cbar_kwargsdict, optional: Keyword arguments passed to Figure.colorbar.
titlestr, optional: Axes title. If None, use the data long name.
lon_name_cell, lat_name_cellstr: ICON cell coordinate variable names.
use_triangulation_cachebool, default: True: If True, cache the triangulation for repeated calls on the same mesh and extent.

Returns¶

matplotlib.contour.QuadContourSet: Filled contour set returned by Axes.tricontourf.

ICON Cell-centered contour plots

easyclimate.plot.icon.plot_cell_barbs(ds, u_da, v_da, *, ax=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, center_lon=None, input_radians=True, lon_name_cell='clon', lat_name_cell='clat', nx_bins=35, ny_bins=20, thin_method='nearest_center', use_thinning_cache=True, transform=None, title=None, **barbs_kwargs)¶

Plot cell-centered vector wind as wind barbs on an ICON mesh.

ICON cell-centered vectors are thinned into regular longitude-latitude bins before they are passed to Axes.barbs. This keeps barb density readable on native ICON triangular meshes.

Parameters¶

dsxarray.Dataset: ICON dataset containing cell coordinate variables.
u_da, v_daxarray.DataArray or numpy.ndarray: Cell-centered zonal/eastward and meridional/northward vector components. Each input must be one-dimensional on ncells after selecting time or vertical dimensions.
axmatplotlib.axes.Axes, optional: Axes on which to draw. By default, use the current axes.
lon_min, lon_max, lat_min, lat_maxfloat: Plot extent in degrees. These bounds are required so vector thinning is restricted to the requested ICON domain.
center_lonfloat, optional: Longitude center used for wrapping. If None, infer it from the extent or valid cell centers.
input_radiansbool, default: True: If True, ICON longitude and latitude variables are interpreted as radians and converted to degrees.
lon_name_cell, lat_name_cellstr: ICON cell coordinate variable names.
nx_bins, ny_binsint, default: 35, 20: Number of longitude and latitude bins used to thin vectors.
thin_method{“nearest_center”, “max_speed”, “mean”}, default: “nearest_center”: Rule used to choose or aggregate one vector per bin.
use_thinning_cachebool, default: True: If True, cache coordinate-only bin metadata for repeated calls on the same ICON mesh and extent.
transformcartopy.crs.CRS, optional: Coordinate reference system of the input coordinates for Cartopy axes.
titlestr, optional: Axes title. If None, use a default wind-barb title.
**barbs_kwargs: Additional keyword arguments passed to Axes.barbs.

Returns¶

matplotlib.quiver.Barbs: Barb container returned by Axes.barbs.

ICON Cell-centered wind barb plots

easyclimate.plot.icon.plot_cell_curved_quiver(ds, u_da, v_da, *, ax=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, center_lon=None, input_radians=True, lon_name_cell='clon', lat_name_cell='clat', nx=160, ny=100, interpolation_padding=None, interpolation_padding_cells=2.0, min_valid_fraction=0.02, max_triangle_edge=None, use_triangulation_cache=True, transform=None, project_to_map=True, density=1, linewidth=None, color=None, cmap=None, norm=None, arrowsize=1, arrowstyle='-|>', zorder=None, start_points=None, integration_direction='both', grains=15, broken_streamlines=True, ref_magnitude: float | None = None, ref_length: float | None = None, min_frac_length: float = 0.0, length_norm: Literal['reference', 'max', 'percentile'] = 'reference', mask_density: int | tuple[int, int] = 10, line_start_stride: int = 1, arrow_stride: int = 1, min_distance: float = 0.0, arrow_head_ratio: float = 1.0, arrow_position: float = 1.0, title=None) → easyclimate.plot.modplot.CurvedQuiverplotSet¶

Plot ICON cell-centered vector wind as curved quiver trajectories.

ICON cell-centered irregular vectors are first interpolated onto a regular grid, then drawn with the same curved-quiver engine used by easyclimate.plot.curved_quiver_plot.curved_quiver().

Parameters¶

dsxarray.Dataset: ICON dataset containing cell coordinate variables.
u_da, v_daxarray.DataArray or numpy.ndarray: Cell-centered zonal/eastward and meridional/northward vector components. Each input must be one-dimensional on ncells after selecting time or vertical dimensions.
axmatplotlib.axes.Axes, optional: Axes on which to draw. By default, use the current axes.
lon_min, lon_max, lat_min, lat_maxfloat: Plot extent in degrees. These bounds are required to define the regular interpolation grid.
center_lonfloat, optional: Longitude center used for wrapping. If None, infer it from the extent or valid cell centers.
input_radiansbool, default: True: If True, ICON longitude and latitude variables are interpreted as radians and converted to degrees.
lon_name_cell, lat_name_cellstr: ICON cell coordinate variable names.
nx, nyint, default: 160, 100: Number of longitude and latitude points in the regular interpolation grid.
interpolation_paddingfloat or (float, float) or None, optional: Extra longitude/latitude degrees used only when selecting source ICON cells for interpolation. If None, padding is inferred from interpolation_padding_cells and the regular grid spacing.
interpolation_padding_cellsfloat, default: 2.0: Number of regular-grid cells used as automatic interpolation padding.
min_valid_fractionfloat, default: 0.02: Minimum fraction of valid interpolated grid points required before plotting.
max_triangle_edgefloat, optional: Maximum accepted source-cell separation for interpolation support. Longer source triangles are masked when a triangulation-based cache path is used.
use_triangulation_cachebool, default: True: If True, cache geometry-only interpolation metadata for repeated calls on the same ICON mesh and grid.
transformcartopy.crs.CRS, optional: Coordinate reference system of the input coordinates for Cartopy axes.
project_to_mapbool, default: True: For Cartopy GeoAxes, transform the regular lon-lat grid and vector components to the target projection before drawing when the transformed grid remains rectilinear.
density, linewidth, color, cmap, norm, arrowsize, arrowstyle: Curved-quiver style options passed to velovect.
zorder, start_points, integration_direction, grains, broken_streamlines: Curved-quiver trajectory options passed to velovect.
ref_magnitude, ref_length, min_frac_length, length_norm: Options controlling how vector magnitude maps to curved-vector length.
mask_density, line_start_stride, arrow_stride, min_distance: Options controlling seed-point density and collision masking.
arrow_head_ratio, arrow_position: Arrow-head size and placement controls.
titlestr, optional: Axes title. If None, use a default curved-quiver title.

Returns¶

easyclimate.plot.modplot.CurvedQuiverplotSet: Container with line and arrow artists returned by velovect.

ICON Cell-centered curved quiver plots

easyclimate.plot.icon.plot_cell_quiver(ds, u_da, v_da, *, ax=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, center_lon=None, input_radians=True, lon_name_cell='clon', lat_name_cell='clat', nx_bins=35, ny_bins=20, thin_method='nearest_center', use_thinning_cache=True, add_quiverkey=True, quiverkey_value=None, quiverkey_label=None, quiverkey_x=0.88, quiverkey_y=1.04, transform=None, title=None, **quiver_kwargs)¶

Plot cell-centered vector wind on an ICON mesh.

ICON cell-centered vectors are thinned into regular longitude-latitude bins before they are passed to Axes.quiver. This keeps vector density readable on native ICON triangular meshes.

Parameters¶

dsxarray.Dataset: ICON dataset containing cell coordinate variables.
u_da, v_daxarray.DataArray or numpy.ndarray: Cell-centered zonal/eastward and meridional/northward vector components. Each input must be one-dimensional on ncells after selecting time or vertical dimensions.
axmatplotlib.axes.Axes, optional: Axes on which to draw. By default, use the current axes.
lon_min, lon_max, lat_min, lat_maxfloat: Plot extent in degrees. These bounds are required so vector thinning is restricted to the requested ICON domain.
center_lonfloat, optional: Longitude center used for wrapping. If None, infer it from the extent or valid cell centers.
input_radiansbool, default: True: If True, ICON longitude and latitude variables are interpreted as radians and converted to degrees.
lon_name_cell, lat_name_cellstr: ICON cell coordinate variable names.
nx_bins, ny_binsint, default: 35, 20: Number of longitude and latitude bins used to thin vectors.
thin_method{“nearest_center”, “max_speed”, “mean”}, default: “nearest_center”: Rule used to choose or aggregate one vector per bin.
use_thinning_cachebool, default: True: If True, cache coordinate-only bin metadata for repeated calls on the same ICON mesh and extent.
add_quiverkeybool, default: True: If True, add a reference quiver key.
quiverkey_valuefloat, optional: Reference vector magnitude for the quiver key. If None, use the 75th percentile of thinned vector speeds.
quiverkey_labelstr, optional: Label for the quiver key. If None, build a metres-per-second label from quiverkey_value.
quiverkey_x, quiverkey_yfloat, default: 0.88, 1.04: Quiver-key position in axes coordinates.
transformcartopy.crs.CRS, optional: Coordinate reference system of the input coordinates for Cartopy axes.
titlestr, optional: Axes title. If None, use a default wind title.
**quiver_kwargs: Additional keyword arguments passed to Axes.quiver.

Returns¶

matplotlib.quiver.Quiver: Quiver object returned by Axes.quiver.

ICON Cell-centered quiver plots

easyclimate.plot.icon.plot_cell_streamplot(ds, u_da, v_da, *, ax=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, center_lon=None, input_radians=True, lon_name_cell='clon', lat_name_cell='clat', nx=160, ny=100, interpolation_padding=None, interpolation_padding_cells=2.0, min_valid_fraction=0.02, max_triangle_edge=None, use_triangulation_cache=True, transform=None, title=None, **streamplot_kwargs)¶

Plot cell-centered vector wind as streamlines on an ICON mesh.

ICON cell-centered irregular vectors are first interpolated onto a regular lon-lat grid with SciPy linear interpolation, then passed to Axes.streamplot / Cartopy GeoAxes streamplot.

Parameters¶

dsxarray.Dataset: ICON dataset containing cell coordinate variables.
u_da, v_daxarray.DataArray or numpy.ndarray: Cell-centered zonal/eastward and meridional/northward vector components. Each input must be one-dimensional on ncells after selecting time or vertical dimensions.
axmatplotlib.axes.Axes, optional: Axes on which to draw. By default, use the current axes.
lon_min, lon_max, lat_min, lat_maxfloat: Plot extent in degrees. These bounds are required to define the regular interpolation grid.
center_lonfloat, optional: Longitude center used for wrapping. If None, infer it from the extent or valid cell centers.
input_radiansbool, default: True: If True, ICON longitude and latitude variables are interpreted as radians and converted to degrees.
lon_name_cell, lat_name_cellstr: ICON cell coordinate variable names.
nx, nyint, default: 160, 100: Number of longitude and latitude points in the regular interpolation grid.
interpolation_paddingfloat or (float, float) or None, optional: Extra longitude/latitude degrees used only when selecting source ICON cells for interpolation. Padding keeps the requested output grid inside the interpolation hull, reducing blank margins near plot edges. If None, padding is inferred from interpolation_padding_cells and the regular grid spacing.
interpolation_padding_cellsfloat, default: 2.0: Number of regular-grid cells used as automatic interpolation padding.
min_valid_fractionfloat, default: 0.02: Minimum fraction of valid interpolated grid points required before plotting.
max_triangle_edgefloat, optional: Maximum accepted source-cell separation for interpolation support. Longer source triangles are masked when a triangulation-based cache path is used.
use_triangulation_cachebool, default: True: If True, cache geometry-only interpolation metadata for repeated calls on the same ICON mesh and grid.
transformcartopy.crs.CRS, optional: Coordinate reference system of the input coordinates for Cartopy axes.
titlestr, optional: Axes title. If None, use a default streamline title.
**streamplot_kwargs: Additional keyword arguments passed to Axes.streamplot.

Returns¶

matplotlib.streamplot.StreamplotSet: Streamplot set returned by Axes.streamplot.

ICON Cell-centered streamplots

easyclimate.plot.icon.plot_cell_triangular(ds, da, *, ax=None, transform=None, lon_min=None, lon_max=None, lat_min=None, lat_max=None, auto_extent=True, extent_margin=0.05, cell_margin=0.05, global_plot=False, center_lon=None, input_radians=True, skip_large_lon_jump=True, max_polygon_lon_span=180.0, cmap=None, vmin=None, vmax=None, symmetric=False, percentile=98, edgecolor='none', linewidth=0.0, add_colorbar=True, cbar_kwargs=None, title=None, xlabel='Longitude', ylabel='Latitude', aspect='auto', lon_name_cell='clon', lat_name_cell='clat', lon_bnds_name='clon_bnds', lat_bnds_name='clat_bnds')¶

Plot ICON cell-centered scalar data on native triangular cells.

Parameters¶

dsxarray.Dataset: ICON dataset containing cell centers and triangular cell bounds.
daxarray.DataArray or numpy.ndarray: Cell-centered scalar values on ncells. Select time and vertical dimensions before calling, for example ds["temp"].isel(time=0, plev=0).
axmatplotlib.axes.Axes, optional: Axes on which to draw. By default, use the current axes.
transformcartopy.crs.CRS, optional: Coordinate reference system of the input coordinates for Cartopy axes.
lon_min, lon_max, lat_min, lat_maxfloat, optional: Plot extent in degrees. Cross-dateline longitude windows are supported.
auto_extentbool, default: True: If True and no explicit extent is supplied, infer the extent from valid cell centers.
extent_marginfloat, default: 0.05: Fractional margin added to the automatically inferred extent.
cell_marginfloat, default: 0.05: Fractional padding used when selecting triangles near the visible extent.
global_plotbool, default: False: If True, draw a global extent centered on center_lon.
center_lonfloat, optional: Longitude center used for wrapping. If None, infer it from the extent or valid cell centers.
input_radiansbool, default: True: If True, ICON longitude and latitude variables are interpreted as radians and converted to degrees.
skip_large_lon_jumpbool, default: True: If True, skip triangles with very large wrapped longitude spans.
max_polygon_lon_spanfloat, default: 180.0: Maximum accepted wrapped triangle longitude span in degrees.
cmapstr or matplotlib.colors.Colormap, optional: Colormap used for triangle values.
vmin, vmaxfloat, optional: Color limits. If omitted, infer them from selected values.
symmetricbool, default: False: If True, infer symmetric color limits around zero.
percentilefloat, default: 98: Percentile used for automatic color-limit inference.
edgecolor, linewidth: Polygon edge style passed to matplotlib.collections.PolyCollection.
add_colorbarbool, default: True: If True, add a colorbar for the polygon collection.
cbar_kwargsdict, optional: Keyword arguments passed to Figure.colorbar.
titlestr, optional: Axes title. If None, use the data long name.
xlabel, ylabelstr: Axis labels used for plain Matplotlib axes.
aspectstr or float, default: “auto”: Aspect setting used for plain Matplotlib axes.
lon_name_cell, lat_name_cell, lon_bnds_name, lat_bnds_namestr: ICON coordinate and triangular-bound variable names.

Returns¶

matplotlib.collections.PolyCollection: Polygon collection added to the axes.

ICON Cell-centered triangular plots

easyclimate.plot.icon.plot_triangular_grid(ds, *, lon_min=None, lon_max=None, lat_min=None, lat_max=None, ax=None, transform=None, auto_extent=True, extent_margin=0.05, cell_margin=0.05, global_plot=False, center_lon=None, input_radians=True, skip_large_lon_jump=True, max_polygon_lon_span=180.0, lon_name_cell='clon', lat_name_cell='clat', lon_bnds_name='clon_bnds', lat_bnds_name='clat_bnds', deduplicate_edges=True, project_to_map=None, **linekwargs)¶

Plot ICON native triangular mesh edges.

Parameters¶

dsxarray.Dataset: ICON dataset containing triangular cell bounds.
lon_min, lon_max, lat_min, lat_maxfloat, optional: Optional plot extent in degrees. Cross-dateline longitude windows are supported.
axmatplotlib.axes.Axes, optional: Axes on which to draw. By default, use the current axes.
transformcartopy.crs.CRS, optional: Coordinate reference system of the input coordinates for Cartopy axes.
auto_extentbool, default: True: If True and no explicit extent is supplied, infer the extent from ICON cell centers.
extent_marginfloat, default: 0.05: Fractional margin added to the automatically inferred extent.
cell_marginfloat, default: 0.05: Fractional padding used when selecting triangles near the visible extent.
global_plotbool, default: False: If True, draw a global extent centered on center_lon.
center_lonfloat, optional: Longitude center used for wrapping. If None, infer it from the extent or valid cell centers.
input_radiansbool, default: True: If True, ICON longitude and latitude variables are interpreted as radians and converted to degrees.
skip_large_lon_jumpbool, default: True: If True, skip triangles with very large wrapped longitude spans.
max_polygon_lon_spanfloat, default: 180.0: Maximum accepted wrapped triangle longitude span in degrees.
lon_name_cell, lat_name_cell, lon_bnds_name, lat_bnds_namestr: ICON coordinate and triangular-bound variable names.
deduplicate_edgesbool, default: True: If True, remove duplicate shared cell edges before drawing.
project_to_mapbool or {“force”}, optional: If True or None on Cartopy axes, use the fast endpoint-projection path only for global-scale plots and use Cartopy’s exact path transform for regional plots. If False, always let Cartopy transform each path itself. If “force”, always project all edge endpoints to the target map projection in one vectorized operation before creating the collection. The forced path avoids Cartopy’s per-path Shapely projection overhead, but may differ from Cartopy’s exact transform on regional projections.
**linekwargs: Additional keyword arguments passed to matplotlib.collections.LineCollection.

Returns¶

matplotlib.collections.LineCollection: Line collection containing selected ICON triangular mesh edges.

ICON/Triangular grid