stormcatchments.Network

A stormcatchments.Network represents a stormwater network, which consists flow sinks (where water can enter a stormwater system), flow sources (where water can exit a stormwater system), and the spatial connectivity of these points.

class stormcatchments.network.Network(storm_lines: geopandas.GeoDataFrame, storm_pts: geopandas.GeoDataFrame, coord_decimals: int = 3, type_column: Optional[str] = None, sink_types: Optional[list] = None, source_types: Optional[list] = None)

Parses through stormwater infrastructure point and line data to generate directional graphs represeting the connectivity of the infrastructure network.

Methods

add_edges(direction[, verbose])	Utilize user storm line data to add edges (and their nodes) to self.G in one or both directions
draw([extent, ax, add_basemap])	Draw the Graph using the geographic coordinates of each node
get_inlet_points(catchment)	Get GeoDataFrame of all the infrastructure points outside the catchment that bring flow into the catchment.
get_outlet(pt_idx)	Get Index of the outlet for a given storm_pt whose coordinates exist in the graph
get_outlet_points(catchment)	Get GeoDataFrame of all the infrastructure points within the catchment that bring flow out of the current catchment.
has_StormPoint(pt)	Check if self.G contains a given StormPoint
resolve_directions([method, verbose])	Attempt to resolve directions for all edges within the graph
resolve_from_sources([verbose])	Resolve directions of all edges within the graph by traversing subgraphs upstream from each flow source
resolve_upstream(source_pt)	Initializiton function for traverse_upstream, prepares arguments for depth-first search
to_StormPoint(pt)	Converts point data from various types to a StormPoint namedtuple
traverse_upstream(coords, visited)	Revise direction of edges via recursive depth-first search, starting from an outlet then traverse the graph "upstream".

__init__(storm_lines: geopandas.GeoDataFrame, storm_pts: geopandas.GeoDataFrame, coord_decimals: int = 3, type_column: Optional[str] = None, sink_types: Optional[list] = None, source_types: Optional[list] = None)

Parameters:

storm_linesgpd.GeoDataFrame

All the stormwater infrastructure line features within the area of interest

storm_ptsgpd.GeoDataFrame

All the stormwater infrastructure points features within the area of interest

coord_decimalsint (default 3)

Decimal to round line coordinates too, prevents problems with improper snapping

type_columnstr | None (default None)

Column in storm_pts GeoDataFrame that represents the type of each point (e.g., catchbasins, outfalls, culverts), set to None if IS_SOURCE and IS_SINK are preconfigured in the storm_pts GeoDataFrame

sink_typeslist (default None)

List of type values that correspond to flow sinks, where flow enters at these points, such as a catchbasin

source_typeslist (default None)

List of type values that correspond to flow sources, where flow exits at these points, such as an outfall

add_edges(direction: str, verbose: bool = False) → None

Utilize user storm line data to add edges (and their nodes) to self.G in one or both directions

Parameters

directionstr

Direction to add edges in, based on the order of verticies in the user’s stormwater infrastructure line data (self.lines & self.segments). Can be ‘both’, ‘original’, or ‘reverse’

verbosebool

Set to True to print direction resolution/edge addition results to console

draw(extent: geopandas.GeoDataFrame = None, ax=None, add_basemap: bool = False) → plt.axes

Draw the Graph using the geographic coordinates of each node

Parameters

extentgpd.GeoDataFrame (default None)

GeoDataFrame whose extent will be used to trim the infrastructure data

axplt.axes | None (default None)

Matplotlib axes object to utilize for plot

add_basemapbool (deafult False)

Option to add a contextily basemap to the plot

get_inlet_points(catchment: geopandas.GeoDataFrame) → geopandas.GeoDataFrame

Get GeoDataFrame of all the infrastructure points outside the catchment that bring flow into the catchment.

Parameters

catchmentgpd.GeoDataFrame

GeoDataFrame containing the current catchment polygon

Returns

inlet_ptsgpd.GeoDataFrame

GeoDataFrame containing all the points outside the catchment that bring flow into the catchment

get_outlet(pt_idx: int) → Optional[int]

Get Index of the outlet for a given storm_pt whose coordinates exist in the graph

Parameters

pt_idxint

Index of point, note that OBJECTID is the default index column

get_outlet_points(catchment: geopandas.GeoDataFrame) → geopandas.GeoDataFrame

Get GeoDataFrame of all the infrastructure points within the catchment that bring flow out of the current catchment. The catchments for these points will need to be removed from current catchment.

Parameters

catchmentgpd.GeoDataFrame

GeoDataFrame containing the current catchment polygon

Returns

outlet_ptsgpd.GeoDataFrame

GeoDataFrame containing all the points that bring flow out of the current catchment

has_StormPoint(pt) → bool

Check if self.G contains a given StormPoint

Parameters

ptgpd.GeoDataFrame | pd.Series | StormPoint (namedtuple)

Point whose cooridnate pair will searched for in self.G

Returns

has_nodebool

True if the pt’s coordinate pair is present as a node in self.G

resolve_directions(method: str = 'from_sources', verbose: bool = False) → None

Attempt to resolve directions for all edges within the graph

Parameters

methodstr (default ‘from_sources’)

Method to resolve edge directions for self.G, can be one of the following: - ‘from_sources’: Traverses upstream from each outlet point (where

self.pts[‘IS_SOURCE’] is True) to define edge directions to point to outlets

• ‘vertex_order’: Defines edge directions using the order of verticies in

  self.lines

• ‘vertex_order_r’: Defines edge directions using reverse order of verticies

  in self.lines

verbosebool (default False)

Set to True to print direction resolution results to console

resolve_from_sources(verbose: bool = False) → None

Resolve directions of all edges within the graph by traversing subgraphs upstream from each flow source

Parameters

verbosebool (default False)

Set to True to print direction resolution results to console

resolve_upstream(source_pt) → None

Initializiton function for traverse_upstream, prepares arguments for depth-first search

Parameters

source_ptgpd.GeoDataFrame | pd.Series | StormPoint (namedtuple)

Infrastructure point which is a flow source/discharge point (IS_SOURCE=True)

to_StormPoint(pt) → StormPoint

Converts point data from various types to a StormPoint namedtuple

Parameters

ptgpd.GeoDataFrame | pd.Series | StormPoint (namedtuple)

Point data to convert to namedtuple

Returns

ptStormPoint (namedtuple)

Point data as a StormPoint namedtuple

traverse_upstream(coords: tuple, visited: set) → None

Revise direction of edges via recursive depth-first search, starting from an outlet then traverse the graph “upstream”. Visits every node that’s connected to the initial source node.

Parameters

coordstuple

Tuple of current (x, y) float coordinates. These coordinates are the name/index of the nodes in self.G

visitedset

Used to record which coordinates have already been visited in this search