API Reference#

This page provides an auto-generated summary of xugrid’s API.

Xugrid also almost completely exposes the attributes and methods of xarray DataArrays and Datasets. Refer to the Xarray documentation.

Changelog

Top-level functions#

`open_dataarray`(args, *kwargs)	Open an DataArray from a file or file-like object containing a single data variable.
`open_dataset`(args, *kwargs)	Open and decode a dataset from a file or file-like object.
`open_mfdataset`(args, *kwargs)	Open multiple files as a single dataset.
`open_zarr`(args, *kwargs)	Load and decode a dataset from a Zarr store.
`full_like`()	Return a new object with the same shape and type as a given object.
`ones_like`()	Return a new object of ones with the same shape and type as a given dataarray or dataset.
`zeros_like`()	Return a new object of zeros with the same shape and type as a given dataarray or dataset.
`concat`()	Concatenate xarray objects along a new or existing dimension.
`merge`(objects[, compat, join, fill_value, ...])	Merge any number of xarray objects into a single Dataset as variables.
`merge_partitions`(partitions)	Merge topology and data, partitioned along UGRID dimensions, into a single UgridDataset.
`burn_vector_geometry`(gdf, like[, column, ...])	Burn vector geometries (points, lines, polygons) into a Ugrid2d mesh.
`polygonize`(uda)	Polygonize a UgridDataArray.

UgridDataArray#

`UgridDataArray`(obj, grid)
`UgridDataArray.ugrid`	UGRID Accessor.
`UgridDataArray.from_structured`(da[, x, y])	Create a UgridDataArray from a (structured) xarray DataArray.

UgridDataset#

`UgridDataset`([obj, grids])
`UgridDataset.ugrid`	UGRID Accessor.
`UgridDataset.from_geodataframe`(geodataframe)	Convert a geodataframe into the appropriate Ugrid topology and dataset.

UGRID Accessor#

These methods and attributes are available under the .ugrid attribute of a UgridDataArray or UgridDataset.

