stormcatchments.constants

stormcatchments.delineate

class stormcatchments.delineate.Delineate(network: Network, grid: pysheds.sgrid.sGrid, fdir: pysheds.sview.Raster, acc: pysheds.sview.Raster, grid_epsg: int)

Bases: object

Methods

delineate_points(pts, delineated)	Delineate catchments for a subset of infrastructure points
get_catchment(pour_pt[, acc_thresh])	Delineate catchment using pysheds
get_stormcatchment(pour_pt[, acc_thresh])	Iteratively delineate a stormcatchment.

delineate_points(pts: geopandas.GeoDataFrame, delineated: set) -> (geopandas.GeoDataFrame, <class 'set'>)

Delineate catchments for a subset of infrastructure points

Parameters

ptsgpd.GeoDataFrame

Points to delineate catchments for

delineatedset

A set of the OBJECTID (indicies) of point that have already been delineated. These points may or may not lie spatially within the catchment because snapping to the flow accumulation raster may shift their location

Returns

catchmentsgpd.GeoDataFrame

The newly delineated catchment for all the provided points, or an empty GeoDataFrame if the provided points have already been delineated

delineatedset

(Same as param delineated, see above)

get_catchment(pour_pt: tuple, acc_thresh: int = 1000) → geopandas.GeoDataFrame

Delineate catchment using pysheds

Parameters

pour_pttuple

An (x, y) coordinate pair, with the same coordinate system as the grid

acc_threshint (default 1000)

The minimum accumulation threshold used during pour point snapping

Returns

catchmentgpd.GeoDataFrame

A GeoDataFrame containing the newly delineated catchment polygon

get_stormcatchment(pour_pt: tuple, acc_thresh: int = 1000) → geopandas.GeoDataFrame

Iteratively delineate a stormcatchment. pysheds does the delineation work and the network module provides the stormwater infrastructure networking

Parameters

pour_pttuple

An (x, y) coordinate pair, with the same coordinate system as the grid

acc_threshint (default 1000)

The minimum accumulation threshold used during pour point snapping

Returns

catchment: gpd.GeoDataFrame

A GeoDataFrame containing the newly delineated catchment polygon

stormcatchments.delineate.get_catchment(pour_pt: tuple, grid: pysheds.sgrid.sGrid, fdir: pysheds.sview.Raster, acc: pysheds.sview.Raster, grid_epsg: int, acc_thresh: int = 1000) → geopandas.GeoDataFrame

Delineate catchment using pysheds

Parameters

pour_pttuple

An (x, y) coordinate pair, with the same coordinate system as the grid

gridpysheds.sgrid.sGrid

DEM

fdirpysheds.sview.Raster

A pysheds flow direction raster

accpysheds.sview.Raster

A pysehds flow accumulation raster

grid_epsgint

EPSG code for the CRS of the DEM

acc_threshint (default 1000)

The minimum accumulation threshold used during pour point snapping

Returns

catchmentgpd.GeoDataFrame

A GeoDataFrame containing the newly delineated catchment polygon

stormcatchments.network

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)

Bases: object

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

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

stormcatchments.network.get_point_coords(pt_geom, decimals: Optional[int] = None) → tuple

Get and x, y coordinate tuple from a Point or MultiPoint shapely geometry

Parameters

pt_geomPoint | MultiPoint

shapely geometry object containing a point coordinate

decimalsint (default None)

Number of decimals to round coordinates to

stormcatchments.terrain

stormcatchments.terrain.mosaic_to_new_raster(raster_paths: list, out_path: str)

Combine a set of rasters and write to a new file.

Parameters

raster_paths: list

List of str, each being a path to an existing raster file

out_path: str

Path to write new mosiac raster to

stormcatchments.terrain.preprocess_dem(dem_path: str) → tuple

Pre-process digital elevation model (DEM), in line standard preprocessing steps outlined in pysheds documentation

Parameters

dem_path: str

Path to DEM raster file

Returns

grid: pysheds.sgrid.sGrid

Grid view of digitial elevation model (DEM) raster

acc: pysheds.sview.Raster

A pysehds flow accumulation raster

fdir: pysheds.sview.Raster

A pysheds flow direction raster

stormcatchments.topology

stormcatchments.topology.find_floating_points(net: Network) → geopandas.GeoDataFrame

Find and return any points in a Network that are not snapped to a line vertex. These floating points cannot be integrated into networking functionality unless they are snapped to a line vertex.

Parameters

netNetwork

A stormcatchments Network object whose point data will be inspected for floating points

Returns

floating_ptsgpd.GeoDataFrame

A GeoDataFrame of any floating points in net.pts

stormcatchments.topology.find_multi_outlet(net: Network) → geopandas.GeoDataFrame

Find all subnetworks within greater Network that have more than one flow source/outlet

Parameters

netNetwork

A stormcatchments Network with resolved directions

Returns

mutli_outgpd.GeoDataFrame

A GeoDataFrame containing one MultiLineString features for each connected subgraph with multiple outlets/flow sources. If no multi-outlet subgraphs are found an empty GeoDataFrame is returned

stormcatchments.topology.snap_points(net: Network, tolerance: float) → Network

Create a copy of a supplied Network which snaps any points in Network to the closest line vertex within a snapping tolerance

Parameters

netNetwork

A stormcatchments Network object which may contain floating points

tolerancefloat

The maximum search distance to find the nearest vertex

Returns

net_snappedNetwork

A stormcatchments Network object with snapping applied to its point data