API reference

This page provides an auto-generated summary of UXarray’s API. For more details and examples, refer to the relevant chapters in the main part of the documentation.

Top Level Functions

open_grid(grid_filename_or_obj[, chunks, ...])	Constructs and returns a Grid from a grid file.
open_dataset(grid_filename_or_obj, ...[, ...])	Wraps xarray.open_dataset() for loading in a dataset paired with a grid file.
open_mfdataset(grid_filename_or_obj, paths)	Wraps xarray.open_dataset() to support reading in a grid and multiple data files together.
concat(objs, *args, **kwargs)

Grid

Constructors

Grid(grid_ds[, source_grid_spec, ...])	Represents a two-dimensional unstructured grid encoded following the UGRID conventions and provides grid-specific functionality.
Grid.from_dataset(dataset[, use_dual])	Constructs a Grid object from a dataset.
Grid.from_file(filename[, backend])	Constructs a Grid object from a using the read_file method with a specified backend.
Grid.from_topology(node_lon, node_lat, ...)	Constructs a Grid object from user-defined topology variables provided in the UGRID conventions.
Grid.from_structured([ds, lon, lat, tol])	Converts a structured xarray.Dataset or longitude and latitude coordinates into an unstructured uxarray.Grid.
Grid.from_points(points[, method, ...])	Create a grid from unstructured points.
Grid.from_healpix(zoom[, pixels_only, nest])	Constructs a Grid object representing a given HEALPix zoom level.

Indexing

Grid.isel([inverse_indices])	Indexes an unstructured grid along a given dimension (n_node, n_edge, or n_face) and returns a new grid.
Grid.inverse_indices	Indices for a subset that map each face in the subset back to the original grid

Dimensions

Grid.dims	Names of all unstructured grid dimensions.
Grid.sizes	Names and values of all unstructured 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	Maximum number of nodes defining a single face.
Grid.n_max_face_edges	Maximum number of edges defining a single face.
Grid.n_max_face_faces	Maximum number of neighboring faces surrounding a single face.
Grid.n_max_edge_edges	Maximum number of edges surrounding a single edge.
Grid.n_max_node_faces	Maximum number of faces surrounding a single node.
Grid.n_max_node_edges	Maximum number of edges surrounding a single node.
Grid.n_nodes_per_face	An array containing the maximum number of nodes for each face.

Spherical Coordinates

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

Cartesian Coordinates

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

Connectivity

Grid.connectivity	Names of all connectivity variables.
Grid.face_node_connectivity	Connectivity variable representing the indices of nodes (mesh vertices) that define each face.
Grid.face_edge_connectivity	Connectivity variable representing the indices of edges that define each face.
Grid.face_face_connectivity	Connectivity variable representing the indices of faces that share edges.
Grid.edge_node_connectivity	Connectivity variable representing the indices of nodes (mesh vertices) that define each edge.
Grid.edge_edge_connectivity	Connectivity variable representing the indices of edges that share at least one node.
Grid.edge_face_connectivity	Connectivity variable representing the indices of faces that saddle each edge.
Grid.node_node_connectivity	Connectivity variable representing the indices of nodes (mesh vertices) that surround each node.
Grid.node_edge_connectivity	Connectivity variable representing the indices of edges that contain each node.
Grid.node_face_connectivity	Connectivity variable representing the indices of faces that share a given node.

Descriptors

Grid.descriptors	Names of all descriptor variables.
Grid.face_areas	Area of each face.
Grid.bounds	Spherical bounds of each face in degrees
Grid.face_bounds_lon	Longitude bounds for each face in degrees.
Grid.face_bounds_lat	Latitude bounds for each face in degrees.
Grid.edge_node_distances	Arc distance between the two nodes that make up each edge (in radians).
Grid.edge_face_distances	Arc distance between the faces that saddle each edge (in radians).
Grid.antimeridian_face_indices	Indices of faces that touch or cross the antimeridian.
Grid.boundary_node_indices	Indices of nodes that border regions not covered by any geometry (holes) in a partial grid.
Grid.boundary_edge_indices	Indices of edges that border regions not covered by any geometry (holes) in a partial grid.
Grid.boundary_face_indices	Indices of faces that border regions not covered by any geometry (holes) in a partial grid.
Grid.partial_sphere_coverage	Boolean indicated whether the Grid partial covers the unit sphere (i.e. contains holes).
Grid.global_sphere_coverage	Boolean indicated whether the Grid completely covers the unit sphere (i.e. contains no holes).
Grid.triangular	Boolean indicated whether the Grid is strictly composed of triangular faces.
Grid.max_face_radius	Maximum Euclidean distance from each face center to its nodes.

Attributes

Grid.attrs

Dictionary of parsed attributes from the source grid.

Methods

