Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

UXarray for Basic HEALPix Statistics & Visualization

HEALPix logo

UXarray for Basic HEALPix Statistics & Visualization

In this section, you’ll learn:

  • Utilizing intake to open a HEALPix data catalog

  • Using the uxarray package to look at basic statistics over HEALPix data

  • Using UXarray plotting functionality on HEALPix data

Prerequisites

ConceptsImportanceNotes
UXarrayNecessary
HEALPix overviewNecessary

Time to learn: 30 minutes


Open data catalog

Let us use the online data catalog from the WCRP’s Digital Earths Global Hackathon 2025’s catalog repository using intake and read the output of the ICON simulation run ngc4008, which is stored in the HEALPix format:

/home/runner/micromamba/envs/healpix-cookbook-dev2/lib/python3.14/site-packages/intake/catalog/utils.py:173: UserWarning: Shell command not executed due to getshell=False
  warnings.warn("Shell command not executed due to getshell=False")
/home/runner/micromamba/envs/healpix-cookbook-dev2/lib/python3.14/site-packages/intake/catalog/utils.py:182: UserWarning: Shell command not executed due to getshell=False
  warnings.warn("Shell command not executed due to getshell=False")

We will be looking at two resolution levels, one is the coarsest zoom level of 0, which is the default in this model run, and the other is a finer one at the zoom level of 7:

Create UXarray Datasets from HEALPix

Now let us use those xarray.Datasets from the model run to open unstructured grid-aware uxarray.UxDataset:

CPU times: user 300 ms, sys: 17.8 ms, total: 318 ms
Wall time: 320 ms
Loading...

HEALPix basic stats using UXarray

Let us look at the global and Boulder, CO, USA air temperature averages for the dataset. Data spans from 2020 to 2050, so let us also consider slicing it to have a 3-year interval between 2020 and 2023, which would also give us similar results to that with easy.gems in the previous section.

Mesh face containing Boulder’s coords

We can find face(s) containing a given point with uxarray conveniently as follows:

CPU times: user 3.58 s, sys: 57.4 ms, total: 3.64 s
Wall time: 3.61 s
[2]

Data variables of interest

In order to use in the rest of the analyses, we can grab data variables, in theuxarray.UxDataArray type, from the dataset as follows:

Global and Boulder’s temperature averages

In order to get a line plot of our UXarray.UxDataset objects’ 1-dimensional temperature variables, we will convert them to xarray and call the default plot function because UXarray’s default plotting functions are all dedicated to grid-topology aware visualizations:

Loading...
CPU times: user 44.2 ms, sys: 13.3 ms, total: 57.5 ms
Wall time: 1.14 s
<Figure size 640x480 with 1 Axes>

Data plotting with UXarray

UXarray provides several built-in plotting functions to visualize unstructured grids, which can also be applied to HEALPix grids in the same interface:

Let us first look into interactive plots with the bokeh backend (i.e. UXarray’s plotting functions have a backend parameter that defaults to “bokeh”, and it can also accept “matplotlib”)

Global plots

Let us first plot the global temperature (at the first timestep for simplicity), using the default backend, bokeh, of UXarray’s visualization API to create an interactive plot:

Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
CPU times: user 6.44 s, sys: 197 ms, total: 6.64 s
Wall time: 7.16 s
WARNING:param.GeoOverlayPlot00487: Due to internal constraints, when aspect and width/height is set, the bokeh backend uses those values as frame_width/frame_height instead. This ensures the aspect is respected, but means that the plot might be slightly larger than anticipated. Set the frame_width/frame_height explicitly to suppress this warning.
Loading...

Now, let us create the same plot, using matplotlib as the backend:

Loading...
Loading...
Loading...
Loading...
Loading...
CPU times: user 336 ms, sys: 6.96 ms, total: 343 ms
Wall time: 868 ms
Loading...

Regional subsets (Not only for plotting but also for analysis)

When a region on the globe is of interest, UXarray provides subsetting functions, which return new regional grids that can then be used in the same way a global grid is plotted.

