swn.SurfaceWaterNetwork.pair_segments_frame#

SurfaceWaterNetwork.pair_segments_frame(value, value_out=None, name=None, method='continuous')#

Generate a DataFrame of paired values for top/bottom of segments.

The first value applies to the top of each segment, and the bottom value is determined from the top of the value it connects to.

Parameters:
valuescalar, list, dict or pandas.Series

Value to assign to the upstream or top end of each segment. If value is a Series, it is checked to ensure it is has the same index as segments. Otherwise value as a scalar, list or dict is cast as a Series with segments.index.

value_outNone (default), scalar, dict or pandas.Series

If None (default), the value used for the bottom is determined using method. Otherwise, value_out can be directly specified with a Series or dict, indexed by segnum. If value_out is a scalar, it is cast as a Series with outlets.index. This option is normally specified for outlets, but will overwrite any other values determined by method.

namestr, default None

Base name used for the column names, if provided. For example, name="foo" will create columns “foo1” and “foo2”.

methodstr, default “continuous”

This option determines how value_out values should be determined, if not specified. Choose one of:

  • continuous (default): downstream value is evaluated to be the same as the upstream value it connects to. This allows a continuous network of values along the networks, such as elevation.

  • constant : value_out is the same as value.

  • additive : downstream value is evaluated to be a fraction of tributaries that add to the upstream value it connects to. Proportions of values for each tributary are preserved, but lengths of segments are ignored.

Returns:
pandas.DataFrame

Resulting DataFrame has two columns for top (1) and bottom (2) of each 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)
>>> n.pair_segments_frame([3, 4, 5])
   1  2
0  3  3
1  4  3
2  5  3
>>> n.pair_segments_frame([4.0, 3.0, 5.0], {0: 6.0}, name="var")
   var1  var2
0   4.0   6.0
1   3.0   4.0
2   5.0   4.0
>>> n.pair_segments_frame([10.0, 2.0, 3.0], name="add",
...                       method="additive")
   add1  add2
0  10.0  10.0
1   2.0   4.0
2   3.0   6.0