swn.SurfaceWaterNetwork.locate_geoms#

SurfaceWaterNetwork.locate_geoms(geom, *, override={}, min_stream_order=None, downstream_bias=0.0)#

Return GeoDataFrame of data associated in finding geometies.

Parameters:

geomGeoSeries: Geometry series input to process, e.g. stream gauge locations, bridges or building footprints.
overridedict, optional: Override matches, where key is the index from geom, and the value is segnum. If value is None, no match is performed.
min_stream_orderint, default None: Finds stream segments with a minimum stream order.
downstream_biasfloat, default 0.0: A bias used for spatial location matching on nearest segments that increase the likelihood of finding downstream segments if positive, and upstream segments if negative. Valid range is -1.0 to 1.0. Default 0.0 is no bias, matching to the closest segment.

Returns:

geopandas.GeoDataFrame: Resulting GeoDataFrame has columns geometry (always LineString), method (override, catchment or nearest), segnum, seg_ndist (normalized distance along segment), and dist_to_seg (distance to segment).

Notes

Seveal methods are used to pair the geometry with one segnum:

empty: geometry cannot be matched to anything. Use override with None value to suppress warning.

override: explicit pairs are provided as a dict, with key for the geom index, and value with the segnum.

catchment: if catchments are part of the surface water network, find the catchment polygons that contain the geometries. Input polygons that intersect with more than one catchment are matched with the catchment with the largest intersection polygon area. If min_stream_order is specified, then a catchment downstream might be identified.

nearest: find the segment lines that are nearest to the input geometries. Input polygons that intersect with more than one segment are matched with the largest intersection line length.

It is advised that outputs are checked in a GIS to ensure correct matches. Any error can be corrected using an override entry.

The geometry returned by this method consists of two-coordinate line segments that represent the shortest distance between geom and the surface water network segment.

Examples

>>> import geopandas
>>> import swn
>>> lines = geopandas.GeoSeries.from_wkt([
...    "LINESTRING (60 100, 60  80)",
...    "LINESTRING (40 130, 60 100)",
...    "LINESTRING (70 130, 60 100)"])
>>> n = swn.SurfaceWaterNetwork.from_lines(lines)
>>> lines.index += 101
>>> obs_gs = geopandas.GeoSeries.from_wkt([
...    "POINT (56 103)",
...    "LINESTRING (58 90, 62 90)",
...    "POLYGON ((60 107, 59 113, 61 113, 60 107))",
...    "POINT (55 130)"])
>>> obs_gs.index += 11
>>> obs_match = n.locate_geoms(obs_gs, override={14: 2})
>>> obs_match[["method", "segnum", "seg_ndist", "dist_to_seg"]]
      method  segnum  seg_ndist  dist_to_seg
11   nearest       1   0.869231     1.664101
12   nearest       0   0.500000     0.000000
13   nearest       2   0.790000     2.213594
14  override       2   0.150000    14.230249