Let us look into the USA map using the Boulder, CO, USA coords we had used before for simplicity:

Subsetting uxds_fine into a new UxDataset using a “bounding box” around Boulder, CO first:

CPU times: user 23.3 s, sys: 138 ms, total: 23.5 s
Wall time: 23.5 s

If we check the global and regional subset’s average temperature at the first timestep, we can see the difference:

Global temperature average:  286.30957  K
Regional subset's temperature average:  nan  K

Now, let us plot the regional subset UxDataset:

CPU times: user 3.27 ms, sys: 26 μs, total: 3.3 ms
Wall time: 2.47 ms
---------------------------------------------------------------------------
ValueError                                Traceback (most recent call last)
Cell In[14], line 1
----> 1 get_ipython().run_cell_magic('time', '', 'projection = ccrs.Robinson(central_longitude=boulder_lon)\n\nuxda_fine_subset.plot(\n    projection=projection,\n    cmap="inferno",\n    features=["borders", "coastline"],\n    title="Boulder temperature",\n    width=1100,\n)\n')

File <timed exec>:3
      1 'Could not get source, probably due dynamically evaluated source code.'

File ~/micromamba/envs/healpix-cookbook-dev2/lib/python3.14/site-packages/uxarray/plot/accessor.py:386, in UxDataArrayPlotAccessor.__call__(self, **kwargs)
    383 def __call__(self, **kwargs) -> Any:
    384     if self._uxda._face_centered():
    385         # polygons for face-centered data
--> 386         return self.polygons(**kwargs)
    387     else:
    388         # points for node and edge centered data
    389         return self.points(**kwargs)

File ~/micromamba/envs/healpix-cookbook-dev2/lib/python3.14/site-packages/uxarray/plot/accessor.py:474, in UxDataArrayPlotAccessor.polygons(self, periodic_elements, backend, engine, rasterize, dynamic, projection, xlabel, ylabel, *args, **kwargs)
    471 if "clabel" not in kwargs and self._uxda.name is not None:
    472     kwargs["clabel"] = self._uxda.name
--> 474 gdf = self._uxda.to_geodataframe(
    475     periodic_elements=periodic_elements,
    476     projection=kwargs.get("projection"),
    477     engine=engine,
    478     project=False,
    479 )
    481 # import datashader  # no need to import explicitly, but gets used below when rasterize=True.
    482 # (commented here for future reference, since datashader appears in uxarray dependency list,
    483 #    but it isn't imported explicitly anywhere in uxarray. For more details see PR #1548.)
    484 return gdf.hvplot.polygons(
    485     c=self._uxda.name if self._uxda.name is not None else "var",
    486     rasterize=rasterize,
   (...)    491     **kwargs,
    492 )

File ~/micromamba/envs/healpix-cookbook-dev2/lib/python3.14/site-packages/uxarray/core/dataarray.py:304, in UxDataArray.to_geodataframe(self, periodic_elements, projection, cache, override, engine, project)
    299     raise DimensionError(
    300         f"to_geodataframe() expected 1D data, got {self.ndim}D data with dims={self.dims}."
    301     )
    303 if self._face_centered():
--> 304     gdf, non_nan_polygon_indices = self.uxgrid.to_geodataframe(
    305         periodic_elements=periodic_elements,
    306         projection=projection,
    307         project=project,
    308         cache=cache,
    309         override=override,
    310         return_non_nan_polygon_indices=True,
    311         engine=engine,
    312     )
    314     # set a default variable name if the data array is not named
    315     var_name = self.name if self.name is not None else "var"

File ~/micromamba/envs/healpix-cookbook-dev2/lib/python3.14/site-packages/uxarray/grid/grid.py:2614, in Grid.to_geodataframe(self, periodic_elements, projection, cache, override, engine, return_non_nan_polygon_indices, exclude_nan_polygons, project)
   2611         return self._gdf_cached_parameters["gdf"]
   2613 # construct a GeoDataFrame with the faces stored as polygons as the geometry
