Terrain hydrology

hydro.along_network#

The stretches of river up and down from every point within a distance along the network, as hydrographr's get_buffer_along_the_network: downstream along the D8 directions, upstream along every stream that flows into it (a buffer that follows the river, not a circle: the reach of a fish, of a spill below a mine). Each cell given the point nearest to it along the network.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
pointsrequired	vector	the points, moved onto the streams
streamsrequired	map	the streams: non-zero on their cells

Output	Type	What it is
map	map	the point (1..) of each cell within reach, 0 elsewhere
distance	map	the distance along the network to that point (map units; m for longitude / latitude)

Setting	Type	What it is
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)
upstream	number	how far upstream (0)
downstream	number	how far downstream (0)
snap	number	the largest move of a point onto the streams, map units (300 m; 3 cells without a projection)

hydro.breach#

Remove the depressions of a DEM by cutting channels through their rims (least-cost breaching, WhiteboxTools' BreachDepressionsLeastCost after Lindsay & Dhun 2015): each pit, from the lowest, joined to the nearest cell it can drain to by the channel of least cost; often changes the terrain less than filling.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled

Output	Type	What it is
map	map	the breached DEM

Setting	Type	What it is
max_length	integer	the longest channel, in cells (100)
max_cost	number	the costliest channel to cut (default: any)
min_dist	bool	count the channel's length in its cost, preferring shorter channels (default true)
flat_increment	number	the drop per cell along a channel (default: from the elevations, as WhiteboxTools)
fill_rest	bool	fill the depressions no channel could solve (default true)

hydro.centrality#

The place of every link in its river network, as hydrographr's get_centrality on the graph of the links: the links flowing into it, its degree, its Shreve magnitude (the sources above it), the length of river above it, and its betweenness (the pairs of links whose path goes through it) and closeness (one over the sum of the steps to every other link of its network), igraph's on the undirected graph.

Input	Type	What it is
linksrequired	table	the links' table of hydro.stream_links (link, downstream, length)

Output	Type	What it is
table	table	link, downstream, upstream, degree, magnitude, upstream_length, betweenness, closeness

hydro.connectivity_index#

The index of connectivity (Borselli et al. 2008) as InVEST's sediment delivery ratio model computes it: log10 of the upslope over the downslope component, the weight (a land use's USLE C) and pygeoprocessing's slope along its routing; no value on the streams.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
weightrequired	map	the weight W of each cell (USLE C)
streams	map	1 on the streams (else from the threshold)

Output	Type	What it is
map	map	the index

Setting	Type	What it is
threshold	number	the flow accumulation (cells) of a stream, without streams
method	text	the routing: mfd (default) or d8

hydro.dci#

The dendritic connectivity index of a river network cut by barriers (Cote et al. 2009), as R's riverconn: the network split into segments at each dam, weir or culvert, each segment weighted by its length (or its habitat); the potamodromous DCI (the chance that a fish can swim between two points of the river, 0 to 100) and the diadromous one (between the mouth and a point), from the passability of each barrier up and down. For every barrier, the DCI if it were removed and its gain (riverconn's d_index, percent): which dams to remove first.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
streamsrequired	map	the river network: non-zero on its cells (hydro.streams, the links)
barriersrequired	vector	the barriers as points, moved onto the streams; their passability from the attributes pass_u and pass_d, or passability (0 to 1)
weights	map	the habitat of each cell: a segment weighs the length of its cells times this (default 1)

Output	Type	What it is
table	table	a row per network with barriers: network (its mouth segment), segments, barriers, weight, dci_p, dci_d
barriers	vector	the barriers moved, their attributes and segment, network, pass_u, pass_d, dci_p_removed, d_index (the percent the DCI of its network grows when it is removed), rank (1 the largest)
segments	map	the segment of each stream cell (1..), 0 elsewhere
reach	map	on each stream cell, riverconn's reach index of its segment, 0 to 100: the share of its network a fish there can reach