`UgridDatasetAccessor`(obj, grids)
`UgridDatasetAccessor.assign_node_coords`()	Assign node coordinates from the grid to the object.
`UgridDatasetAccessor.assign_edge_coords`()	Assign edge coordinates from the grid to the object.
`UgridDatasetAccessor.assign_face_coords`()	Assign face coordinates from the grid to the object.
`UgridDatasetAccessor.set_node_coords`(node_x, ...)	Given names of x and y coordinates of the nodes of an object, set them as the coordinates in the grid.
`UgridDatasetAccessor.grid`	Returns the single UGRID topology in this dataset.
`UgridDatasetAccessor.name`	Returns name of the single UGRID topology in this dataset.
`UgridDatasetAccessor.names`	Names of all the UGRID topologies in the dataset.
`UgridDatasetAccessor.topology`	Mapping from names to UGRID topologies.
`UgridDatasetAccessor.bounds`	Mapping from grid name to tuple containing `minx, miny, maxx, maxy` values of the grid's node coordinates for every grid in the dataset.
`UgridDatasetAccessor.total_bounds`	Returns a tuple containing `minx, miny, maxx, maxy` values for the bounds of the dataset as a whole.
`UgridDatasetAccessor.crs`	The Coordinate Reference System (CRS) represented as a `pyproj.CRS` object.
`UgridDatasetAccessor.rename`(...)	Give a new name to the UGRID topology and update the associated coordinate and dimension names in the Dataset.
`UgridDatasetAccessor.set_crs`([crs, epsg, ...])	Set the Coordinate Reference System (CRS) of a UGRID topology.
`UgridDatasetAccessor.to_crs`([crs, epsg, ...])	Transform geometries to a new coordinate reference system.
`UgridDatasetAccessor.sel`([x, y])
`UgridDatasetAccessor.sel_points`(x, y)	Select points in the unstructured grid.
`UgridDatasetAccessor.rasterize`(resolution)	Rasterize all face data on 2D unstructured grids by sampling.
`UgridDatasetAccessor.rasterize_like`(other)	Rasterize unstructured all face data on 2D unstructured grids by sampling on the x and y coordinates of `other`.
`UgridDatasetAccessor.to_periodic`()	Convert every grid to a periodic grid, where the rightmost boundary shares its nodes with the leftmost boundary.
`UgridDatasetAccessor.to_nonperiodic`(xmax)	Convert the grid from a periodic grid (where the rightmost boundary shares its nodes with the leftmost boundary) to an aperiodic grid, where the leftmost nodes are separate from the rightmost nodes.
`UgridDatasetAccessor.intersect_line`(start, end)	Intersect a line with the grid of this data, and fetch the values of the intersected faces.
`UgridDatasetAccessor.intersect_linestring`(...)	Intersect the grid along a collection of linestrings.
`UgridDatasetAccessor.partition`(n_part)	Partition a grid into a given number of parts.
`UgridDatasetAccessor.partition_by_label`(labels)	Partition a grid by labels.
`UgridDatasetAccessor.reindex_like`(other[, ...])	Conform this object to match the topology of another object.
`UgridDatasetAccessor.to_geodataframe`([dim_order])	Convert data and topology of one facet (node, edge, face) of the grid to a geopandas GeoDataFrame.
`UgridDatasetAccessor.to_dataset`([...])	Convert this UgridDataset into a standard xarray.Dataset.
`UgridDatasetAccessor.to_netcdf`(args, *kwargs)	Write dataset contents to a UGRID compliant netCDF file.
`UgridDatasetAccessor.to_zarr`(args, *kwargs)	Write dataset contents to a UGRID compliant Zarr file.
`UgridDataArrayAccessor`(obj, grid)	This "accessor" makes operations using the UGRID topology available via the `.ugrid` attribute for UgridDataArrays and UgridDatasets.
`UgridDataArrayAccessor.assign_node_coords`()	Assign node coordinates from the grid to the object.
`UgridDataArrayAccessor.assign_edge_coords`()	Assign edge coordinates from the grid to the object.
`UgridDataArrayAccessor.assign_face_coords`()	Assign face coordinates from the grid to the object.
`UgridDataArrayAccessor.set_node_coords`(...)	Given names of x and y coordinates of the nodes of an object, set them as the coordinates in the grid.
`UgridDataArrayAccessor.grids`	The UGRID topology of this DataArry, as a list.
`UgridDataArrayAccessor.name`	Name of the UGRID topology of this DataArray.
`UgridDataArrayAccessor.names`	Name of the UGRID topology, as a list.
`UgridDataArrayAccessor.topology`	Mapping from name to UGRID topology.
`UgridDataArrayAccessor.bounds`	Mapping from grid name to tuple containing `minx, miny, maxx, maxy` values of the grid's node coordinates.
`UgridDataArrayAccessor.total_bounds`	Returns a tuple containing `minx, miny, maxx, maxy` values of the grid's node coordinates.
`UgridDataArrayAccessor.crs`	The Coordinate Reference System (CRS) represented as a `pyproj.CRS` object.
`UgridDataArrayAccessor.rename`(name)	Give a new name to the UGRID topology and update the associated coordinate and dimension names in the DataArray.
`UgridDataArrayAccessor.set_crs`([crs, epsg, ...])	Set the Coordinate Reference System (CRS) of a UGRID topology.
`UgridDataArrayAccessor.to_crs`([crs, epsg])	Transform geometries to a new coordinate reference system.
`UgridDataArrayAccessor.sel`([x, y])	Return a new object, a subselection in the UGRID x and y coordinates.
`UgridDataArrayAccessor.sel_points`(x, y)	Select points in the unstructured grid.
`UgridDataArrayAccessor.intersect_line`(start, end)	Intersect a line with the grid of this data, and fetch the values of the intersected faces.
`UgridDataArrayAccessor.intersect_linestring`(...)	Intersect the grid along a collection of linestrings.
`UgridDataArrayAccessor.partition`(n_part)	Partition a grid into a given number of parts.
`UgridDataArrayAccessor.partition_by_label`(labels)	Partition a grid by labels.
`UgridDataArrayAccessor.rasterize`(resolution)	Rasterize unstructured grid by sampling.
`UgridDataArrayAccessor.rasterize_like`(other)	Rasterize unstructured grid by sampling on the x and y coordinates of `other`.
`UgridDataArrayAccessor.reindex_like`(other[, ...])	Conform this object to match the topology of another object.
`UgridDataArrayAccessor.to_periodic`()	Convert this grid to a periodic grid, where the rightmost boundary shares its nodes with the leftmost boundary.
`UgridDataArrayAccessor.to_nonperiodic`(xmax)	Convert this grid from a periodic grid (where the rightmost boundary shares its nodes with the leftmost boundary) to an aperiodic grid, where the leftmost nodes are separate from the rightmost nodes.
`UgridDataArrayAccessor.to_geodataframe`([...])	Convert data and topology of one facet (node, edge, face) of the grid to a geopandas GeoDataFrame.
`UgridDataArrayAccessor.binary_dilation`([...])	Binary dilation can be used on a boolean array to expand the "shape" of features.
`UgridDataArrayAccessor.binary_erosion`([...])	Binary erosion can be used on a boolean array to shrink the "shape" of features.
`UgridDataArrayAccessor.connected_components`()	Every edge or face is given a component number.
`UgridDataArrayAccessor.reverse_cuthill_mckee`()	Reduces bandwith of the connectivity matrix.
`UgridDataArrayAccessor.laplace_interpolate`([...])	Fill gaps in `data` (`np.nan` values) using Laplace interpolation.
`UgridDataArrayAccessor.to_dataset`([...])	Convert this UgridDataArray or UgridDataset into a standard xarray.Dataset.
`UgridDataArrayAccessor.to_netcdf`(args, *kwargs)	Write dataset contents to a UGRID compliant netCDF file.
`UgridDataArrayAccessor.to_zarr`(args, *kwargs)	Write dataset contents to a UGRID compliant Zarr file.

