Plotting

This section introduces UXarray’s plotting API, showcasing how to visualize both data variables and grid topology.

import uxarray as ux

Data

For most of the examples in this notebook, we will be using a simple mesh consisting of 4 hexagons, with sample data mapped to the faces, edges, and nodes.

grid_path = "../../test/meshfiles/ugrid/quad-hexagon/grid.nc"

data_paths = [
    "../../test/meshfiles/ugrid/quad-hexagon/random-node-data.nc",
    "../../test/meshfiles/ugrid/quad-hexagon/random-edge-data.nc",
    "../../test/meshfiles/ugrid/quad-hexagon/random-face-data.nc",
]

uxds = ux.open_mfdataset(grid_path, data_paths)
uxgrid = uxds.uxgrid

uxds

<xarray.UxDataset> Size: 312B
Dimensions:           (n_node: 16, n_edge: 19, n_face: 4)
Dimensions without coordinates: n_node, n_edge, n_face
Data variables:
    random_data_node  (n_node) float64 128B dask.array<chunksize=(16,), meta=np.ndarray>
    random_data_edge  (n_edge) float64 152B dask.array<chunksize=(19,), meta=np.ndarray>
    random_data_face  (n_face) float64 32B dask.array<chunksize=(4,), meta=np.ndarray>

<xarray.UxDataset> Size: 312B
Dimensions:           (n_node: 16, n_edge: 19, n_face: 4)
Dimensions without coordinates: n_node, n_edge, n_face
Data variables:
    random_data_node  (n_node) float64 128B dask.array<chunksize=(16,), meta=np.ndarray>
    random_data_edge  (n_edge) float64 152B dask.array<chunksize=(19,), meta=np.ndarray>
    random_data_face  (n_face) float64 32B dask.array<chunksize=(4,), meta=np.ndarray>

uxarray.UxDataset

• Dimensions:
  • n_node: 16
  • n_edge: 19
  • n_face: 4
• Coordinates: (0)
• Data variables: (3)
  • random_data_node
    (n_node)
    float64
    dask.array<chunksize=(16,), meta=np.ndarray>

    Array Chunk Bytes 128 B 128 B Shape (16,) (16,) Dask graph 1 chunks in 2 graph layers Data type float64 numpy.ndarray

  • random_data_edge
    (n_edge)
    float64
    dask.array<chunksize=(19,), meta=np.ndarray>

    Array Chunk Bytes 152 B 152 B Shape (19,) (19,) Dask graph 1 chunks in 2 graph layers Data type float64 numpy.ndarray

  • random_data_face
    (n_face)
    float64
    dask.array<chunksize=(4,), meta=np.ndarray>

    Array Chunk Bytes 32 B 32 B Shape (4,) (4,) Dask graph 1 chunks in 2 graph layers Data type float64 numpy.ndarray

• Indexes: (0)
• Attributes: (0)

Show Grid Information

<uxarray.Grid>
Original Grid Type: UGRID
Grid Dimensions:
  * n_node: 16
  * n_edge: 19
  * n_face: 4
  * n_max_face_nodes: 6
Grid Coordinates (Spherical):
  * node_lon: (16,)
  * node_lat: (16,)
  * edge_lon: (19,)
  * edge_lat: (19,)
  * face_lon: (4,)
  * face_lat: (4,)
Grid Coordinates (Cartesian):
Grid Connectivity Variables:
  * face_node_connectivity: (4, 6)
Grid Descriptor Variables:
  * n_nodes_per_face: (4,)

uxarray.UxDataset.uxgrid

• Dimensions:
  • n_node: 16
  • n_face: 4
  • n_edge: 19
  • n_max_face_nodes: 6