Grid.copy()	Returns a deep copy of this grid.
Grid.chunk([n_node, n_edge, n_face])	Converts all arrays to dask arrays with given chunks across grid dimensions in-place.
Grid.validate([check_duplicates])	Validates the current Grid, checking for Duplicate Nodes, Present Connectivity, and Non-Zero Face Areas.
Grid.compute_face_areas([quadrature_rule, ...])	Face areas calculation function for grid class, calculates area of all faces in the grid.
Grid.calculate_total_face_area([...])	Function to calculate the total surface area of all the faces in a mesh.
Grid.normalize_cartesian_coordinates()	Normalizes Cartesian coordinates.
Grid.construct_face_centers([method])	Constructs face centers, this method provides users direct control of the method for constructing the face centers, the default method is "cartesian average", but a more accurate method is "welzl" that is based on the recursive Welzl algorithm.
Grid.get_spatial_hash([reconstruct])	Get the SpatialHash data structure of this Grid that allows for fast face search queries.
Grid.get_faces_containing_point(points[, ...])	Identify which grid faces contain the given point(s).

Inheritance of Xarray Functionality

The primary data structures in UXarray, uxarray.UxDataArray and uxarray.UxDataset inherit from xarray.DataArray and xarray.Dataset respectively. This means that they contain the same methods and attributes that are present in Xarray, with new additions and some overloaded as discussed in the next sections. For a detailed list of Xarray specific behavior and functionality, please refer to Xarray’s documentation.

UxDataArray

Constructors

UxDataArray(*args[, uxgrid])	Grid informed xarray.DataArray with an attached Grid accessor and grid-specific functionality.
UxDataArray.from_xarray(da, uxgrid[, ugrid_dims])	Converts a xarray.DataArray into a uxarray.UxDataset paired with a user-defined Grid
UxDataArray.from_healpix(da[, pixels_only, ...])	Loads a data array represented in the HEALPix format into a ux.UxDataArray, paired with a Grid containing information about the HEALPix definition.

Grid Accessor

UxDataArray.uxgrid

Linked Grid representing to the unstructured grid the data resides on.

UxDataset

Constructors

UxDataset(*args[, uxgrid, source_datasets])	Grid informed xarray.Dataset with an attached Grid accessor and grid-specific functionality.
UxDataset.from_structured(ds)	Converts a structured xarray.Dataset into an unstructured uxarray.UxDataset
UxDataset.from_xarray(ds[, uxgrid, ugrid_dims])	Converts a xarray.Dataset into a uxarray.UxDataset, paired with either a user-defined or parsed Grid
UxDataset.from_healpix(ds[, pixels_only, ...])	Loads a dataset represented in the HEALPix format into a ux.UxDataSet, paired with a Grid containing information about the HEALPix definition.

Grid Accessor

UxDataset.uxgrid

Linked Grid representing to the unstructured grid the data resides on.

Conversion Methods

UXarray provides functionality to convert its unstructured grids representation to other data structures that can be ingested by existing, widely used tools, such as Matplotlib and Cartopy. This allows users to keep using their workflows with such tools.

Grid

Grid.to_geodataframe([periodic_elements, ...])	Constructs a GeoDataFrame consisting of polygons representing the faces of the current Grid
Grid.to_polycollection(**kwargs)	Constructs a matplotlib.collections.PolyCollection` consisting of polygons representing the faces of the current Grid
Grid.to_linecollection(**kwargs)	Constructs a matplotlib.collections.LineCollection` consisting of lines representing the edges of the current Grid
Grid.to_xarray([grid_format])	Returns an xarray.Dataset with the variables stored under the Grid encoded in a specific grid format.

UxDataArray

