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.

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.

earcut_triangulate_polygons(polygons[, column])

Break down polygons using mapbox_earcut, and create a mesh from the resulting triangles.

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.

UgridDataArray.from_data(data, grid, facet)

Create a UgridDataArray from a grid and a 1D array of values.

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.interpolate_na([...])

Fill in NaNs by interpolating.

UgridDataArrayAccessor.laplace_interpolate([...])

Fill in NaNs by 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_nodes(x, y, max_snap_distance)

Snap neigbhoring vertices together that are located within a maximum snapping distance from each other.

snap_to_grid(lines, grid, max_snap_distance)

Snap a collection of lines to a grid.

create_snap_to_grid_dataframe(lines, grid, ...)

Create a dataframe required to snap line geometries to a Ugrid2d topology.

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.dims

node dimension, edge dimension.

Ugrid1d.sizes

Ugrid1d.attrs

Ugrid1d.coords

Dictionary for grid coordinates.

Ugrid1d.fill_value

Fill value for UGRID connectivity arrays.

Ugrid1d.start_index

Start index for UGRID connectivity arrays.

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.get_coordinates(dim)

Return the coordinates for the specified UGRID dimension.

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.get_connectivity_matrix(dim, xy_weights)

Return the connectivity matrix for the specified UGRID dimension.

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.create_data_array(data, facet)

Create a UgridDataArray from this grid and a 1D array of values.

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.dims

node dimension, edge dimension, face_dimension.

Ugrid2d.sizes

Ugrid2d.attrs

Ugrid2d.coords

Dictionary for grid coordinates.

Ugrid2d.fill_value

Fill value for UGRID connectivity arrays.

Ugrid2d.start_index

Start index for UGRID connectivity arrays.

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.get_coordinates(dim)

Return the coordinates for the specified UGRID dimension.

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.get_connectivity_matrix(dim, xy_weights)

Return the connectivity matrix for the specified UGRID dimension.

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.earcut_triangulate_polygons(polygons)

Break down polygons using mapbox_earcut, and create a mesh from the resulting triangles.

Ugrid2d.create_data_array(data, facet)

Create a UgridDataArray from this grid and a 1D array of values.

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.