• Spherical Coordinates: (6)
  • node_lon
    (n_node)
    float32
    -0.03841 -0.1864 ... 0.2352 0.2439

    standard_name :

    longitude

    long_name :

    longitude of mesh nodes

    units :

    degrees_east

    array([-0.038411, -0.186448, -0.181994, -0.047552,  0.100399,  0.096181,
            0.105031,  0.239774, -0.177116, -0.325237,  0.378854,  0.382835,
           -0.042753, -0.320659,  0.235225,  0.243879], dtype=float32)

  • node_lat
    (n_node)
    float32
    ...

    standard_name :

    latitude

    long_name :

    latitude of mesh nodes

    units :

    degrees_north

    [16 values with dtype=float32]

  • edge_lon
    (n_edge)
    float32
    -0.1149 0.02647 ... 0.03119 0.1723

    standard_name :

    longitude

    long name :

    Longitude of the center of each edge

    units :

    degrees_east

    array([-0.114868,  0.026474,  0.167755,  0.309082, -0.184204,  0.098297,
            0.380844, -0.253662, -0.112366,  0.028824,  0.17009 ,  0.311295,
           -0.322998, -0.040649,  0.241837, -0.251099, -0.109985,  0.031189,
            0.172333], dtype=float32)

  • edge_lat
    (n_edge)
    float32
    ...

    standard_name :

    latitude

    long_name :

    latitude of edge centers

    units :

    degrees_north

    [19 values with dtype=float32]

  • face_lon
    (n_face)
    float32
    -0.04297 0.1006 -0.1818 0.2396

    standard_name :

    longitude

    long name :

    Longitude of the center of each face

    units :

    degrees_east

    array([-0.042969,  0.100616, -0.181763,  0.239563], dtype=float32)

  • face_lat
    (n_face)
    float32
    ...

    standard_name :

    latitude

    long_name :

    latitude of center nodes

    units :

    degrees_north

    [4 values with dtype=float32]

• Cartesian Coordinates: (0)
• Connectivity: (1)
  • face_node_connectivity
    (n_face, n_max_face_nodes)
    int64
    0 1 2 3 4 5 15 ... 4 14 11 10 15 5

    cf_role :

    face_node_connectivity

    long name :

    Maps every face to its corner nodes.

    start_index :

    0

    _FillValue :

    -9223372036854775808

    array([[ 0,  1,  2,  3,  4,  5],
           [15,  7,  6, 12,  0,  5],
           [ 0, 12,  8,  9, 13,  1],
           [ 4, 14, 11, 10, 15,  5]])

• Descriptors: (1)
  • n_nodes_per_face
    (n_face)
    int64
    ...

    cf_role :

    n_nodes_per_face

    long name :

    Number of nodes per face

    [4 values with dtype=int64]

