Plotting#

The Skyborn plotting module provides specialized visualization functions for atmospheric and climate data.

Plotting Utilities#

add_equal_axes(ax, loc, pad, width)[source]#

Add a new Axes with equal height or width next to the original Axes and return that object.

Parameters:

ax (Axes or array_like of Axes) – The original Axes, or can be an array of Axes.
loc ({'left', 'right', 'bottom', 'top'}) – Position of the new Axes relative to the old Axes.
pad (float) – Spacing between the new Axes and the old Axes.
width (float) – When loc=’left’ or ‘right’, width represents the width of the new Axes. When loc=’bottom’ or ‘top’, width represents the height of the new Axes.

Returns:

ax_new – New Axes object.

Return type:

Axes

createFigure(figsize=(12, 8), dpi=300, subplotAdj=None, **kwargs)[source]#

Curly Vector Plots#

curly_vector(*args, **kwargs)[source]#

Plot NCL-like curly vectors from arrays or an xarray dataset.

Parameters:

ds (xarray.Dataset, optional) – Dataset source for the dataset-style call form. When ds is used as the first positional argument, x, y, u, and v must be the corresponding coordinate and variable names inside that dataset.
ax (matplotlib.axes.Axes, optional) – Target axes for the vector plot. If omitted, matplotlib.pyplot.gca() is used.
x (array-like or hashable) –
Coordinate definition for the vector field.

For array-style calls, these may be 1D or 2D coordinate arrays. If 2D, they should describe a meshgrid-like layout matching the vector field. For dataset-style calls, they are the coordinate names inside ds.
y (array-like or hashable) –
Coordinate definition for the vector field.

For array-style calls, these may be 1D or 2D coordinate arrays. If 2D, they should describe a meshgrid-like layout matching the vector field. For dataset-style calls, they are the coordinate names inside ds.
u (array-like or hashable) – Vector components. For array-style calls, these are 2D numeric arrays aligned with the supplied coordinates. For dataset-style calls, they are variable names inside ds.
v (array-like or hashable) – Vector components. For array-style calls, these are 2D numeric arrays aligned with the supplied coordinates. For dataset-style calls, they are variable names inside ds.
density (float or tuple of float, optional) – Controls the closeness of the rendered curly vectors. As in the low-level engine, density=1 corresponds to the default NCL-like sampling density, and a tuple (density_x, density_y) can be used for anisotropic spacing.
linewidth (float or 2D array, optional) – Width of the curved vector shafts. A field array must match the vector grid shape.
linewidths (float or 2D array, optional) – Matplotlib quiver-style alias for linewidth.
color (color-like or 2D array, optional) – Shaft color. If a 2D scalar field is supplied, Skyborn maps it through cmap and norm.
c (color-like or 2D array, optional) – Matplotlib-style alias for color.
cmap – Colormap and normalization controls used when color/c is a scalar field.
norm – Colormap and normalization controls used when color/c is a scalar field.
vmin (float, optional) – Lower and upper normalization bounds used when color/c is a scalar field and norm is omitted.
vmax (float, optional) – Lower and upper normalization bounds used when color/c is a scalar field and norm is omitted.
alpha (float, optional) – Matplotlib artist alpha applied to both the curved shafts and the arrow heads.
facecolor (color-like, optional) – Explicit arrow-head fill and edge colors. When omitted, the resolved shaft color is reused.
edgecolor (color-like, optional) – Explicit arrow-head fill and edge colors. When omitted, the resolved shaft color is reused.
facecolors (color-like, optional) – Matplotlib-style aliases for facecolor and edgecolor.
edgecolors (color-like, optional) – Matplotlib-style aliases for facecolor and edgecolor.
rasterized (bool, optional) – Whether to rasterize the generated curly-vector artists when exporting to vector formats such as PDF or SVG.
arrowsize (float, optional) – Scaling factor for the arrow size.
arrowstyle (str, optional) – Supported arrow-head style. Use "->" for the open NCL-like line head or "-|>" for a filled triangular head.
transform (optional) – Coordinate transformation for the plot. Standard Matplotlib transforms are forwarded directly. Cartopy CRS-like objects are normalized internally.
zorder (float, optional) – Z-order of the curved shafts and arrow heads.
start_points ((N, 2) array-like, optional) – Explicit seed points for the curly-vector glyphs in data coordinates.
integration_direction ({'forward', 'backward', 'both'}, optional) – Integrate the glyph shape in the forward, backward, or both directions.
grains (int, optional) – Number of grains used during streamline-style integration.
broken_streamlines (bool, optional) – If False, forces traces to continue until they leave the domain. If True, traces may terminate early when they come too close to another glyph.
anchor ({'tail', 'center', 'head'} or None, optional) – Anchor point for the NCL-like curved-glyph renderer. If omitted, the anchor is inferred from integration_direction.
pivot ({'tail', 'mid', 'middle', 'tip'} or None, optional) – Matplotlib quiver-style alias for anchor.
ref_magnitude (float, optional) – Reference magnitude used when mapping a physical vector magnitude to a display-space glyph length. If omitted, the maximum field magnitude is used.
ref_length (float, optional) – Reference glyph length as a fraction of the axes width. If omitted, a NCL-like default scaled by arrowsize is used.
min_frac_length (float, optional) – Minimum glyph length as a fraction of the reference length.
min_distance (float, optional) – Minimum glyph-center spacing as a fraction of the axes width. If omitted, it is inferred from density.
ncl_preset ({None, 'profile'}, optional) – Optional preset override for NCL-like glyph tuning. In most cases you can leave this as None and let Skyborn choose the default behavior.
regrid_shape (int or (int, int), optional) – Target shape for projection-aware Cartopy regridding. This requires a Cartopy CRS-like transform and a GeoAxes with a projection.
curvilinear_regrid_shape (int or (int, int), optional) – Target shape used when the source coordinates describe a curvilinear grid. If omitted, Skyborn infers a conservative default from the source grid and density.
target_extent (tuple of float, optional) – Explicit (xmin, xmax, ymin, ymax) target extent used during projection-aware regridding.
isel (mapping or tuple, optional) – Dataset-only selection forwarded before extracting x, y, u, and v from ds.
**kwargs (Any) – Additional style and artist options supported by the public wrapper.
args (Any)
**kwargs

