surficial Package#

surficial Package#

alignment Module#

class surficial.core.alignment.Alignment(lines)#

Bases: DiGraph

A directed network graph of LineStrings

Alignment is a subclass of networkx.DiGraph and adds methods for addressing points within the network. It represents the set of geometries onto which points of interest are projected.

Parameters:

lines (list[LineString]) –

edge_addresses(outlet, weight='len')#

Calculate cost path distances from a given node to each graph edge end node

Parameters:

  • outlet (int) – network outlet node ID

  • weight (str) – name of property to use for weight calculation

Returns:

pandas.DataFrame of edge address information relative to outlet

edge

tuple of node identifiers identifying an edge (as tuple[int, int])

from_node_address

cost path distance between outlet node and edge start node (as float)

to_node_address

cost path distance between outlet node and edge end node (as float)

Return type:

DataFrame

edge_buffer(radius=1.0, edges=None)#

Return a buffer Polygon around a set of graph edges

Example

path = list(alignment.path_edges(1, outlet)) buf = PolygonPatch(alignment.edge_buffer(100.0, edges=path), fc=BLUE, ec=BLUE, alpha=0.5, zorder=2)

Parameters:

  • radius (int | float) – buffer radius

  • edges (Iterable[tuple[int, int]] | None) – optional list of edges to buffer

Returns:

polygon representing the buffered geometries

Return type:

MultiLineString

intermediate_nodes()#

Return the set of nodes intermediate between leaf and root nodes

Returns:

list of all intermediate node ID values

Return type:

list[int]

outlet()#

Return the root node in a directed graph

In a stream network this represents the drainage outlet.

Returns:

outlet node ID

Return type:

int

path_edges(start, goal, weight=None)#

Return the set of graph edges making up a shortest path

Parameters:

  • start (int) – starting node ID

  • goal (int) – goal node ID

  • weight (str | None) – name of property to use for weight calculation

Returns:

edges making up the path

Return type:

Iterable[tuple[int, int]]

path_weight(edges, weight)#

Return the path weight of a set of graph edges

Parameters:

  • edges (Iterable[tuple[int, int]]) – list of edges making up the path

  • weight (str) – name of property to use for weight calculation

Returns:

total path weight

Return type:

float

station(step)#

Get a dataframe of regularly spaced stations along graph edges

Parameters:

step (float) – distance spacing between stations

Returns:

pandas.DataFrame containing station point information

m

path distance from the to_node endpoint (as float)

x

x coordinate (as float)

y

y coordinate (as float)

z

z coordinate (as float)

edge

pair of graph nodes: from, to (as tuple[int, int])

path_m

path distance from the outlet (as float)

Return type:

DataFrame

surficial.core.alignment.remove_spikes(graph, start=None, goal=None, column='z')#

Remove spikes from a graph or a subset of edges using an expanding minimum

Parameters:

  • graph (Alignment) – directed network graph

  • start (None | int) – starting/from node

  • goal (None | int) – goal/to node

  • column (str) – column from which to remove spikes

Returns:

pandas.DataFrame of graph vertices with new despiked column ‘zmin’

m

path distance from the to_node endpoint (as float)

x

x coordinate (as float)

y

y coordinate (as float)

z

z coordinate (as float)

edge

pair of graph nodes: from, to (as tuple[int, int])

path_m

path distance from the outlet (as float)

zmin

rolling minimum z coordinate (as float)

Return type:

DataFrame

surficial.core.alignment.roll_down(graph, start, goal, window)#

Perform an operation on a list of path edges

Parameters:

  • graph (Alignment) – directed network graph

  • start (int) – start/from node

  • goal (int) – goal/to node

  • window (int) – window width in number of vertices

Return type:

None

surficial.core.alignment.slope(graph, column='z')#

Returns a DataFrame with columns for rise and slope between vertices

Parameters:

  • graph (Alignment) – an Alignment

  • column (str) – name of column containing the values

Returns:

pandas.Dataframe with columns for rise and slope

m

path distance from the to_node endpoint (as float)

x

x coordinate (as float)

y

y coordinate (as float)

z

z coordinate (as float)

edge

pair of graph nodes: from, to (as tuple[int, int])

path_m

path distance from the outlet (as float)

rise

change in given column in downstream direction (as float)

slope

rise over run in the downstream direction (as float)

Return type:

DataFrame

Subpackages#