User API

This page shows already-implemented Uxarray user API functions. You can also check the UXarray Milestones and UXarray RoadMap for a high level understanding of UXarray’s future function development milestones and roadmap. Please let us know if you have any feedback!

UxDataset

A xarray.Dataset-like, multi-dimensional, in memory, array database. Inherits from xarray.Dataset and has its own unstructured grid-aware dataset operators and attributes through the uxgrid accessor.

Below is a list of features explicitly added to UxDataset to work on Unstructured Grids:

Class

UxDataset(*args[, uxgrid, source_datasets])

A xarray.Dataset-like, multi-dimensional, in memory, array database.

IO

open_dataset(grid_filename_or_obj, ...[, ...])	Wraps xarray.open_dataset() and creates a uxarray.UxDataset object, given a grid topology definition with a single dataset file or object with corresponding data.
open_mfdataset(grid_filename_or_obj, paths)	Wraps xarray.open_mfdataset() and creates a uxarray.UxDataset object, given a single grid topology file with multiple dataset paths with corresponding data.

Attributes

UxDataset.uxgrid	uxarray.Grid property for uxarray.UxDataset to make it unstructured grid-aware.
UxDataset.source_datasets	Property to keep track of the source data sets used to instantiate this uxarray.UxDataset.

Methods

UxDataset.info([buf, show_attrs])

Concise summary of Dataset variables and attributes including grid topology information stored in the uxgrid property.

Remapping

UxDataset.nearest_neighbor_remap(destination_obj)	Nearest Neighbor Remapping between a source (UxDataset) and destination.`.
UxDataset.inverse_distance_weighted_remap(...)	Inverse Distance Weighted Remapping between a source (UxDataset) and destination.`.

Plotting

UxDataset.plot

Plotting Accessor for UxDataset, accessed through UxDataset.plot() or UxDataset.plot.specific_routine()

UxDataArray

N-dimensional xarray.DataArray-like array. Inherits from xarray.DataArray and has its own unstructured grid-aware array operators and attributes through the uxgrid accessor.

Below is a list of features explicitly added to UxDataset to work on Unstructured Grids:

Class

UxDataArray(*args[, uxgrid])

N-dimensional xarray.DataArray-like array.

IO

UxDataArray.to_dataset()	Converts a UxDataArray into a UxDataset with a single data variable.
UxDataArray.to_geodataframe([override, ...])	Constructs a spatialpandas.GeoDataFrame with a "geometry" column, containing a collection of Shapely Polygons or MultiPolygons representing the geometry of the unstructured grid, and a data column representing a 1D slice of data mapped to each Polygon.
UxDataArray.to_polycollection([override, ...])	Constructs a matplotlib.collections.PolyCollection object with polygons representing the geometry of the unstructured grid, with polygons that cross the antimeridian split across the antimeridian.

Attributes

UxDataArray.uxgrid

uxarray.Grid property for uxarray.UxDataArray to make it unstructured grid-aware.

Methods

UxDataArray.integrate([quadrature_rule, order])	Computes the integral of a data variable residing on an unstructured grid.
UxDataArray.isel([ignore_grid])	Grid-informed implementation of xarray's isel method, which enables indexing across grid dimensions.

Remapping

UxDataArray.nearest_neighbor_remap(...[, ...])	Nearest Neighbor Remapping between a source (UxDataArray) and destination.`.
UxDataArray.inverse_distance_weighted_remap(...)	Inverse Distance Weighted Remapping between a source (UxDataArray) and destination.`.
UxDataArray.nodal_average()	Computes the Nodal Average of a Data Variable, which is the mean of the nodes that surround each face.

Plotting

UxDataArray.plot

Plotting Accessor for UxDataArray, accessed through UxDataArray.plot() or UxDataArray.plot.specific_routine()

