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.
UxDataset.integrate([quadrature_rule, order])	Integrates over all the faces of the givfen mesh.

Remapping

UxDataset.nearest_neighbor_remap(destination_obj)

Nearest Neighbor Remapping between a source (UxDataset) and destination.`.

Plotting

UxDataset.plot

alias of UxDatasetPlotAccessor

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

Methods

UxDataArray.integrate([quadrature_rule, order])

Computes the integral of a data variable residing on an unstructured grid.

Remapping

UxDataArray.nearest_neighbor_remap(...[, ...])

Nearest Neighbor Remapping between a source (UxDataArray) and destination.`.

Plotting

UxDataArray.plot	alias of UxDataArrayPlotAccessor
UxDataArray.plot.datashade(*args[, method, ...])	Visualizes an unstructured grid data variable using data shading (rasterization + shading).
UxDataArray.plot.rasterize([method, ...])	Performs an unstructured grid rasterization for visualuzation.

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, ...])	Creates a 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.to_shapely_polygons([...])	Constructs an array of Shapely Polygons representing each face, with antimeridian polygons split according to the GeoJSON standards.

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([tree_type])	Get the BallTree data structure of this Grid that allows for nearest neighbor queries (k nearest or within some radius) on either the nodes (Mesh2_node_x, Mesh2_node_y) or face centers (Mesh2_face_x, Mesh2_face_y).
Grid.get_kd_tree([tree_type])	Get the KDTree data structure of this Grid that allows for nearest neighbor queries (k nearest or within some radius) on either the nodes (Mesh2_node_cart_x, Mesh2_node_cart_y, Mesh2_node_cart_z) or face centers (Mesh2_face_cart_x, Mesh2_face_cart_y, Mesh2_face_cart_z).
Grid.copy()	Returns a deep copy of this grid.

Attributes

Grid.Mesh2	UGRID Attribute Mesh2, which indicates the topology data of a 2D unstructured mesh.
Grid.parsed_attrs	Dictionary of parsed attributes from the source grid.
Grid.nMesh2_node	UGRID Dimension nMesh2_node, which represents the total number of nodes.
Grid.nMesh2_face	UGRID Dimension nMesh2_face, which represents the total number of faces.
Grid.nMesh2_edge	UGRID Dimension nMesh2_edge, which represents the total number of edges.
Grid.nMaxMesh2_face_nodes	UGRID Dimension nMaxMesh2_face_nodes, which represents the maximum number of nodes that a face may contain.
Grid.nMaxMesh2_face_edges	Dimension nMaxMesh2_face_edges, which represents the maximum number of edges per face.
Grid.nNodes_per_face	Dimension Variable nNodes_per_face, which contains the number of non-fill-value nodes per face.
Grid.Mesh2_node_x	Coordinate Mesh2_node_x, which contains the longitude of each node in degrees.
Grid.Mesh2_node_y	Coordinate Mesh2_node_y, which contains the latitude of each node in degrees.
Grid.Mesh2_node_cart_x	Coordinate Mesh2_node_cart_x, which contains the Cartesian x of each node in meters.
Grid.Mesh2_node_cart_y	Coordinate Mesh2_node_cart_y, which contains the Cartesian y location of each node in meters.
Grid.Mesh2_node_cart_z	Coordinate Mesh2_node_cart_z, which contains the Cartesian z location of each node in meters.
Grid.Mesh2_face_x	Coordinate Mesh2_face_x, which contains the longitude of each face center in degrees.
Grid.Mesh2_face_y	Coordinate Mesh2_face_y, which contains the latitude of each face center in degrees.
Grid.Mesh2_face_nodes	UGRID Connectivity Variable Mesh2_face_nodes, which maps each face to its corner nodes.
Grid.Mesh2_edge_nodes	UGRID Connectivity Variable Mesh2_edge_nodes, which maps every edge to the two nodes that it connects.
Grid.Mesh2_face_edges	UGRID Connectivity Variable Mesh2_face_edges, which maps every face to its edges.
Grid.Mesh2_edge_faces	UGRID Connectivity Variable Mesh2_edge_faces, which contains the index of the faces that saddle a given edge.
Grid.antimeridian_face_indices	Index of each face that crosses the antimeridian.

Plotting

Grid.plot

alias of GridPlotAccessor

Visualization

Accessors

plot.accessor.GridPlotAccessor(uxgrid)	Plotting Accessor for Grid, accessed through Grid.plot() or Grid.plot.specific_routine()
plot.accessor.UxDataArrayPlotAccessor(uxda)	Plotting Accessor for UxDataArray, accessed through UxDataArray.plot() or UxDataArray.plot.specific_routine()
plot.accessor.UxDatasetPlotAccessor(uxds)	Plotting Accessor for UxDataset, accessed through UxDataset.plot() or UxDataset.plot.specific_routine()

UxDataArray Plotting Methods

plot.dataarray_plot.datashade(uxda, *args[, ...])	Visualizes an unstructured grid data variable using data shading (rasterization + shading).
plot.dataarray_plot.rasterize(uxda[, ...])	Performs an unstructured grid rasterization for visualuzation.

Nearest Neighbor Data Structures

KDTree

grid.neighbors.KDTree(grid[, tree_type, ...])	Custom KDTree data structure written around the sklearn.neighbors.KDTree implementation for use with either the corner (Mesh2_node_cart_x, Mesh2_node_cart_y, Mesh2_node_cart_z) or center (Mesh2_face_cart_x, Mesh2_face_cart_y, Mesh2_face_cart_z) nodes of the inputted unstructured grid.
grid.neighbors.KDTree.query(xyz[, k, ...])	Queries the tree for the k nearest neighbors.
grid.neighbors.KDTree.query_radius(xyz[, r, ...])	Queries the tree for all neighbors within a radius r.

BallTree

grid.neighbors.BallTree(grid[, tree_type, ...])	Custom BallTree data structure written around the sklearn.neighbors.BallTree implementation for use with either the corner (Mesh2_node_x, Mesh2_node_y) or center (Mesh2_face_x, Mesh2_face_y) nodes of the inputted unstructured grid.
grid.neighbors.BallTree.query(xy[, k, ...])	Queries the tree for the k nearest neighbors.
grid.neighbors.BallTree.query_radius(xy[, ...])	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 (Mesh2_face_nodes) 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.

Utils

grid.utils.cross_fma(v1, v2)

Calculate the cross product of two 3D vectors utilizing the fused multiply-add operation.

Numba

utils.enable_jit_cache()	Allows Numba's JIT cache to be turned on.
utils.disable_jit_cache()	Allows Numba's JIT cache to be turned on off.
utils.enable_jit()	Allows Numba's JIT application to be turned on.
utils.disable_jit()	Allows Numba's JIT application to be turned off.