Grid Topology

No matter what analysis operations you are performing on the data, visualization of the geometric elements of an unstructured grid (i.e. nodes, edges) without any data mapped to them can always be useful for a number of reasons, including but not limited to understanding the mesh topology and diagnosing patterns or issues with or prior to data analysis (e.g. analyzing the mesh of a dynamical core prior to running a simulation).

UXarray provides convenient functionality to visualize these elements of the Grid object. Below we will introduce those functions, but let us do the initial setup first:

Setup

This setup handles the package imports and data loading.

Imports

import cartopy.crs as ccrs
import geoviews.feature as gf
import holoviews as hv
import uxarray as ux

Read in the data

# File paths
file_dir = "../../meshfiles/"

# We use 480km dataset in this example but there is also 120km dataset
# in the file directory that can be further explored
grid_filename = "oQU480.grid.nc"
data_filename = "oQU480.data.nc"

# A standalone grid can be opened for immediate visualization
ux_grid = ux.open_grid(file_dir + grid_filename)

# Visualization through a `UxDataset`'s associated grid, `uxds.uxgrid` is also possible.
uxds = ux.open_dataset(file_dir + grid_filename, file_dir + data_filename)

Important!

How to plot through Grid, UxDataset, or UxDataArray?

As the above ux_grid and uxds creation suggests, you may either have a UxDataset (or similarly UxDataArray), or a standalone Grid object. Visualization of the geometric elements of an unstructured grid is possible in all of these cases as follows (Through uxgrid accessor when it is a UxDataset or UxDataArray):
uxarray.Grid.plot.plotting_function()
uxarray.UxDataset.uxgrid.plot.plotting_function()
uxarray.UxDataArray.uxgrid.plot.plotting_function()

We will demonstrate plotting functions using the standalone ux_grid thorughout this notebook.

Plotting Edges

Plotting the edges of an Unstructured Grid gives us an immediate idea of what the actual mesh looks like since connected edges construct the faces of the grid. Because of this, edge visualization is considered as the default method for Grid topology visualization purposes, and the default plotting method uxarray.Grid.plot(), provides an edge plot as follows:

ux_grid.plot(
    title="Default Grid Plot Method",
    width=700,
    height=350,
)

Tip:

See also ux_grid.plot.mesh() and ux_grid.plot.edges() that would both create the same plot.

Tip:

Try xlim and ylim args with the above plot to plot a region of interest only, e.g. xlim=(-170, -50), ylim=(10, 80).

Using exclude_antimeridian

The default grid plot() method as well as mesh() and edges() can take in an optional argument called exclude_antimeridian, which generates the visualization with or without correcting polygons that cross at the antimeridian (± 180 longitude):

ux_grid.plot.mesh(
    exclude_antimeridian=True,
    title="Mesh - Exclude Antimeridian Polygons",
    width=700,
    height=350,
)

WARNING:param.main: exclude_antimeridian option not found for paths plot with bokeh; similar options include: []

Choosing a backend

Since all of our plotting methods are built around the Holoviews package, you can select between Matplotlib and Bokeh backends if desired (Bokeh is the default and is suggested). Let us have a quick look at a Matplotlib result as well:

ux_grid.plot.edges(
    backend="matplotlib", title="Edges - Matplotlib Backend", fig_size=300, aspect=2
)

WARNING:param.main: fig_size option not found for paths plot with matplotlib; similar options include: []

Plotting Nodes

The nodes (a.k.a. vertices in some unstructured mesh models) construct the corner points of faces (a.k.a. cells) in unstructured grids, hence they can also give an idea about the mesh geometry when visualized. Nodes can be visualized easily with UXarray as follows:

ux_grid.plot.nodes(size=1, title="Nodes", width=700, height=350)

Tip:

See also ux_grid.plot.node_coords() that would create the same plot.

Plotting Face and Edge Centers

In some cases, one might even want to visualize the center coordinates of the grid faces and edges. UXarray has functions to perform such visualizations as points:

ux_grid.plot.face_centers(size=1, title="Face Centers", width=700, height=350)

Tip:

See also ux_grid.plot.face_coords() that would create the same plot.

ux_grid.plot.edge_centers(size=1, title="Edge Centers", width=700, height=350)

Tip:

See also ux_grid.plot.edge_coords() that would create the same plot.

Putting All Together

A more meaningful visualization case could be bringing all of these plotting functions together in a single figure (This time, let’s use the uxds object to analyze its grid geometry):

(
    uxds.uxgrid.plot.edges(color="Black", line_dash="dashed", line_width=1)
    * uxds.uxgrid.plot.nodes(color="Red", size=1)
    * uxds.uxgrid.plot.face_centers(color="Blue", size=1)
    * uxds.uxgrid.plot.edge_centers(color="Green", size=1)
).opts(
    title="Node, Edge, & Face Coordinates",
    xlim=(-170, -50),
    ylim=(10, 80),
    width=700,
    height=350,
)

WARNING:param.main: line_dash option not found for paths plot with matplotlib; similar options include: ['linewidth']

WARNING:param.main: line_width option not found for paths plot with matplotlib; similar options include: ['linewidth', 'min_width', 'width']

WARNING:param.main: Option 'width' for Overlay type not valid for selected backend ('matplotlib'). Option only applies to following backends: ['bokeh']

WARNING:param.main: Option 'height' for Overlay type not valid for selected backend ('matplotlib'). Option only applies to following backends: ['bokeh']
On this page