Returns:

Container object with attributes

lines: .LineCollection of the curved vector shafts.
arrows: tuple of arrow-head artists added to the axes. Open arrow styles use line segments only and may therefore return an empty tuple.

Return type:

CurlyVectorPlotSet

Notes

Supported call styles

curly_vector(ax, x, y, u, v, ...)
curly_vector(x, y, u, v, ..., ax=ax)
curly_vector(x, y, u, v, ...)
curly_vector(ds, x="lon", y="lat", u="u", v="v", ax=ax, ...)

The recommended module-oriented import path for the vector feature family is skyborn.plot.vector:

from skyborn.plot.vector import curly_vector, curly_vector_key

The package-level names skyborn.plot.curly_vector and skyborn.plot.curly_vector_key remain available and forward to the same public behavior.

The same skyborn.plot.curly_vector entry point supports both call styles:

curly_vector(ax, x, y, u, v, ...) for direct NumPy / Matplotlib input
curly_vector(ds, x="lon", y="lat", u="u", v="v", ax=ax, ...) for xarray dataset input

curly_vector_key(*args, **kwargs)[source]#

Add an NCL-like reference-vector annotation to axes.

Parameters:

ax (matplotlib.axes.Axes, optional) – Target axes for the reference key. If omitted, matplotlib.pyplot.gca() is used.
curly_vector_set (CurlyVectorPlotSet) – Plot result returned by curly_vector(). The key reads glyph scale and reference-length information from this object.
U (float, optional) – Reference vector magnitude to display in the key. Defaults to 2.0.
units (str, optional) – Units label displayed with the reference magnitude. Defaults to "m/s".
label (str, optional) – Optional custom label text for the annotation.
description (str, optional) – Optional secondary description line shown with the reference key.
width (float, optional) – Size of the reference-key box in axes coordinates.
height (float, optional) – Size of the reference-key box in axes coordinates.
loc ({"lower left", "lower right", "upper left", "upper right"}, optional) – Preset box location used when explicit x/y axes coordinates are not provided.
x (float, optional) – Explicit box anchor position in axes coordinates. These two parameters must be provided together and override loc.
y (float, optional) – Explicit box anchor position in axes coordinates. These two parameters must be provided together and override loc.
labelpos ({"N", "S", "E", "W"}, optional) – Relative label placement around the reference arrow.
max_arrow_length (float, optional) – Maximum arrow length used by the fallback reference-arrow geometry.
arrow_props (dict, optional) – Styling dictionaries forwarded to the low-level arrow, frame, and text artists.
patch_props (dict, optional) – Styling dictionaries forwarded to the low-level arrow, frame, and text artists.
text_props (dict, optional) – Styling dictionaries forwarded to the low-level arrow, frame, and text artists.
padding (float, optional) – Internal padding between the frame and the reference-arrow/text layout.
margin (float, optional) – Margin from the axes edge when loc is used.
reference_speed (float, optional) – Fallback reference speed used when the plot set cannot provide a usable scale mapping.
center_label (bool, optional) – Whether to center the main label rather than using the default north/south/east/west placement logic.
frameon (bool, optional) – Whether to draw the surrounding reference-key frame.
show_description (bool, optional) – Whether to render the description text when one is available.
**kwargs (Any) – Additional keyword arguments forwarded to CurlyVectorKey.
args (Any)
**kwargs