Setting	Type	What it is
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)
passability	number	of the barriers without pass_u, pass_d or passability attributes (0: impassable)
direction	text	symmetric (default: the product of the passabilities up and down at every barrier, Cote's) or asymmetric (up through a barrier going upstream, down going downstream)
snap	number	the largest move of a barrier onto the streams, map units (300 m; 3 cells without a projection)

hydro.distance_to_channel#

The mean distance water travels from each cell to a stream along pygeoprocessing's multiple flow directions (InVEST's sediment delivery model's downslope component): in cell lengths, or in the units of the weights; 0 on the streams, no value where no flow reaches one.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
streamsrequired	map	1 on the stream cells
weights	map	the length of each step onto a cell

Output	Type	What it is
map	map	the distance

hydro.fill#

Fill the depressions of a DEM so that water flows from every cell to the edge: each depression raised to where it would spill over (Priority-Flood, Barnes, Lehman & Mulla 2014; the DEM of WhiteboxTools' FillDepressions), through landschaft's C++.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled

Output	Type	What it is
map	map	the filled DEM

Setting	Type	What it is
drain_flats	bool	raise each filled cell by the smallest step above the cell it drains to (Priority-Flood+epsilon), so filled areas slope towards their outlet

hydro.flow_accumulation#

The area that drains through each cell (itself included): all to the steepest neighbour (d8), split between the two cells of the D-infinity azimuth (dinf), among the lower neighbours by slope^exponent (fd8, Freeman 1991) or by slope times contour length (quinn, Quinn et al. 1991), or pygeoprocessing's multiple flow directions (mfd, the InVEST models'). WhiteboxTools' accumulations cell for cell.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
weights	map	what each cell contributes instead of 1

Output	Type	What it is
map	map	the accumulation

Setting	Type	What it is
method	text	d8 (default), dinf, fd8, quinn or mfd
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)
units	text	cells (default), area (map units squared; m² for longitude / latitude) or sca (the area per unit contour width)
exponent	number	of fd8 (1.1) and quinn (1)

hydro.flow_direction#

The direction each cell drains to: D8 (O'Callaghan & Mark 1984) as ESRI's codes (1 E, 2 SE, 4 S, 8 SW, 16 W, 32 NW, 64 N, 128 NE; 0 no flow), D-infinity (Tarboton 1997) as the azimuth in degrees clockwise from north (-1 no flow), or pygeoprocessing's multiple flow directions (the InVEST models' routing) as eight packed 4-bit weights.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled

Output	Type	What it is
map	map	the codes or azimuths

Setting	Type	What it is
method	text	d8 (default), dinf or mfd
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)

hydro.hand#

Height Above the Nearest Drainage (HAND; Rennó et al. 2008, Nobre et al. 2011): the height of each cell above the stream cell its water reaches along the D8 directions; 0 on the streams, no value where it reaches none.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
streams	map	the drainage: non-zero on the stream cells

Output	Type	What it is
map	map	the height in the DEM's units

Setting	Type	What it is
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)
threshold	number	or the drainage as the cells of D8 accumulation (cells) of at least this

hydro.network_distance#

The distance along the river network between every two points, as hydrographr's get_distance: down the D8 directions from each to where their waters meet (fish swimming between two gauges, two populations), and the straight distance; whether one drains into the other. Points in different basins are not connected.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
streams	map	the streams the points are moved onto (non-zero on their cells); without them, the cell each falls in
pointsrequired	vector	the points (moved onto the streams when they are given)

Output	Type	What it is
table	table	a row per two points: from, to (1..), network (map units; m for longitude / latitude; no value when not connected), euclidean, connected (1 or 0), flow (1 when one drains into the other)

Setting	Type	What it is
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)
snap	number	the largest move of a point onto the streams, map units (300 m; 3 cells without a projection)

hydro.snap#

Points moved onto the stream network, as hydrographr's snap_to_network: gauges, dams, records of fish each to the centre of the nearest stream cell within a distance (of equally near ones the first in raster order), or of the nearest whose flow accumulation is at least a minimum (on the river, not a tributary beside it). A point farther than the distance stays where it was, snapped 0.

