Utilities and visualization

SurfaceWaterIntegratedModeling.saturated_spillgraph — Method

saturated_spillgraph(tstruct)

Create the spillgraph corresponding to the provided trapping structure, considering that all traps are already filled.

The result will be returned as a SimpleDiGraph showing which traps are spilling into which traps or regions.

The trapping structure tstruct may have regions with negative indices (referring to regions that spill out of the terrain). Since SimpleDiGraph does not handle nodes with negative indices, a remapping is necessary between the indices used in tstruct and the set 1:N used in the returned graph. These mappings are returned as the second and third return value:

The second return value is a Vector{Int} mapping from 1:N to the indices in tstruct
The third return value is a Dict mapping from the indices in tstruct to 1:N.

source

SurfaceWaterIntegratedModeling.watercourses — Method

watercourses(tstruct, full_traps, precipitation, infiltration)

Compute the total intensity of flow of water across all non-lake grid cells in the terrain.

Determine the areas containing high amounts of flowing water, and return a grid with the corresponding values.

Arguments

tstruct::TrapStructure: a TrapStructure object containing all the information from the topographical analysis, as returned by the spillanalysis function.
full_traps::Vector{Bool}: A vector with one entry per (sub)trap, indicating whether this trap has been filled yet or not. Only full traps will overflow and forward the water from upstream.
precipitation::Matrix{<:Real}: A grid expressing precipitation rate per grid cell. If left empty, it will be substituted by a grid filled with ones.
infiltration::Matrix{<:Real}: A grid expressing the maximum infiltration rate per grid cell. If left empty, it will be substituted by a grid filled with zeros.

Returns

runoff::Matrix{Float64}: Grid expressing infiltration excess runoff rate (positive values) or remaining infiltration capacity (negative values)
region_accum::Vector{Float64}: Vector with one entry per spill region, indicating net water accumulation rate for that region (also including water spilling into the region from upstream filled traps). Note that if the region is associated with a filled trap, the accumulation value is set to zero, unless it spills into a filled 'sibling' trap. The logic is in any case such that the accumulation of any still unfilled trap should equal the sum of accumulation of its regions.
offregion_runoff::Float64: Total rate of water flowing off the domain
used_infiltration::Float64: Total infiltration rate across the terrain

source

SurfaceWaterIntegratedModeling.all_subtraps_of — Method

all_subtraps_of(subtrap_graph, trap_ixs)

Return all subtraps (at any level) of a specified set of traps.

The graph representing the supertrap/subtrap tree is given by subtrap_graph. The indices to the set of traps is specified by trap_ixs. This argument may be an integer refering to a single trap, or a Vector{Int} referring to one or more traps.

The result is returned as a Vector{Int} giving the indices of all traps that are subtraps of the trap(s) referred to by trap_ixs.

source

SurfaceWaterIntegratedModeling.all_upstream_regions — Method

all_upstream_regions(tstruct, region)

Identify all spill regions that will eventually become part of the extended watershed of a specified region.

When traps are empty, water accumulates locally. As traps fill up, water starts to spill from upstream to downstream regions. This function identifies all the spill regions that will flow into a specified region/trap when all upstream traps have been completely filled.

The result is returned as a Vector{Int}, giving the indices of all regions that will be upstream of the specified region when all traps are filled.

Arguments

tstruct::TrapStructure{<:Real}: trap structure object describing the terrain traps
region::Int: index of the region in question

See also: flatten_grid!

source

SurfaceWaterIntegratedModeling.interpolate_timeseries — Method

interpolate_timeseries(tstruct, seq, timepoints; 
                       filled_color=1, trap_color=2, river_color=3)

Compute the exact terrain fill states for a sequence of timepoints, given a trapping structure and sequence of SpillEvents.

Each generated fill state is represented as an integer matrix (Matrix{Int}), where submerged cells are set to filled_color, the parts of traps that are not (yet) submerged set to trap_color and intermittent streams set to river_color. Other cells are attributed the value zero.

The result is returned as a Vector{Matrix{Int}}, of the same length as timepoints. A second return value provides a corresponding Vector{Int} that for each timepoint provides the index for the latest preceding event in seq.

Arguments

tstruct::TrapStructure{<:Real}: trap structure object describing the terrain traps
seq::Vector{SpillEvent}: the sequence of events, as computed by fill_sequence for a given weather scenario
timepoints::Vector{<:Real}: the timepoints for which we want to compute the exact terrain fill states. Should be given in ascending order.
filled_color::Int: The 'color' value to represent filled areas (default: 1).
trap_color::Int: The 'color' to represent unfilled parts of traps (default: 2).
river_color::Int: The 'color' to represent intermittent rivers (default: 3).
verbose::Bool: Whether to print progess information during computations (default: true).

source

SurfaceWaterIntegratedModeling.show_region_selection — Method

show_region_selection(tstruct; selection=nothing, 
                      region_color=1, trap_color=2, river_color=3)

Create a texture identifying the requested regions, traps and related rivers.

The information about the terrain, including topography, spillpoints, etc., is provided by the structure tstruct, which can be obtained from the spillanalysis function. The selected regions are identified by selection, a vector with the indices of the selected regions. If left empty, all toplevel traps/regions will be selected.

The result is returned as a matrix of integers, where the integers can be thought of as 'colors'. The integer values used to indicate region, trap or river are given by the arguments region_color, trap_color and river_color, respectively. If region_color is a negative integer, each region will be assigned an unique color, starting from abs(region_color) and incrementing by one per region.

Arguments

selection: integer vector containing indices of the selected regions
region_color: integer to assign to the cells of all selected regions
trap_color: integer to assign to all selected traps
river_color: integer to assign to all river cells related to the selected regions