-> 2614 gdf, non_nan_polygon_indices = _grid_to_polygon_geodataframe(
   2615     self, periodic_elements, projection, project, engine
   2616 )
   2618 if exclude_nan_polygons and non_nan_polygon_indices is not None:
   2619     # exclude any polygons that contain NaN values
   2620     gdf = GeoDataFrame({"geometry": gdf["geometry"][non_nan_polygon_indices]})

File ~/micromamba/envs/healpix-cookbook-dev2/lib/python3.14/site-packages/uxarray/grid/geometry.py:244, in _grid_to_polygon_geodataframe(grid, periodic_elements, projection, project, engine)
    241 grid._gdf_cached_parameters["antimeridian_face_indices"] = antimeridian_face_indices
    243 if periodic_elements == "split":
--> 244     gdf = _build_geodataframe_with_antimeridian(
    245         polygon_shells,
    246         projected_polygon_shells,
    247         antimeridian_face_indices,
    248         engine=engine,
    249     )
    250 elif periodic_elements == "ignore":
    251     if engine == "geopandas":
    252         # create a geopandas.GeoDataFrame

File ~/micromamba/envs/healpix-cookbook-dev2/lib/python3.14/site-packages/uxarray/grid/geometry.py:343, in _build_geodataframe_with_antimeridian(polygon_shells, projected_polygon_shells, antimeridian_face_indices, engine)
    330 else:
    331     # Create a spatialpandas.GeoDataFrame
    332     # (MultiPolygonArray handles cases where polygons are split across the antimeridian.
   (...)    336     # the fact that only the antimeridian-crossing faces actually need any adjustment.
    337     # The _build_multipolygon_array() helper provides a more efficient implementation.)
    338     shells = (
    339         projected_polygon_shells
    340         if projected_polygon_shells is not None
    341         else polygon_shells
    342     )
--> 343     geometry = _build_multipolygon_array(
    344         polygons, shells, antimeridian_face_indices
    345     )
    346     gdf = spatialpandas.GeoDataFrame({"geometry": geometry})
    348 return gdf

File ~/micromamba/envs/healpix-cookbook-dev2/lib/python3.14/site-packages/uxarray/grid/geometry.py:397, in _build_multipolygon_array(shapely_polygons, shells, antimeridian_face_indices)
    395 # (n_face, n_nodes, 2) -> (n_face, n_nodes * 2), i.e. x0, y0, x1, y1, ...
    396 n_face = shells.shape[0]
--> 397 flat_rings = shells.reshape(n_face, -1)
    399 # MultiPolygonArray input: multipolygon -> polygon -> ring -> flat coords.
    400 # Every uncorrected face is one multipolygon with one polygon with one ring.
    401 data = [[[ring]] for ring in flat_rings]

ValueError: cannot reshape array of size 0 into shape (0,newaxis)

Grid topology exploration

Exploring the grid topology may be needed sometimes, and UXarray provides functionality to do so, both numerically and visually. Each UxDataset or UxDataArray has their associated Grid object that has all the information such as spherical and cartesian coordinates, connectives, dimensions, etc. about the topology this data belongs to. This Grid object can be explored as follows:

There might be times that the user wants to open a standalone Grid object for a HEALPix grid (or any other unstructured grids supported by UXarray) without accessing the data yet. Let’s create the coarsest HEALPix grid as follows:

Let’s investigate how a HEALPix grid looks like over the poles. We can do things by selecting an Orthographic projection and setting a Geodetic source projection. This allows to better approximates the true HEALPix structured compared to the defaut PlateCaree projection.

Let’s chose another projection.

The grid structure here is approximated. While the boundary between each pixel is easily known in HEALPix workflows, UXarray represents the boundaries as a Great Circle Arc (GCA) due to the requirement of having explicit connectivity information, which is different than HEALPix boundaries and leads to minor differences in the computed plots and computations.

Now that we’ve looked at the grid structure, we can also apply the same principles to our data plotting.

What is next?

The next section will provide an UXarray workflow that loads in and analyzes & visualizes HEALPix data.