UxDataArray.to_geodataframe([...])	Constructs a GeoDataFrame consisting of polygons representing the faces of the current Grid with a face-centered data variable mapped to them.
UxDataArray.to_polycollection(**kwargs)	Constructs a matplotlib.collections.PolyCollection` consisting of polygons representing the faces of the current UxDataArray with a face-centered data variable mapped to them.
UxDataArray.to_raster(ax)	Rasterizes a data variable stored on the faces of an unstructured grid onto the pixels of the provided Cartopy GeoAxes.
UxDataArray.to_dataset([dim, name, ...])	Convert a UxDataArray to a UxDataset.
UxDataArray.to_xarray()

UxDataset

UxDataset.to_xarray([grid_format])	Converts a ux.UXDataset to a xr.Dataset.
UxDataset.to_array()	Override to make the result an instance of uxarray.UxDataArray.

Plotting

UXarray’s plotting API is written using hvPlot. We also support standalone functions for pure Matplotlib and Cartopy workflows.

See also

Plotting User Guide Section Plotting with Matplotlib User Guide Section

Grid

Grid.plot()	Plotting accessor for Grid.
Grid.plot.mesh([periodic_elements, backend])	Plots the edges of a Grid.
Grid.plot.edges([periodic_elements, ...])	Plots the edges of a Grid.
Grid.plot.node_coords([backend])	Generate a point plot for the grid corner nodes.
Grid.plot.nodes([backend])	Generate a point plot for the grid corner nodes.
Grid.plot.face_coords([backend])	Wrapper for Grid.plot.points(element='face centers')
Grid.plot.face_centers([backend])	Wrapper for Grid.plot.points(element='face centers')
Grid.plot.edge_coords([backend])	Wrapper for Grid.plot.points(element='edge centers')
Grid.plot.edge_centers([backend])	Wrapper for Grid.plot.points(element='edge centers')
Grid.plot.face_degree_distribution([...])	Plots the distribution of the number of nodes per face as a bar plot.
Grid.plot.face_area_distribution([backend, ...])	Plots a histogram of the face areas using hvplot.

UxDataArray

UxDataArray.plot()	Plotting Accessor for UxDataArray.
UxDataArray.plot.polygons([...])	Generated a shaded polygon plot.
UxDataArray.plot.points([backend])	Generate a point plot based on the specified grid element type (nodes, faces, or edges) shaded with the data mapped to those elements.
UxDataArray.plot.line([backend])	Wrapper for hvplot.line()
UxDataArray.plot.scatter([backend])	Wrapper for hvplot.scatter()

Subsetting

See also

Subsetting User Guide Section

Grid

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_box(lon_bounds, lat_bounds)	Subsets an unstructured grid between two latitude and longitude points which form a bounding box.
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.constant_latitude(lat[, ...])	Extracts a subset of the grid by selecting all faces that intersect with a specified line of constant latitude.
Grid.subset.constant_longitude(lon[, ...])	Extracts a subset of the grid by selecting all faces that intersect with a specified line of constant longitude.
Grid.subset.constant_latitude_interval(lats)	Extracts a subset of the grid by selecting all faces that are within a specified latitude interval.
Grid.subset.constant_longitude_interval(lons)	Extracts a subset of the grid by selecting all faces that are within a specified longitude interval.

UxDataArray

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_box(lon_bounds, ...)	Subsets an unstructured grid between two latitude and longitude points which form a bounding box.
UxDataArray.subset.bounding_circle(...[, ...])	Subsets an unstructured grid by returning all elements within some radius (in degrees) from a center coord.
UxDataArray.subset.constant_latitude(lat[, ...])	Extracts a subset of the data array across a line of constant-latitude.
UxDataArray.subset.constant_longitude(lon[, ...])	Extracts a subset of the data array across a line of constant-longitude.
UxDataArray.subset.constant_latitude_interval(lats)	Extracts a subset of data by selecting all faces that are within a specified latitude interval.
UxDataArray.subset.constant_longitude_interval(lons)	Extracts a subset of data by selecting all faces that are within a specified longitude interval.

Cross Sections

See also

Cross Sections User Guide Section

UxDataArray.cross_section()

Extracts a cross-section sampled along an arbitrary great-circle arc (GCA) or line of constant latitude/longitude.

Remapping

See also

Remapping User Guide Section

UxDataArray

UxDataArray.remap()	Expose remapping methods on UxDataArray and UxDataset objects.
UxDataArray.remap.nearest_neighbor(...[, ...])	Perform nearest-neighbor remapping.
UxDataArray.remap.inverse_distance_weighted(...)	Perform inverse-distance-weighted (IDW) remapping.
UxDataArray.remap.bilinear(destination_grid)	Perform bilinear remapping.

UxDataset

UxDataset.remap()	Expose remapping methods on UxDataArray and UxDataset objects.
UxDataset.remap.nearest_neighbor(...[, remap_to])	Perform nearest-neighbor remapping.
UxDataset.remap.inverse_distance_weighted(...)	Perform inverse-distance-weighted (IDW) remapping.
UxDataset.remap.bilinear(destination_grid[, ...])	Perform bilinear remapping.

Mathematical Operators

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

Dual Mesh Construction

Grid.get_dual([check_duplicate_nodes])	Compute the dual for a grid, which constructs a new grid centered around the nodes, where the nodes of the primal become the face centers of the dual, and the face centers of the primal become the nodes of the dual.
UxDataArray.get_dual()	Compute the dual mesh for a data array, returns a new data array object.
UxDataset.get_dual()	Compute the dual mesh for a dataset, returns a new dataset object.

Aggregations

Topological

Topological aggregations apply an aggregation (i.e. averaging) on a per-element basis. For example, instead of computing the average across all values, we can compute the average of all the nodes that surround each face and store the result on each face.

See also

Topological Aggregations User Guide Section

UxDataArray.topological_mean(destination, ...)	Performs a topological mean aggregation.
UxDataArray.topological_min([destination])	Performs a topological min aggregation.
UxDataArray.topological_max([destination])	Performs a topological max aggregation.
UxDataArray.topological_median([destination])	Performs a topological median aggregation.
UxDataArray.topological_std([destination])	Performs a topological std aggregation.
UxDataArray.topological_var([destination])	Performs a topological var aggregation.
UxDataArray.topological_sum([destination])	Performs a topological sum aggregation.
UxDataArray.topological_prod([destination])	Performs a topological prod aggregation.
UxDataArray.topological_all([destination])	Performs a topological all aggregation.
UxDataArray.topological_any([destination])	Performs a topological any aggregation.

Zonal Average

UxDataArray.zonal_mean([lat])

Compute averages along lines of constant latitude.

Weighted

UxDataArray.weighted_mean([weights])

Computes a weighted mean.

Spherical Geometry

Intersections

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

Arcs

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

Accurate Computing

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.