UxDataArray.plot.datashade(*args[, method, ...])	Visualizes an unstructured grid data variable using data shading (rasterization + shading).
UxDataArray.plot.rasterize([method, ...])	Rasterized Plot of a Data Variable Residing on an Unstructured Grid.
UxDataArray.plot.polygons([backend, ...])	Vector Polygon Plot of a Data Variable Residing on an Unstructured Grid.
UxDataArray.plot.points([backend, width, ...])	Vector Point Plot of a Data Variable Mapped to either Node, Edge, or Face Coordinates.

Subsetting

UxDataArray.subset

Accessor for performing unstructured grid subsetting with a data variable, accessed through UxDataArray.subset

UxDataArray.subset.nearest_neighbor(...[, ...])	Subsets an unstructured grid by returning the k closest neighbors from a center coordinate.
UxDataArray.subset.bounding_circle(...[, ...])	Subsets an unstructured grid by returning all elements within some radius (in degrees) from a center coord.
UxDataArray.subset.bounding_box(lon_bounds, ...)	Subsets an unstructured grid between two latitude and longitude points which form a bounding box.

Calculus Operators

UxDataArray.integrate([quadrature_rule, order])	Computes the integral of a data variable residing on an unstructured grid.
UxDataArray.gradient([normalize, use_magnitude])	Computes the horizontal gradient of a data variable residing on an unstructured grid.
UxDataArray.difference([destination])	Computes the absolute difference between a data variable.

Grid

Unstructured grid topology definition to store stores grid topology dimensions, coordinates, variables and provides grid-specific functions.

Can be used standalone to explore an unstructured grid topology, or can be seen as the property of uxarray.UxDataset and uxarray.DataArray to make them unstructured grid-aware data sets and arrays.

Class

Grid(grid_ds[, source_grid_spec, ...])

Represents a two-dimensional unstructured grid encoded following the UGRID conventions and provides grid-specific functionality.

IO

open_grid(grid_filename_or_obj[, latlon, ...])	Constructs and returns an uxarray.Grid object from a grid topology definition.
Grid.from_dataset(dataset[, use_dual])	Constructs a Grid object from an xarray.Dataset.
Grid.from_face_vertices(face_vertices[, latlon])	Constructs a Grid object from user-defined face vertices.
Grid.to_geodataframe([override, cache, ...])	Constructs a spatialpandas.GeoDataFrame with a "geometry" column, containing a collection of Shapely Polygons or MultiPolygons representing the geometry of the unstructured grid.
Grid.to_polycollection([override, cache, ...])	Constructs a matplotlib.collections.PolyCollection object with polygons representing the geometry of the unstructured grid, with polygons that cross the antimeridian split.
Grid.to_linecollection([override, cache])	Constructs a matplotlib.collections.LineCollection object with line segments representing the geometry of the unstructured grid, corrected near the antimeridian.
Grid.validate()	Validate a grid object check for common errors, such as:

Methods

Grid.calculate_total_face_area([...])	Function to calculate the total surface area of all the faces in a mesh.
Grid.compute_face_areas([quadrature_rule, ...])	Face areas calculation function for grid class, calculates area of all faces in the grid.
Grid.encode_as(grid_type)	Encodes the grid as a new xarray.Dataset per grid format supplied in the grid_type argument.
Grid.get_ball_tree([coordinates, ...])	Get the BallTree data structure of this Grid that allows for nearest neighbor queries (k nearest or within some radius) on either the (node_x, node_y, node_z) and (node_lon, node_lat), edge (edge_x, edge_y, edge_z) and (edge_lon, edge_lat), or center (face_x, face_y, face_z) and (face_lon, ` face_lat`) nodes.
Grid.get_kd_tree([coordinates, ...])	Get the KDTree data structure of this Grid that allows for nearest neighbor queries (k nearest or within some radius) on either the (node_x, node_y, node_z) and (node_lon, node_lat), edge (edge_x, edge_y, edge_z) and (edge_lon, edge_lat), or center (face_x, face_y, face_z) and (face_lon, face_lat) nodes.
Grid.copy()	Returns a deep copy of this grid.
Grid.isel(**dim_kwargs)	Indexes an unstructured grid along a given dimension (n_node, n_edge, or n_face) and returns a new grid.