Snapping#

Snapping is the process of moving nodes/edges/faces to other nodes/edges/faces if within a certain range.

snap_to_grid(lines, grid, max_snap_distance)

Snap a collection of lines to a grid.

Regridding#

Regridding is the process of converting gridded data from one grid to another grid. Xugrid provides tools for 2D and 3D regridding of structured gridded data, represented as xarray objects, as well as (layered) unstructured gridded data, represented as xugrid objects.

`BarycentricInterpolator`(source, target)	The BaryCentricInterpolator searches the centroid of every face of the target grid in the source grid.
`CentroidLocatorRegridder`(source, target)	The CentroidLocatorRegridded regrids by searching the source grid for the centroids of the target grid.
`OverlapRegridder`(source, target[, method])	The OverlapRegridder regrids by computing which target faces overlap with which source faces.
`RelativeOverlapRegridder`(source, target[, ...])	The RelativeOverlapRegridder regrids by computing which target faces overlap with which source faces.

Plotting#

These methods are also available under the .ugrid.plot attribute of a UgridDataArray.

`plot.contour`(topology, darray, **kwargs)	Create a contour plot of a 2D UgridDataArray.
`plot.contourf`(topology, darray, **kwargs)	Create a filled contour plot of a 2D UgridDataArray.
`plot.imshow`(topology, darray, **kwargs)	Image plot of 2D DataArray.
`plot.line`(topology, darray, **kwargs)	None
`plot.pcolormesh`(topology, darray, **kwargs)	Create a pseudocolor mesh plot of a 2D UgridDataArray.
`plot.scatter`(topology, darray, **kwargs)	None
`plot.surface`(topology, darray, **kwargs)	Create a surface plot of a 2D UgridDataArray.
`plot.tripcolor`(topology, darray, **kwargs)	None

UGRID1D Topology#

