Scatter plots

scatter is the general-purpose method for plotting data values as coloured points at arbitrary (x, y) locations. It is the underlying method called by both point_cloud (for gridded data coloured by value) and grid_points (for grid centroid locations only).

Use scatter directly when:

• your data has explicit coordinate variables that don’t match earthkit-plots’ auto-detection (e.g. custom column names in a netCDF),

• you are plotting station or observation data that isn’t on any regular grid,

• you want full control over which variable provides x, y and z (value) independently.

All standard matplotlib scatter keyword arguments (s, marker, alpha, edgecolors, etc.) are accepted.

Example: maritime observation temperatures

We load a netCDF file of MADIS maritime surface observations. The file contains longitude, latitude and temperature as separate variables, which we pass explicitly to scatter.

import earthkit.data as ekd

import earthkit.plots as ekp

obs = ekd.from_source(
    "url",
    "https://get.ecmwf.int/repository/test-data/metview/gallery/madis-maritime.nc",
)

style = ekp.styles.Style(
    colors="Spectral_r",
    levels=range(0, 30, 2),
    units="celsius",
    extend="both",
)

chart = ekp.Map(domain=[-145, -70, 10, 75])

chart.scatter(
    obs,
    x="longitude",
    y="latitude",
    z="temperature",
    metadata={"units": "K"},
    style=style,
    s=8,
)

chart.coastlines()
chart.gridlines()
chart.legend()
chart.title("Maritime surface temperatures")

chart.show()

Controlling point appearance

Point size, marker shape, transparency and edge colour can all be set via matplotlib kwargs.

figure = ekp.Figure(rows=1, columns=2, domain=[-145, -70, 10, 75])

# Small, semi-transparent circles
ax = figure.add_map()
ax.scatter(
    obs,
    x="longitude",
    y="latitude",
    z="temperature",
    metadata={"units": "K"},
    style=style,
    s=5,
    alpha=0.5,
)
ax.title("s=5, alpha=0.5")

# Larger squares with black edges
ax = figure.add_map()
ax.scatter(
    obs,
    x="longitude",
    y="latitude",
    z="temperature",
    metadata={"units": "K"},
    style=style,
    s=30,
    marker="s",
    edgecolors="black",
    linewidths=0.3,
)
ax.title("marker='s', edgecolors='black'")

figure.coastlines()
figure.legend(location="right")

figure.show()

Scatter on a gridded dataset

scatter also works on structured gridded data. When the coordinate names are standard (latitude/longitude), earthkit-plots can detect them automatically — but you can also supply them explicitly.

grid_data = ekd.from_source("sample", "healpix-h128-nested-2t.grib")

grid_style = ekp.styles.Style(
    colors="Spectral_r",
    levels=range(-10, 35, 5),
    units="celsius",
    extend="both",
)

chart = ekp.Map(domain="Europe")

chart.scatter(grid_data, style=grid_style, s=3)

chart.coastlines()
chart.gridlines()
chart.legend()
chart.title()

chart.show()

scatter vs. point_cloud

point_cloud is a thin convenience wrapper around scatter that applies the @schema.point_cloud defaults (such as auto-style). For gridded data with standard coordinates, the two are equivalent; for observation data with custom coordinate names, use scatter with explicit x, y and z arguments.

figure = ekp.Figure(rows=1, columns=2, domain="Europe")

ax = figure.add_map()
ax.scatter(grid_data, style=grid_style, s=4)
ax.title("scatter")

ax = figure.add_map()
ax.point_cloud(grid_data, style=grid_style, s=4)
ax.title("point_cloud")

figure.coastlines()
figure.legend(location="right")

figure.show()