• Attributes: (55)

  model_name :

  mpas

  core_name :

  init_atmosphere

  source :

  MPAS

  Conventions :

  MPAS

  git_version :

  v6.0-dirty

  on_a_sphere :

  YES

  sphere_radius :

  6371229.0

  is_periodic :

  NO

  x_period :

  0.0

  y_period :

  0.0

  history :

  Mon Aug 16 12:09:52 2021: ncks -v latVertex,lonVertex,latCell,lonCell,latEdge,lonEdge,cellsOnVertex,verticesOnCell,verticesOnEdge,edgesOnVertex,edgesOnCell,nEdgesOnCell,angleEdge x1.655362.init.nc foo.nc mpirun -n 18 ./init_atmosphere_model

  parent_id :

  0hhmjs26t0

  mesh_spec :

  0.0

  config_init_case :

  7

  config_calendar_type :

  gregorian

  config_start_time :

  2016-08-01_00:00:00

  config_stop_time :

  2016-09-10_00:00:00

  config_theta_adv_order :

  3

  config_coef_3rd_order :

  0.25

  config_num_halos :

  2

  config_nvertlevels :

  75

  config_nsoillevels :

  4

  config_nfglevels :

  38

  config_nfgsoillevels :

  4

  config_months :

  12

  config_geog_data_path :

  /glade/p/work/wrfhelp/WPS_GEOG/

  config_met_prefix :

  FILE

  config_sfc_prefix :

  SST

  config_fg_interval :

  86400

  config_landuse_data :

  USGS

  config_topo_data :

  GMTED2010

  config_use_spechumd :

  NO

  config_ztop :

  40000.0

  config_nsmterrain :

  1

  config_smooth_surfaces :

  YES

  config_dzmin :

  0.3

  config_nsm :

  30

  config_tc_vertical_grid :

  YES

  config_extrap_airtemp :

  linear

  config_static_interp :

  NO

  config_native_gwd_static :

  NO

  config_gwd_cell_scaling :

  1.0

  config_vertical_grid :

  YES

  config_met_interp :

  YES

  config_input_sst :

  NO

  config_frac_seaice :

  YES

  config_pio_num_iotasks :

  0

  config_pio_stride :

  1

  config_block_decomp_file_prefix :

  x1.655362.graph.info.part.

  config_number_of_blocks :

  0

  config_explicit_proc_decomp :

  NO

  config_proc_decomp_file_prefix :

  graph.info.part.

  file_id :

  ytj0fh0qmd

  NCO :

  netCDF Operators version 4.9.5 (Homepage = http://nco.sf.net, Code = http://github.com/nco/nco)

  source_grid_spec :

  UGRID

Grid Topology Visualization

The topology (i.e. edges and coordinates) of an unstructured grid can be plotted using the Grid.plot() accessor. By default, Grid.plot() will plot the edges of the unstructured grid.

uxgrid.plot(title="Grid Plot Accessor")

Edge Plots

The default plotting routine above calls the Grid.edges() method, which visualizes the edges of each face in the unstructured grid.

uxgrid.plot.edges(color="black", title="Grid Edge Plot")

Point Plots

There are three coordinates that are typically associated with unstructured grids:

• Corner Nodes: node_lon & node_lat

• Edge Centers: edge_lon & edge_lat

• Face Centers: face_lon & face_lat

These coordinates can be plotted using the following plotting methods:

• Corner Nodes: Grid.plot.nodes()

• Edge Centers: Grid.plot.edge_centers()

• Face Centers: Grid.plot.face_centers()

(
    uxgrid.plot.edges(color="black")
    * uxgrid.plot.nodes(marker="o", size=150).relabel("Corner Nodes")
    * uxgrid.plot.face_centers(marker="s", size=150).relabel("Face Centers")
    * uxgrid.plot.edge_centers(marker="^", size=150).relabel("Edge Centers")
).opts(title="Grid Coordinates", legend_position="top_right")

Data Visualization

Visualizing Data

The section above visualized the topology an unstructured grid. If you are working with data residing on an unstructured grid, plotting is handled through the UxDataArray.plot() accessor.

uxds["random_data_face"].plot(
    cmap=ux.cmaps.diverging, title="UxDataArray Plot Accessor"
)

Polygons

Face centered data can be visualized as polygons using the UxDataArray.polygons() method. The geometry of each face is represented as a polygon, shaded with the data variable mapped to it.

(
    uxds["random_data_face"].plot.polygons(
        rasterize=False,
        cmap=ux.cmaps.diverging,
        title="Vector Polygons (rasterize=False)",
        colorbar=False,
    )
    + uxds["random_data_face"].plot.polygons(
        rasterize=True,
        cmap=ux.cmaps.diverging,
        title="Raster Polygons (rasterize=True)",
        colorbar=False,
    )
).cols(1)

Points

Since data can be mapped to either the nodes, edges, or faces of an unstructured grid, the coordinates at these locations can be shaded to represent the data. Data can be plotted as points using the UxDataArray.plot.points() method.

(
    uxds.uxgrid.plot(line_color="black")
    * uxds["random_data_node"]
    .plot.points(
        cmap="inferno", size=150, marker="circle", clabel=None, tools=["hover"]
    )
    .relabel("Node Data")
    * uxds["random_data_edge"]
    .plot.points(
        cmap="inferno", size=150, marker="square", clabel=None, tools=["hover"]
    )
    .relabel("Edge Data")
    * uxds["random_data_face"]
    .plot.points(
        cmap="inferno", size=150, marker="triangle", clabel=None, tools=["hover"]
    )
    .relabel("Face Data")
).opts(title="Plotting Data as Points", legend_position="top_right")

Working with Periodic Data

The grid used in the previous example is extremely simple, only consisting of 4 hexagons. When working with a periodic global grid, such as those from global climate model simulations, additional attention must be given to handling periodic elements (i.e. those that cross the antimeridian.

The periodic_elements parameter can be used to select how to handle these elements.

• periodic_elements='exclude': Periodic polygons are excluded from the final plot

• periodic_elements='split': Periodic polygons are split along the antimeridian

• periodic_elements='ignore': Periodic polygons are left uncorrected.

Warning

It is suggested to keep periodic_elements='exclude' (default value) when working with moderatly large datasets, as there is a significant overhead needed correct the antimeridian faces.

base_path = "../../test/meshfiles/mpas/QU/"
grid_path = base_path + "oQU480.231010.nc"
uxds_mpas = ux.open_dataset(grid_path, grid_path)

(
    uxds_mpas["bottomDepth"]
    .plot(cmap=ux.cmaps.sequential_blue)
    .opts(width=700, height=350, title="Default Plot (Excluding Periodic Elements)")
    + uxds_mpas["bottomDepth"]
    .plot(
        periodic_elements="split", cmap=ux.cmaps.sequential_blue, width=700, height=350
    )
    .opts(title="Include Periodic Elements (Split)")
).cols(1)