The plot() function#

healpix_plot.plot() is the main entry point of the library. It resamples HEALPix data onto a regular pixel grid and renders it with Matplotlib and Cartopy.

plot() returns a matplotlib.image.AxesImage (the mappable). Use .axes to access the underlying Axes object.

Parameter	Description
`cell_ids`	`numpy.ndarray` of cell ids describing spatial positions.
`data`	1-D array for scalar data (color-mapped), or 2-D array of shape `(N, 3)` / `(N, 4)` for RGB / RGBA.
`healpix_grid`	A `HealpixGrid` instance (or equivalent dict).
`sampling_grid`	Target raster resolution and extent. Pass a dict such as `{"shape": 1024}`; missing `center` / `resolution` are inferred from the data.
`projection`	A Cartopy CRS name (e.g. `"Mollweide"`) or an actual CRS object. Unknown names raise a `ValueError`.
`agg`	Aggregation function applied when `cell_ids` contains duplicates before resampling. Accepted values: `"mean"` (default), `"median"`, `"std"`, `"var"`, `"min"`, `"max"`, `"first"`, `"last"`.
`interpolation`	Resampling method. `"nearest"` (default and only implemented). `"bilinear"` is accepted by the API but raises `NotImplementedError`.
`background_value`	Fill value for grid points with no matching cell id. Default: `numpy.nan`.
`view`	Optional `(xmin, xmax, ymin, ymax)` tuple defining the displayed extent, passed to `ax.set_extent()`. Ignored when the full sphere is being plotted.
`rgb_clip`	`(min, max)` tuple used to clip RGB/RGBA `data` before display. Default: `(0.0, 1.0)`. Ignored for scalar (color-mapped) data.
`ax`	An existing Cartopy GeoAxes to draw on — see Plot on an existing axis below for the exact requirement. If omitted, a new figure is created using `projection`.
`title`	Optional string title for the axes.
`cmap`	Colormap (name or `Colormap` object). Default: `"viridis"`.
`vmin`, `vmax`	Scalar data range for colour normalisation.
`norm`	A `matplotlib.colors.Normalize` instance for finer colour control.
`colorbar`	`True` to add a colorbar, or a dict of kwargs forwarded to `figure.colorbar()`. Default: `False`.
`axis_labels`	`None` (default, uses `"Longitude"` / `"Latitude"`), a dict with `"x"` / `"y"` keys, or `"none"` to suppress labels entirely.

Minimal call#

healpix_plot.plot(
    cell_ids,  # 1-D array of HEALPix cell IDs (uint64)
    data,  # 1-D scalar array, or (N, 3)/(N, 4) for RGB/RGBA
    healpix_grid=grid,  # HealpixGrid object (or dict)
    sampling_grid={"shape": 1024},
)

Interpolation#

healpix_plot.plot(..., interpolation="nearest")  # default
healpix_plot.plot(
    ..., interpolation="bilinear"
)  # smoother, better for continuous fields

Plot on an existing axis#

When you pass ax, the projection parameter is ignored — plot() draws directly onto the axis you give it instead of creating one.

Important

The axis you pass as ax must be a Cartopy GeoAxes, i.e. created with subplot_kw={"projection": <a cartopy CRS>}. plot() calls Cartopy-only methods on it internally (ax.set_extent(), ax.set_global()). A plain matplotlib.axes.Axes — what you get from plt.subplots() without subplot_kw — does not have these methods and raises:

AttributeError: 'Axes' object has no attribute 'set_extent'

This is easy to miss when you go from a single plot to a grid of subplots, since subplot_kw has to be repeated on every plt.subplots() call that will host a plot() call.

import matplotlib.pyplot as plt
import cartopy.crs as ccrs

fig, ax = plt.subplots(subplot_kw={"projection": ccrs.Robinson()})
healpix_plot.plot(..., ax=ax)
plt.show()

Multiple panels side by side#

subplot_kw applies to every axis plt.subplots() creates, including when you ask for several panels at once — pass ax=axes[0], ax=axes[1], etc. to place one plot() call per panel:

import matplotlib.pyplot as plt
import cartopy.crs as ccrs

fig, (ax1, ax2) = plt.subplots(
    1,
    2,
    subplot_kw={"projection": ccrs.Mollweide()},  # required on every axis
    figsize=(16, 8),
    layout="constrained",
)

m1 = healpix_plot.plot(
    cell_ids_a,
    data_a,
    healpix_grid=grid,
    sampling_grid={"shape": 512},
    ax=ax1,
    title="A",
    colorbar=True,
)
m2 = healpix_plot.plot(
    cell_ids_b,
    data_b,
    healpix_grid=grid,
    sampling_grid={"shape": 512},
    ax=ax2,
    title="B",
    colorbar=True,
)

plt.show()

Each axis can even use a different projection, since it is set per-axis via subplot_kw and not by plot() itself when ax is given.

Title and axis labels#

healpix_plot.plot(
    ...,
    title="Surface temperature",
    axis_labels={"x": "Longitude", "y": "Latitude"},
)
healpix_plot.plot(..., axis_labels="none")  # hide labels

RGB / RGBA data#

plot() accepts multi-band data directly. If data has shape (N, 3) (RGB) or (N, 4) (RGBA), the values are composited per-pixel rather than colour-mapped. Colourmap parameters (cmap, vmin, vmax, norm) are ignored in this mode. Values are clipped to rgb_clip (default (0.0, 1.0)) before display.

rgb = np.stack([r, g, b], axis=1)  # shape (N, 3)
healpix_plot.plot(
    cell_ids,
    rgb,
    healpix_grid=healpix_grid,
    sampling_grid={"shape": 1024},
    rgb_clip=(0.0, 1.0),
)