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_multigrid(grid_filename_or_obj[, ...])	Open a multi-grid SCRIP file and construct Grid objects.
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)

Tutorial

tutorial.available_datasets()	Return the names of available tutorial datasets.
tutorial.describe_dataset(name)	Return a short description for a tutorial dataset.
tutorial.file_path(name[, component])	Return the local path for a tutorial dataset file.
tutorial.file_paths(name)	Return the local paths for a multi-file tutorial dataset.
tutorial.open_grid(name, **kwargs)	Open the grid file for a tutorial dataset.
tutorial.open_dataset(name, **kwargs)	Open a tutorial dataset with its associated grid.
tutorial.open_mfdataset(name, **kwargs)	Open a multi-file tutorial dataset with its associated grid.

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_face_vertices(face_vertices[, latlon])	Constructs a Grid object from user-defined face vertices.
Grid.from_file(filename[, backend])	Constructs a Grid object from a using the read_file method with a specified backend.
Grid.from_healpix(zoom[, pixels_only, nest])	Constructs a Grid object representing a given HEALPix zoom level.
Grid.from_points(points[, method, ...])	Create a grid from unstructured points.
Grid.from_structured([ds, lon, lat, tol])	Converts a structured xarray.Dataset or longitude and latitude coordinates into an unstructured uxarray.Grid.
Grid.from_topology(node_lon, node_lat, ...)	Constructs a Grid object from user-defined topology variables provided in the UGRID conventions.

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.

Indexing

Grid.get_edges_at_constant_latitude(lat[, ...])	Identifies the indices of edges that intersect with a line of constant latitude.
Grid.get_edges_at_constant_longitude(lon[, ...])	Identifies the indices of edges that intersect with a line of constant longitude.
Grid.get_faces_at_constant_latitude(lat)	Identifies the indices of faces that intersect with a line of constant latitude.
Grid.get_faces_at_constant_longitude(lon)	Identifies the indices of faces that intersect with a line of constant longitude.
Grid.get_faces_between_latitudes(lats)	Identifies the indices of faces that are strictly between two lines of constant latitude.
Grid.get_faces_between_longitudes(lons)	Identifies the indices of faces that are strictly between two lines of constant longitude.
Grid.get_faces_containing_point(points[, ...])	Identify which grid faces contain the given point(s).
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.coordinates	Names of all coordinate variables.
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.coordinates	Names of all coordinate variables.
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.antimeridian_face_indices	Indices of faces that touch or cross the antimeridian.
Grid.bounds	Spherical bounds of each face in degrees
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.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.face_areas	Area of each face.
Grid.face_bounds_lon	Longitude bounds for each face in degrees.
Grid.face_bounds_lat	Latitude bounds for each face in degrees.
Grid.is_subset	Returns True if the Grid is a subset, 'False' otherwise.
Grid.global_sphere_coverage	Boolean indicated whether the Grid completely covers the unit sphere (i.e. contains no holes).
Grid.max_face_radius	Maximum Euclidean distance from each face center to its nodes.
Grid.partial_sphere_coverage	Boolean indicated whether the Grid partial covers the unit sphere (i.e. contains holes).
Grid.sphere_radius	Physical sphere radius from the source grid (e.g., Earth's radius for MPAS ocean grids).
Grid.triangular	Boolean indicated whether the Grid is strictly composed of triangular faces.

Attributes

Grid.attrs

Dictionary of parsed attributes from the source grid.

Methods

Grid.chunk([n_node, n_edge, n_face])	Converts all arrays to dask arrays with given chunks across grid dimensions in-place.
Grid.copy()	Returns a deep copy of this grid.
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.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_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.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).
Grid.normalize_cartesian_coordinates()	Normalizes Cartesian coordinates.
Grid.validate([check_duplicates])	Validates the current Grid, checking for Duplicate Nodes, Present Connectivity, and Non-Zero Face Areas.

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.

Dual Mesh Construction

UxDataArray.get_dual()

Compute the dual mesh for a data array, returns a new data array object.

Selection & Indexing

UxDataArray.isel([indexers, drop, ...])	Return a new DataArray whose data is given by selecting indexes along the specified dimension(s).
UxDataArray.where(cond[, other, drop])	Filter elements from this object according to a condition.

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_dataframe(dataframe)	Override to make the result a uxarray.UxDataset class.
UxDataset.from_dict(data, **kwargs)	Override to make the result a uxarray.UxDataset class.
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.
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

Dual Mesh Construction

UxDataset.get_dual()

Compute the dual mesh for a dataset, returns a new dataset object.

Grid Accessor

UxDataset.uxgrid

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

Attributes

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.

Selection & Indexing

UxDataset.isel([indexers, drop, ...])	Returns a new dataset with each array indexed along the specified dimension(s).
UxDataset.sel([indexers, method, tolerance, ...])	Returns a new dataset with each array indexed by tick labels along the specified dimension(s).
UxDataset.where(cond[, other, drop])	Filter elements from this object according to a condition.

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_linecollection([periodic_elements, ...])	Constructs a matplotlib.collections.LineCollection` consisting of lines representing the edges of the current unstructured grid.
Grid.to_polycollection([periodic_elements, ...])	Constructs a matplotlib.collections.PolyCollection` consisting of polygons representing the faces 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_dataset([dim, name, ...])	Convert a UxDataArray to a UxDataset.
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([...])	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, *[, pixel_ratio, ...])	Rasterizes a data variable stored on the faces of an unstructured grid onto the pixels of the provided Cartopy GeoAxes.
UxDataArray.to_xarray()

UxDataset

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

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(...[, ...])	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.curl(other, **kwargs)	Computes the curl of a vector field.
UxDataArray.difference([destination])	Computes the absolute difference of a data variable.
UxDataArray.divergence(other, **kwargs)	Computes the divergence of the vector field defined by this UxDataArray and other.
UxDataArray.gradient(**kwargs)	Computes the gradient of a data variable.
UxDataArray.integrate([quadrature_rule, order])	Computes the integral of a data variable.

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.

Azimuthal

Azimuthal aggregations apply an aggregation (i.e. averaging) along circles of constant great-circle distance from a specified point on the sphere.

UxDataArray.azimuthal_mean(center_coord, ...)

Compute averages along circles of constant great-circle distance from a point.

Zonal Average

UxDataArray.zonal_average([lat, conservative])	Alias of zonal_mean; prefer zonal_mean for primary API.
UxDataArray.zonal_mean([lat, conservative])	Compute non-conservative or conservative averages of a face-centered variable along lines of constant latitude or latitude bands.

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.