name: v.stream.network description: Build a linked stream network: each link knows its downstream link keywords: [ vector, stream network, hydrology, geomorphology ]

v.stream.network

Build a linked stream network: each link knows its downstream link

Command linePython (grass.script)

v.stream.network map=name [upstream_easting_column=string] [upstream_northing_column=string] [downstream_easting_column=string] [downstream_northing_column=string] [tostream_cat_column=string] [--verbose] [--quiet] [--qq] [--ui]

Example:

v.stream.network map=name

grass.script.run_command("v.stream.network", map, upstream_easting_column="x1", upstream_northing_column="y1", downstream_easting_column="x2", downstream_northing_column="y2", tostream_cat_column="tostream", verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("v.stream.network", map="name")

Parameters

Command linePython (grass.script)

map=name [required]
    Vector stream network from r.stream.extract
    Or data source for direct OGR access
upstream_easting_column=string
    Upstream easting (or x or lon) column name
    Default: x1
upstream_northing_column=string
    Upstream northing (or y or lat) column name
    Default: y1
downstream_easting_column=string
    Downstream easting (or x or lon) column name
    Default: x2
downstream_northing_column=string
    Downstream northing (or y or lat) column name
    Default: y2
tostream_cat_column=string
    Adjacent downstream segment category
    Zero (0) indicates off-map flow
    Default: tostream
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

map : str, required
    Vector stream network from r.stream.extract
    Or data source for direct OGR access
    Used as: input, vector, name
upstream_easting_column : str, optional
    Upstream easting (or x or lon) column name
    Default: x1
upstream_northing_column : str, optional
    Upstream northing (or y or lat) column name
    Default: y1
downstream_easting_column : str, optional
    Downstream easting (or x or lon) column name
    Default: x2
downstream_northing_column : str, optional
    Downstream northing (or y or lat) column name
    Default: y2
tostream_cat_column : str, optional
    Adjacent downstream segment category
    Zero (0) indicates off-map flow
    Default: tostream
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

v.stream.network populates the attribute table of a river network built by r.stream.extract with five new columns that define the nodes and links within a river network. These are (default names given):

x1, y1: upstream coordinates
x2, y2: downstream coordinates
tostream: category number of the next stream; is equal to 0 if the stream flows off of the map

Any stream-like network will work, but the lines need to be connected. In terms of graph theory, a tree and forest are supported. Behavior for a cyclic graph is undefined.

NOTES

streams is a set of vector lines that is generated by r.stream.extract. It is recommended to be built as follows (Python code):

# Choose elevation map and threshold
elevation = srtm
threshold = 1E6 # [m**2], minimum catchment size = 1 km**2
# Build a map of cell areas: pick one of these
# km2 is more intuitive, but 1 km2 is the threshold for the smallest
# threshold catchment size
r.mapcalc('cellArea_meters2 = '+str(reg.nsres)+' * '+str(reg.ewres), overwrite=True)
r.mapcalc("cellArea_km2 = cellArea_meters2 / 10^6", overwrite=True)

# Use r.watershed to build a drainage basin with units of length**2
# instead of arbitrary units (cells)
r.watershed(elevation=elevation, flow='cellArea_meters2', accumulation='drainageArea_m2', drainage='drainageDirection', stream='streams', threshold=thresh, flags='s', overwrite=True)
# Note that this will include areas of negative (i.e. offmap) flow accumulation

# Build watershed network using r.stream.extract: single-flow-direction (SFD)
print "Building drainage network"
r.stream_extract(elevation=elevation, accumulation='drainageArea_m2', threshold=thresh, d8cut=0, mexp=0, stream_raster='streams', stream_vector='streams', direction='draindir', overwrite=True)

REFERENCES

Ng, G-H. Crystal, Andrew D. Wickert, Lauren D. Somers, Leila Saberi, Collin Cronkite-Ratcliff, Richard G. Niswonger, and Jeffrey M. McKenzie. "GSFLOW–GRASS v1. 0.0: GIS-enabled hydrologic modeling of coupled groundwater–surface-water systems." Geoscientific Model Development 11 (2018): 4755-4777. DOI 10.5194/gmd-11-4755-2018

AUTHOR

Andrew D. Wickert

SOURCE CODE

Available at: v.stream.network source code (history)
Latest change: Friday Feb 21 10:10:05 2025 in commit 7d78fe3