`Ugrid1d`(node_x, node_y, fill_value[, ...])	This class stores the topological data of a "1-D unstructured grid": a collection of connected line elements, such as a river network.
`Ugrid1d.topology_dimension`	1
`Ugrid1d.dimensions`
`Ugrid1d.attrs`
`Ugrid1d.n_node`	Number of nodes (vertices) in the UGRID topology
`Ugrid1d.node_dimension`	Name of node dimension
`Ugrid1d.node_coordinates`	Coordinates (x, y) of the nodes (vertices)
`Ugrid1d.set_node_coords`(node_x, node_y, obj)	Given names of x and y coordinates of the nodes of an object, set them as the coordinates in the grid.
`Ugrid1d.assign_node_coords`(obj)	Assign node coordinates from the grid to the object.
`Ugrid1d.assign_edge_coords`(obj)	Assign node coordinates from the grid to the object.
`Ugrid1d.n_edge`	Number of edges in the UGRID topology
`Ugrid1d.edge_dimension`	Name of edge dimension
`Ugrid1d.edge_coordinates`	Centroid (x,y) coordinates of every edge in the UGRID topology
`Ugrid1d.edge_x`	x-coordinate of every edge in the UGRID topology
`Ugrid1d.edge_y`	y-coordinate of every edge in the UGRID topology
`Ugrid1d.bounds`	xmin, ymin, xmax, ymax
`Ugrid1d.edge_bounds`	Returns a numpy array with columns `minx, miny, maxx, maxy`, describing the bounds of every edge in the grid.
`Ugrid1d.node_edge_connectivity`	Node to edge connectivity.
`Ugrid1d.node_node_connectivity`	Node to node connectivity.
`Ugrid1d.copy`()	Create a deepcopy.
`Ugrid1d.rename`(name[, return_name_dict])	Create a new grid with all variables named according to the default naming conventions.
`Ugrid1d.isel`([indexers, return_index])	Select based on node or edge.
`Ugrid1d.sel`(obj, x, y)	Select a selection of edges, based on edge centroids.
`Ugrid1d.topology_subset`(edge_index[, ...])	Create a new UGRID1D topology for a subset of this topology.
`Ugrid1d.merge_partitions`(grids)	Merge grid partitions into a single whole.
`Ugrid1d.topological_sort_by_dfs`()	Return an array of vertices in topological order.
`Ugrid1d.contract_vertices`(indices)	Return a simplified network topology by removing all nodes that are not listed in `indices`.
`Ugrid1d.reindex_like`(other, obj[, tolerance])	Conform a DataArray or Dataset to match the topology of another Ugrid1D topology.
`Ugrid1d.from_meshkernel`(mesh[, name, ...])	Create a 1D UGRID topology from a MeshKernel Mesh1d object.
`Ugrid1d.mesh`	Create if needed, and return meshkernel Mesh1d object.
`Ugrid1d.meshkernel`	Create if needed, and return meshkernel MeshKernel instance.
`Ugrid1d.set_crs`([crs, epsg, allow_override])	Set the Coordinate Reference System (CRS) of a UGRID topology.
`Ugrid1d.to_crs`([crs, epsg])	Transform geometries to a new coordinate reference system.
`Ugrid1d.from_dataset`(dataset[, topology])	Extract the 1D UGRID topology information from an xarray Dataset.
`Ugrid1d.to_dataset`([other, optional_attributes])
`Ugrid1d.from_geodataframe`(geodataframe)	Convert geodataframe of linestrings into a UGRID1D topology.
`Ugrid1d.from_shapely`(geometry[, crs])	Convert an array of shapely linestrings to UGRID1D topology.
`Ugrid1d.to_shapely`(dim)	Convert UGRID topology to shapely objects.
`Ugrid1d.plot`(**kwargs)	Plot the edges of the mesh.

UGRID2D Topology#