Dimensions

Grid.n_node	Total number of nodes.
Grid.n_edge	Total number of edges.
Grid.n_face	Total number of faces.
Grid.n_max_face_nodes	The maximum number of nodes that can make up a single face.
Grid.n_max_face_edges	The maximum number of edges that surround a single face.
Grid.n_max_face_faces	The maximum number of faces that surround a single face.
Grid.n_max_edge_edges	The maximum number of edges that surround a single edge.
Grid.n_max_node_faces	The maximum number of faces that surround a single node.
Grid.n_max_node_edges	The maximum number of edges that surround a single node.
Grid.n_nodes_per_face	The number of nodes that make up each face.

Spherical Coordinates

Grid.node_lon	Longitude of each node in degrees.
Grid.node_lat	Latitude of each node in degrees.
Grid.edge_lon	Longitude of the center of each edge in degrees.
Grid.edge_lat	Latitude of the center of each edge in degrees.
Grid.face_lon	Longitude of the center of each face in degrees.
Grid.face_lat	Latitude of the center of each face in degrees.

Cartesian Coordinates

Grid.node_x	Cartesian x location of each node in meters.
Grid.node_y	Cartesian y location of each node in meters.
Grid.node_z	Cartesian z location of each node in meters.
Grid.edge_x	Cartesian x location of the center of each edge in meters.
Grid.edge_y	Cartesian y location of the center of each edge in meters.
Grid.edge_z	Cartesian z location of the center of each edge in meters.
Grid.face_x	Cartesian x location of the center of each face in meters.
Grid.face_y	Cartesian y location of the center of each face in meters.
Grid.face_z	Cartesian z location of the center of each face in meters.

Connectivity

Grid.face_node_connectivity	Indices of the nodes that make up each face.
Grid.face_edge_connectivity	Indices of the edges that surround each face.
Grid.face_face_connectivity	Indices of the faces that surround each face.
Grid.edge_node_connectivity	Indices of the two nodes that make up each edge.
Grid.edge_edge_connectivity	Indices of the edges that surround each edge.
Grid.edge_face_connectivity	Indices of the faces that saddle each edge.
Grid.node_edge_connectivity	Indices of the edges that surround each node.
Grid.node_face_connectivity	Indices of the faces that surround each node.

Grid Descriptors

Grid.face_areas	The area of each face.
Grid.antimeridian_face_indices	Index of each face that crosses the antimeridian.
Grid.bounds	Latitude Longitude Bounds for each Face in degrees.

Attributes

Grid.attrs

Dictionary of parsed attributes from the source grid.

Plotting

Grid.plot

Plotting Accessor for Grid, accessed through Grid.plot() or Grid.plot.specific_routine()

Grid.plot.node_coords([backend, width, height])	Vector Point Plot of Nodes (latitude & longitude of the nodes that define the corners of each face)
Grid.plot.nodes([backend, width, height])	Vector Point Plot of Nodes (latitude & longitude of the nodes that define the corners of each face)
Grid.plot.face_coords([backend, width, height])	Vector Point Plot of Face Coordinates (latitude & longitude of the centroid of each face)
Grid.plot.face_centers([backend, width, height])	Vector Point Plot of Face Coordinates (latitude & longitude of the centroid of each face)
Grid.plot.edge_coords([backend, width, height])	Vector Point Plot of Edge Coordinates (latitude & longitude of the center of each edge)
Grid.plot.edge_centers([backend, width, height])	Vector Point Plot of Edge Coordinates (latitude & longitude of the center of each edge)
Grid.plot.mesh([backend, ...])	Vector Line Plot of the edges that make up each face.
Grid.plot.edges([backend, ...])	Vector Line Plot of the edges that make up each face.

Subsetting

Grid.subset

Accessor for performing unstructured grid subsetting, accessed through Grid.subset