Input	Type	What it is
pointsrequired	vector	the points
streamsrequired	map	the streams: non-zero on their cells (hydro.streams, the links)
accumulation	map	a flow accumulation, with min_accumulation

Output	Type	What it is
vector	vector	the points moved, their attributes and row, col, stream (the streams' value there), moved (the distance), snapped (1 or 0)
table	table	their attributes

Setting	Type	What it is
distance	number	the largest move, map units (300 m; 3 cells without a projection)
min_accumulation	number	only the stream cells of at least this accumulation (in its units)

hydro.spi#

Stream power index a x tan(slope) (Moore, Grayson & Ladson 1991), WhiteboxTools' StreamPowerIndex: the erosive power of overland flow. a: the specific contributing area of a multiple-flow accumulation by default; the slope: Horn's gradient of the DEM.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
sca	map	a specific contributing area to use instead
slope	map	a slope in degrees to use instead

Output	Type	What it is
map	map	the SPI

Setting	Type	What it is
method	text	the accumulation of a: fd8 (default), quinn, dinf, d8 or mfd
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)

hydro.sti#

Sediment transport index (m + 1) (a / 22.13)^m (sin(slope) / 0.0896)^n (Moore & Burch 1986), WhiteboxTools' SedimentTransportIndex: the LS factor of the USLE from the contributing area. a: the specific contributing area of a multiple-flow accumulation by default; the slope: Horn's gradient of the DEM.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
sca	map	a specific contributing area to use instead
slope	map	a slope in degrees to use instead

Output	Type	What it is
map	map	the STI

Setting	Type	What it is
method	text	the accumulation of a: fd8 (default), quinn, dinf, d8 or mfd
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)
sca_exponent	number	m (0.4)
slope_exponent	number	n (1.3)

hydro.stream_links#

The links of a stream network: the stretches between sources, junctions and outlets along the D8 directions, numbered 1, 2... in the raster order of their first cells; and their table (downstream link, whether it ends at an outlet, first and last cell, cells, length, elevations, Strahler order).

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
streamsrequired	map	1 on the stream cells
outlets	vector	points where a link must end (gauges, dams, the outlet), each snapped to the nearest stream cell

Output	Type	What it is
map	map	the link of each stream cell, 0 elsewhere
table	table	a row per link

Setting	Type	What it is
snap	number	the largest move of an outlet, map units (300 m; 3 cells without a projection)
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)

hydro.streams#

The stream cells: those whose flow accumulation is at least a threshold; or, with the DEM and trace, pygeoprocessing's stream extraction from the mfd accumulation as InVEST's sediment model runs it (trace 0.7): cells of the threshold traced up from the outlets, tributaries down to trace x threshold kept where they join one.

Input	Type	What it is
accumulationrequired	map	a flow accumulation
dem	map	the (filled) DEM whose mfd directions are traced

Output	Type	What it is
map	map	1 on the streams, 0 elsewhere

Setting	Type	What it is
thresholdrequired	number	the smallest accumulation of a stream, in its units
trace	number	0 to 1, with the DEM (InVEST's: 0.7)

hydro.twi#

Topographic wetness index ln(a / tan(slope)) (Beven & Kirkby 1979), WhiteboxTools' WetnessIndex: high where much area drains through a gentle slope; a proxy of soil moisture. a: the specific contributing area of a multiple-flow accumulation by default; the slope: Horn's gradient of the DEM.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
sca	map	a specific contributing area to use instead
slope	map	a slope in degrees to use instead

Output	Type	What it is
map	map	the TWI

Setting	Type	What it is
method	text	the accumulation of a: fd8 (default), quinn, dinf, d8 or mfd
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)
min_slope	number	a floor for tan(slope), so flat cells get a value (0: they have none)

hydro.upstream#

The land upstream of every link of a stream network, or of every point on it, summarised, as hydrographr's get_upstream_variable: the statistics of maps over all the cells that drain through it (the mean slope, the rain summed) and the share of each class of a map (the forest, the cities upstream), from each link's last cell or the point's along the D8 directions; its cells and area. The cells without a value of a map left out of its statistics.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
streams	map	the streams the points are moved onto (non-zero on their cells); without them, the cell each falls in
links	map	the links of hydro.stream_links: a row per link
points	vector	or points (gauges, dams, sites): a row per point
values	any	a map or a stack of maps whose statistics are given
classes	map	a map of classes whose shares are given (share_)