`Ugrid2d`(node_x, node_y, fill_value, ...[, ...])	This class stores the topological data of a 2-D unstructured grid.
`Ugrid2d.topology_dimension`	2
`Ugrid2d.dimensions`
`Ugrid2d.attrs`
`Ugrid2d.n_node`	Number of nodes (vertices) in the UGRID topology
`Ugrid2d.node_dimension`	Name of node dimension
`Ugrid2d.node_coordinates`	Coordinates (x, y) of the nodes (vertices)
`Ugrid2d.set_node_coords`(node_x, node_y, obj)	Given names of x and y coordinates of the nodes of an object, set them as the coordinates in the grid.
`Ugrid2d.assign_node_coords`(obj)	Assign node coordinates from the grid to the object.
`Ugrid2d.assign_edge_coords`(obj)	Assign node coordinates from the grid to the object.
`Ugrid2d.assign_face_coords`(obj)	Assign face coordinates from the grid to the object.
`Ugrid2d.n_edge`	Number of edges in the UGRID topology
`Ugrid2d.edge_dimension`	Name of edge dimension
`Ugrid2d.edge_coordinates`	Centroid (x,y) coordinates of every edge in the UGRID topology
`Ugrid2d.edge_x`	x-coordinate of every edge in the UGRID topology
`Ugrid2d.edge_y`	y-coordinate of every edge in the UGRID topology
`Ugrid2d.n_face`	Return the number of faces in the UGRID2D topology.
`Ugrid2d.face_dimension`	Return the name of the face dimension.
`Ugrid2d.face_coordinates`	Centroid (x, y) of every face.
`Ugrid2d.centroids`	Centroid (x, y) of every face.
`Ugrid2d.circumcenters`	Circumenter (x, y) of every face; only works for fully triangular grids.
`Ugrid2d.area`	Area of every face.
`Ugrid2d.perimeter`	Perimeter length of every face.
`Ugrid2d.face_x`	x-coordinate of centroid of every face
`Ugrid2d.face_y`	y-coordinate of centroid of every face
`Ugrid2d.bounds`	xmin, ymin, xmax, ymax
`Ugrid2d.edge_bounds`	Returns a numpy array with columns `minx, miny, maxx, maxy`, describing the bounds of every edge in the grid.
`Ugrid2d.face_bounds`	Returns a numpy array with columns `minx, miny, maxx, maxy`, describing the bounds of every face in the grid.
`Ugrid2d.bounding_polygon`()	Construct the bounding polygon of the grid.
`Ugrid2d.node_node_connectivity`	Node to node connectivity.
`Ugrid2d.node_edge_connectivity`	Node to edge connectivity.
`Ugrid2d.node_face_connectivity`	Node to face connectivity.
`Ugrid2d.edge_node_connectivity`	Edge to node connectivity.
`Ugrid2d.face_edge_connectivity`	Face to edge connectivity.
`Ugrid2d.face_face_connectivity`	Face to face connectivity.
`Ugrid2d.validate_edge_node_connectivity`()	Mark valid edges, by comparing face_node_connectivity and edge_node_connectivity.
`Ugrid2d.exterior_edges`	Get all exterior edges, i.e. edges with no other face.
`Ugrid2d.exterior_faces`	Get all exterior faces, i.e. faces with an unshared edge.
`Ugrid2d.copy`()	Create a deepcopy.
`Ugrid2d.rename`(name[, return_name_dict])	Create a new grid with all variables named according to the default naming conventions.
`Ugrid2d.triangulate`()	Triangulate this UGRID2D topology, breaks more complex polygons down into triangles.
`Ugrid2d.triangulation`	Triangulation of the UGRID2D topology.
`Ugrid2d.voronoi_topology`	Centroidal Voronoi tesselation of this UGRID2D topology.
`Ugrid2d.centroid_triangulation`	Triangulation of centroidal voronoi tesselation.
`Ugrid2d.tesselate_centroidal_voronoi`([...])	Create a centroidal Voronoi tesselation of this UGRID2D topology.
`Ugrid2d.tesselate_circumcenter_voronoi`([...])	Create a circumcenter Voronoi tesselation of this UGRID2D topology.
`Ugrid2d.reverse_cuthill_mckee`([dimension])	Reduces bandwith of the connectivity matrix.
`Ugrid2d.compute_barycentric_weights`(points)	Find in which face the points are located, and compute the barycentric weight for every vertex of the face.
`Ugrid2d.isel`([indexers, return_index])	Select based on node, edge, or face.
`Ugrid2d.sel`(obj[, x, y])	Find selection in the UGRID x and y coordinates.
`Ugrid2d.sel_points`(obj, x, y)	Select points in the unstructured grid.
`Ugrid2d.intersect_line`(obj, start, end)	Intersect a line with this grid, and fetch the values of the intersected faces.
`Ugrid2d.intersect_linestring`(obj, linestring)	Intersect linestrings with this grid, and fetch the values of the intersected faces.
`Ugrid2d.celltree`	Initializes the celltree if needed, and returns celltree.
`Ugrid2d.locate_points`(points)	Find in which face points are located.
`Ugrid2d.intersect_edges`(edges)	Find in which face edges are located and compute the intersection with the face edges.
`Ugrid2d.locate_bounding_box`(xmin, ymin, ...)	Find which faces are located in the bounding box.
`Ugrid2d.rasterize`(resolution[, bounds])	Rasterize unstructured grid by sampling.
`Ugrid2d.rasterize_like`(x, y)	Rasterize unstructured grid by sampling on the x and y coordinates.
`Ugrid2d.to_periodic`([obj])	Convert this grid to a periodic grid, where the rightmost nodes are equal to the leftmost nodes.
`Ugrid2d.to_nonperiodic`(xmax[, obj])	Convert this grid from a periodic grid (where the rightmost boundary shares its nodes with the leftmost boundary) to an aperiodic grid, where the leftmost nodes are separate from the rightmost nodes.
`Ugrid2d.topology_subset`(face_index[, ...])	Create a new UGRID1D topology for a subset of this topology.
`Ugrid2d.label_partitions`(n_part)	Generate partition labesl for this grid topology using METIS: KarypisLab/METIS
`Ugrid2d.partition`(n_part)	Partition this grid topology using METIS: KarypisLab/METIS
`Ugrid2d.merge_partitions`(grids)	Merge grid partitions into a single whole.
`Ugrid2d.reindex_like`(other, obj[, tolerance])	Conform a DataArray or Dataset to match the topology of another Ugrid2D topology.
`Ugrid2d.from_meshkernel`(mesh[, name, ...])	Create a 2D UGRID topology from a MeshKernel Mesh2d object.
`Ugrid2d.mesh`	Create if needed, and return meshkernel Mesh2d object.
`Ugrid2d.meshkernel`	Create if needed, and return meshkernel MeshKernel instance.
`Ugrid2d.set_crs`([crs, epsg, allow_override])	Set the Coordinate Reference System (CRS) of a UGRID topology.
`Ugrid2d.to_crs`([crs, epsg])	Transform geometries to a new coordinate reference system.
`Ugrid2d.from_dataset`(dataset[, topology])	Extract the 2D UGRID topology information from an xarray Dataset.
`Ugrid2d.to_dataset`([other, optional_attributes])
`Ugrid2d.from_geodataframe`(geodataframe)	Convert a geodataframe of polygons to UGRID2D topology.
`Ugrid2d.from_structured`(data[, x, y])	Create a Ugrid2d topology from an axis-aligned rectilinear structured topology.
`Ugrid2d.from_structured_multicoord`(data, x, y)	Create a Ugrid2d topology from a structured topology, including rotated and (approximated) curvilinear topologies.
`Ugrid2d.from_structured_bounds`(x_bounds, ...)	Create a Ugrid2d topology from a structured topology based on 1D bounds.
`Ugrid2d.from_structured_intervals1d`(...)	Create a Ugrid2d topology from a structured topology based on 1D intervals.
`Ugrid2d.from_structured_intervals2d`(...)	Create a Ugrid2d topology from a structured topology based on 2D intervals.
`Ugrid2d.from_shapely`(geometry[, crs])	Convert an array of shapely polygons to UGRID2D topology.
`Ugrid2d.to_shapely`(dim)	Convert UGRID topology to shapely objects.
`Ugrid2d.plot`(**kwargs)	Plot the edges of the mesh.

UGRID Roles Accessor#

`UgridRolesAccessor`(ds)	Xarray Dataset "accessor" to retrieve the names of UGRID variables.
`UgridRolesAccessor.topology`	Get the names of the topology dummy variables, marked by a CF-role of `mesh_topology`.
`UgridRolesAccessor.connectivity`	Get the names of the variables containing the UGRID connectivity data.
`UgridRolesAccessor.coordinates`	Get the names of the coordinate variables from the topology attributes.
`UgridRolesAccessor.dimensions`	Get the dimension names from the topology attributes and infer them from connectivity arrays or coordinates.