Returns:

The reference-key artist added to the axes.

Return type:

CurlyVectorKey

Notes

Supported call styles

curly_vector_key(ax, curly_vector_set, U=2.0, ...)
curly_vector_key(curly_vector_set, U=2.0, ax=ax, ...)
curly_vector_key(curly_vector_set, ...)

Scatter Stippling#

scatter(*args, **kwargs)[source]#

Scatter points with optional NCL-style display-space thinning.

This is the public plotting entry point exposed by skyborn.plot. It keeps a Matplotlib-compatible calling convention while adding the display-space thinning workflow needed for gridded stippling use cases such as significance masks on map projections and vertical cross-sections.

Unlike a simple x[::step], y[::step] subsampling strategy, Skyborn first transforms candidate points into the current display geometry and then thins them there. That means the visible stipple density responds to the actual projection, axes aspect ratio, and panel extent seen by the user.

Supported call styles#

Matplotlib-style: scatter(ax, x, y, ...) scatter(x, y, ..., ax=ax) scatter(x, y, ...) scatter(x, y, s, c, ...)

param ax:

Target axes. If omitted, matplotlib.pyplot.gca() is used.

type ax:

matplotlib.axes.Axes, optional

param x:

Coordinate specification for the points to draw. Supported forms are:

paired 1D point coordinates, where x[i] and y[i] already describe one point each,
1D rectilinear grid axes, which are expanded internally with numpy.meshgrid when a gridded mask or style field is supplied,
or 2D meshgrid-like coordinate arrays.

type x:

array-like

param y:

Coordinate specification for the points to draw. Supported forms are:

paired 1D point coordinates, where x[i] and y[i] already describe one point each,
1D rectilinear grid axes, which are expanded internally with numpy.meshgrid when a gridded mask or style field is supplied,
or 2D meshgrid-like coordinate arrays.

type y:

array-like

param s:

Marker size passed through to matplotlib.axes.Axes.scatter. If an array is supplied, it may be defined on the full grid, on the masked candidate set, or on the already flattened point list.

type s:

scalar or array-like, optional

param c:

Marker color argument passed through to Axes.scatter. Array-like color fields follow the same subsetting rules as s.

type c:

color-like or array-like, optional

param color:

Compatibility alias for c. This is useful when matching plotting helpers that prefer the color= spelling while still preserving Matplotlib scatter semantics for numeric color fields.

type color:

color-like or array-like, optional

param linewidth:

Compatibility alias for linewidths.

type linewidth:

scalar or array-like, optional

param facecolor:

Compatibility alias for facecolors.

type facecolor:

color-like or array-like, optional

param edgecolor:

Compatibility alias for edgecolors.

type edgecolor:

color-like or array-like, optional

param linewidths:

Native Matplotlib scatter styling arguments. Array-like values follow the same retained-point subsetting rules as s and c.

param facecolors:

Native Matplotlib scatter styling arguments. Array-like values follow the same retained-point subsetting rules as s and c.

param edgecolors:

Native Matplotlib scatter styling arguments. Array-like values follow the same retained-point subsetting rules as s and c.

param vmin:

Colormap range controls forwarded to Axes.scatter.

type vmin:

float, optional

param vmax:

Colormap range controls forwarded to Axes.scatter.

type vmax:

float, optional

param where:

Candidate-selection mask. Use only one of them. For gridded stippling, these are typically 2D boolean or numeric fields aligned with the input grid. Numeric masks follow NumPy truthiness, while NaN values are treated as invalid rather than truthy.

type where:

array-like, optional

param mask:

type mask:

array-like, optional

param density:

Relative stipple density. Larger values retain more points. When omitted, gridded inputs use the default NCL-style spacing rule and paired 1D points keep all points.

type density:

float, optional

param distance:

Explicit display-space thinning distance in normalized viewport units. Use this when an exact spacing threshold is preferred over the relative density control.

type distance:

float, optional

param min_distance:

Backward-compatible alias for distance.

type min_distance:

float, optional

param placement:

Controls where gridded stipple candidates are generated before thinning. "points" keeps the original node-based behavior. "cells" fills the selected grid cells with interior candidates so dots can appear between coordinate centers. The default "auto" follows the NCL polymarker/scatter convention and uses "points"; request "cells" explicitly when you want fill-like stippling inside selected grid cells.

type placement:

{“auto”, “points”, “cells”}, optional

param transform:

Source coordinate transform. Standard Matplotlib transforms are passed through directly. Cartopy CRS-like objects are converted to the matching Matplotlib transform automatically.

type transform:

optional

param zorder:

Matplotlib z-order of the generated scatter collection.

type zorder:

float, optional

param **kwargs:

Additional keyword arguments forwarded to Axes.scatter after any array-like values have been subset to the retained points.

returns:

The scatter collection returned by Axes.scatter.

rtype:

matplotlib.collections.PathCollection

Parameters:

args (Any)
kwargs (Any)

The same skyborn.plot.scatter entry point supports the standard Matplotlib-style call forms:

scatter(ax, x, y, ...)
scatter(x, y, ..., ax=ax)
scatter(x, y, ...)

For gridded significance stippling, pass 1D grid axes together with a 2D where or mask field. Skyborn expands the grid candidates and then applies NCL-style display-space thinning so dense lat-lon maps and latitude-pressure sections do not need manual [::step] tuning. In most cases, density is the only spacing control you need; distance is available when you want to override the retained-point spacing explicitly. For masked grids with inferable cell geometry, the default placement now fills the selected cells with interior candidates before thinning so month-lat, profile, and curvilinear-grid plots can place dots between coordinate centers. Use placement="points" when you explicitly want the older node-based behavior.

Example Usage#

import skyborn as skb
import matplotlib.pyplot as plt
import numpy as np
import xarray as xr
from skyborn.plot.vector import curly_vector

# Create figure with equal axes
fig, ax = plt.subplots()
ax_new = skb.plot.add_equal_axes(ax, 'right', 0.1, 0.2)

# Low-level array API
lon = np.linspace(-180, 180, 50)
lat = np.linspace(-90, 90, 25)
u = np.random.random((25, 50))
v = np.random.random((25, 50))

curly_vector(ax, lon, lat, u, v)

# Dataset wrapper API
ds = xr.Dataset(
    {"u": (("lat", "lon"), u), "v": (("lat", "lon"), v)},
    coords={"lon": lon, "lat": lat},
)
curly_vector(ds, x="lon", y="lat", u="u", v="v", ax=ax)

# Display-space-thinned stippling on a gridded significance mask
p = xr.DataArray(
    np.random.random((25, 50)),
    dims=("lat", "lon"),
    coords={"lon": lon, "lat": lat},
)
skb.plot.scatter(ax, lon, lat, where=p < 0.05, density=2, s=4, c="0.3")

# Vertical-profile stippling uses the same API
level = np.linspace(1000, 100, 12)
profile_sig = np.random.random((12, 25)) < 0.08
fig2, ax2 = plt.subplots()
skb.plot.scatter(ax2, lat, level, where=profile_sig, density=2, s=4, c="0.2")
ax2.invert_yaxis()

Visualization Examples#

The plotting module is designed for creating publication-quality atmospheric visualizations:

import skyborn as skb
import matplotlib.pyplot as plt
from skyborn.plot.vector import curly_vector

# Create figure
fig = skb.plot.createFigure(figsize=(12, 8), dpi=300)
ax = fig.add_subplot(111)

# Plot wind vectors from arrays
curly = curly_vector(ax, lon, lat, u_wind, v_wind)

# Add significance stippling from a gridded mask
stipple = skb.plot.scatter(ax, lon, lat, where=p_values < 0.05, density=2)

For complete visualization examples, see Gallery.

Plotting

Contents

Plotting#

Plotting Utilities#

Curly Vector Plots#

Scatter Stippling#

Supported call styles#

Example Usage#

Visualization Examples#