Grid.subset.nearest_neighbor(center_coord, k)	Subsets an unstructured grid by returning the k closest neighbors from a center coordinate.
Grid.subset.bounding_circle(center_coord, r)	Subsets an unstructured grid by returning all elements within some radius (in degrees) from a center coord.
Grid.subset.bounding_box(lon_bounds, lat_bounds)	Subsets an unstructured grid between two latitude and longitude points which form a bounding box.

Nearest Neighbor Data Structures

KDTree

grid.neighbors.KDTree(grid[, coordinates, ...])	Custom KDTree data structure written around the sklearn.neighbors.KDTree implementation for use with corner (node_x, node_y, node_z) and (node_lon, node_lat), edge (edge_x, edge_y, edge_z) and (edge_lon, edge_lat), or center (face_x, face_y, face_z) and (face_lon, face_lat) nodes of the inputted unstructured grid.
grid.neighbors.KDTree.query(coords[, k, ...])	Queries the tree for the k nearest neighbors.
grid.neighbors.KDTree.query_radius(coords[, ...])	Queries the tree for all neighbors within a radius r.

BallTree

grid.neighbors.BallTree(grid[, coordinates, ...])	Custom BallTree data structure written around the sklearn.neighbors.BallTree implementation for use with either the (node_x, node_y, node_z) and (node_lon, node_lat), edge (edge_x, edge_y, edge_z) and (edge_lon, edge_lat), or center (face_x, face_y, face_z) and (face_lon, face_lat) nodes of the inputted unstructured grid.
grid.neighbors.BallTree.query(coords[, k, ...])	Queries the tree for the k nearest neighbors.
grid.neighbors.BallTree.query_radius(coords)	Queries the tree for all neighbors within a radius r.

Helpers

Face Area

grid.area.calculate_face_area(x, y, z[, ...])	Calculate area of a face on sphere.
grid.area.get_all_face_area_from_coords(x, ...)	Given coords, connectivity and other area calculation params, this routine loop over all faces and return an numpy array with areas of each face.
grid.area.calculate_spherical_triangle_jacobian(...)	Calculate Jacobian of a spherical triangle.
grid.area.calculate_spherical_triangle_jacobian_barycentric(...)	Calculate Jacobian of a spherical triangle.
grid.area.get_gauss_quadratureDG(nCount)	Gauss Quadrature Points for integration.
grid.area.get_tri_quadratureDG(nOrder)	Triangular Quadrature Points for integration.

Connectivity

grid.connectivity.close_face_nodes(...)

Closes (face_node_connectivity) by inserting the first node index after the last non-fill-value node.

Coordinates

grid.coordinates.node_lonlat_rad_to_xyz(...)	Helper function to Convert the node coordinate from 2D longitude/latitude to normalized 3D xyz.
grid.coordinates.node_xyz_to_lonlat_rad(...)	Calculate the latitude and longitude in radiance for a node represented in the [x, y, z] 3D Cartesian coordinates.
grid.coordinates.normalize_in_place(node)	Helper function to project an arbitrary node in 3D coordinates [x, y, z] on the unit sphere.

Arcs

grid.arcs.in_between(p, q, r)	Determines whether the number q is between p and r.
grid.arcs.point_within_gca(pt, gca_cart[, ...])	Check if a point lies on a given Great Circle Arc (GCA).
grid.arcs.extreme_gca_latitude(gca_cart, ...)	Calculate the maximum or minimum latitude of a great circle arc defined by two 3D points.

Intersections

grid.intersections.gca_gca_intersection(...)	Calculate the intersection point(s) of two Great Circle Arcs (GCAs) in a Cartesian coordinate system.
grid.intersections.gca_constLat_intersection(...)	Calculate the intersection point(s) of a Great Circle Arc (GCA) and a constant latitude line in a Cartesian coordinate system.

Accurate Computing Utils

utils.computing.cross_fma(v1, v2)	Calculate the cross product of two 3D vectors utilizing the fused multiply-add operation.
utils.computing.dot_fma(v1, v2)	Calculate the dot product of two vectors using the FMA (fused multiply- add) operation.

Numba