Output	Type	What it is
table	table	a row per link (link, downstream) or point (point, downstream, row, col), then cells, area (map units squared; m² for longitude / latitude), the statistics (_ of a stack) and the shares
map	map	the column to_map painted on each link's cells, or on each point's cell

Setting	Type	What it is
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)
snap	number	the largest move of a point onto the streams, map units (300 m; 3 cells without a projection)
stats	any	of the values: count, sum, mean, min, max, std (default mean)
to_map	text	the column of the map (the first after the area)

hydro.upstream_catchment#

The catchment of every point (a gauge, a dam, a site), as hydrographr's get_upstream_catchment: all the land that drains to it along the D8 directions, as a polygon per point (with the point's attributes, its cells and area; the catchments of points one above another overlap), and a map of each cell's first point downstream (the catchments nested, between one point and the next).

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
streams	map	the streams the points are moved onto (non-zero on their cells); without them, the cell each falls in
pointsrequired	vector	the points (moved onto the streams when they are given)

Output	Type	What it is
vector	vector	a polygon per point: its attributes and point (1..), downstream (the point below, 0 none), cells, area
table	table	point, downstream, row, col, cells, area
map	map	the first point each cell drains to (1..; 0 none): the catchments between one point and the next

Setting	Type	What it is
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)
snap	number	the largest move of a point onto the streams, map units (300 m; 3 cells without a projection)

hydro.watersheds#

The area draining to each seed: every cell labelled with the first seed below it along the D8 directions (seeds keep their own label); 0 where its path reaches none.

Input	Type	What it is
demrequired	map	the elevations (no value: missing), best with depressions filled
seedsrequired	map	positive whole labels on the cells water drains to (stream links, outlets, lakes), 0 elsewhere

Output	Type	What it is
map	map	the label of the seed each cell drains to

Setting	Type	What it is
flats	bool	drain flat areas towards lower terrain and away from higher terrain (Barnes et al. 2014; default true)

swat.run#

Simulate a SWAT+ project (a TxtInOut folder or a zip of one) as SWAT+ 62.0.1 does, through landschaft's port of it (bit for bit with SWAT+ for what the port covers: measured and generated weather, HRUs with snow, ET, curve number runoff, MUSLE erosion, percolation, lateral flow, nutrients, plant growth and management, routing units, aquifers, SWAT-DEG channels). The tables SWAT+ prints, at a step: a row per date (year, day of the year) and object (HRU, channel, aquifer; the basin's by date).

Output	Type	What it is
weather	table	the daily weather of each station (year, day, station)
hru_wb	table	what SWAT+ prints (columns and units as its own)
hru_nb	table	what SWAT+ prints (columns and units as its own)
hru_ls	table	what SWAT+ prints (columns and units as its own)
hru_pw	table	what SWAT+ prints (columns and units as its own)
basin_wb	table	what SWAT+ prints (columns and units as its own)
basin_nb	table	what SWAT+ prints (columns and units as its own)
basin_ls	table	what SWAT+ prints (columns and units as its own)
basin_pw	table	what SWAT+ prints (columns and units as its own)
channel_sd	table	what SWAT+ prints (columns and units as its own)
aquifer	table	what SWAT+ prints (columns and units as its own)

Setting	Type	What it is
pathrequired	text	the TxtInOut folder (with file.cio) or a zip of it
step	text	of the tables: day, month, year (default) or aa (average annual)
tables	any	the tables printed (default every one): hru_wb, hru_nb, hru_ls, hru_pw, basin_wb, basin_nb, basin_ls, basin_pw, channel_sd, aquifer
nyskip	integer	years simulated before printing (spin-up)
c_factor	text	MUSLE's C: swatplus (default, SWAT+ 62's from APEX) or plant (the plants' minimum, SWAT+'s earlier method)