Skip to content

Commit

Permalink
starting on some vbet documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@jtgilbert
jtgilbert committed Nov 27, 2024
1 parent b15b1e3 commit f35c05a
Show file tree
Hide file tree
Showing 3 changed files with 59 additions and 153 deletions.
15 changes: 15 additions & 0 deletions docs/content/page/vbet/algorithm.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
title: VBET Algorithm
banner: true
layout: default
---

VBET generates valley bottom on a stream by stream basis (using 'level_path' for NHD data or whatever unique stream ID fields exists for custom data), starting with the largest stream and working down to the smallest stream. For each unique stream:

1. **Extract channel area for stream**: the channel area polygon for just the unique stream is extracted and rasterized. This raster is used to generate the HAND raster, as well as for a line of evidence in the valley bottom extraction process.
2. **Clip DEM**: the input DEM is clipped to an extent that includes the drainage wings of the stream.
3. **Generate HAND raster**: the HAND raster is generated using the TauDEM tool.
4. **Generate Slope raster**: the slope raster is generated from the clipped DEM (or clipped to the extent of the DEM if an input slope raster is provided).
5. **Transform HAND and slope rasters into evidence rasters**: the HAND and slope rasters are transformed into rasters with values from 0 to 1, where 0 represents low evidence and 1 represents strong evidence. The transformations are performed using log-likelihood functions that were calibrated by taking points at different locations within and outside of riverscapes, classifying them as valley bottom or not, and extracting the slope and HAND values at those points. This was performed on a dataset of thousands of points across the United States.
6. **Inverse distance weighting of slope evidence**: the slope raster is reweighted using the inverse of the distance from the stream channel. This is done to give more weight to the low slope values near the stream channel relative to low slope values far from the channel (e.g. ridge tops have low slopes but are essentially the opposite of valley bottom). This is done by computing a proximity raster from the rasterized channel area input. For each slope evidence raster cell, the square root of the distance at that cell divided by the square root of the maximum distance is subtracted from the slope evidence value.
7. **Combine evidence rasters**: the slope and HAND evidence rasters are combined using a weighted product. The weights can be set by the user, but the default is 0.65 for HAND and 0.35 for slope. Cells that correspond with the channel area raster are automatically set to 0.995.
11 changes: 6 additions & 5 deletions docs/content/page/vbet/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,19 @@ banner: true
layout: default
---

The Valley Bottom Extraction Tool (VBET) is a tool used to identify the valley bottom of a riverscape, and roughly separate it into geomorphic units (channel, active floodplain, and inactive floodplain). The tool takes a DEM and channel area polygon as inputs. Three different topographic analyses of the DEM are used as lines of evidence in determining what is valley bottom:
The Valley Bottom Extraction Tool (VBET) is a tool used to identify the valley bottom of a riverscape, and roughly separate it into geomorphic units (channel, topographically low-lying floodplain, and elevated (more distal/inactive) floodplain). The tool takes a DEM and channel area polygon as inputs. Two topographic analyses of the DEM are used as lines of evidence in determining what is valley bottom:

- Slope
- Topographic Wetness Index ([TWI](https://en.wikipedia.org/wiki/Topographic_wetness_index))
- Height Above Nearest Drainage (HAND)

(These three inputs can be generated using the [TauDEM](https://tools.riverscapes.com/taudem) tool)
(These inputs can be generated using the [TauDEM](https://tools.riverscapes.com/taudem) tool)

In addition to being used in generating the HAND raster, the channel area polygon is rasterized and used as an additional line of evidence.

For interpretation as lines of evidence, raster values in each of the rasters are converted to values between 0 (very low likelihood of being valley bottom) and 1 (very high likelihood of being valley bottom) using transform functions with parameters that vary based on stream order. The logic for this is that in low stream order settings, valley bottoms are likely to have higher slopes than in high stream order settings. Similarly, higher values of HAND (higher elevations above the drainage network) are less likely to be part of the valley bottom in low order streams. Finally, these transformed inputs are averaged, resulting in a raster with values between 0 and 1, essentially representing relative probability of being part of the valley bottom. This raster is one of the tool outputs. Additionally, threshold values can be chosen in order to extract a polygon representing the valley bottom from the raster. Different threshold values can be used to estimate the extent of the different geomorphic units.
For interpretation as lines of evidence, raster values in each of the rasters are converted to values between 0 (very low likelihood of being valley bottom) and 1 (very high likelihood of being valley bottom) using calibrated transform functions with parameters that vary based on stream size (as determined by drainage area). The logic for this is that in smaller stream settings, valley bottoms are likely to have higher slopes than in larger river settings. Similarly, higher values of HAND (higher elevations above the drainage network) are less likely to be part of the valley bottom in smaller streams. Finally, these transformed inputs are averaged using different weights, resulting in a raster with values between 0 and 1, essentially representing relative probability of being part of the valley bottom. This raster is one of the tool outputs. Additionally, threshold values can be chosen in order to extract a polygon representing the valley bottom from the raster. Different threshold values can be used to estimate the extent of the different geomorphic units. By default, the tool uses a threshold of 0.65 to extract the valley bottom polygon, and a threshold of 0.85 to extract the low-lying portion of the valley bottom. For a detailed description of the algorithm, see the [algorithm page](https://tools.riverscapes.net/vbet/algorithm).

In addition to delineating the extent of valley bottom, VBET segments the valley bottom output in to discrete polygons, whose size varies based on the size of the river. These polygons are called discrete geographic objects (DGOs). These DGOs create a sample frame that can be used to calculate metrics related to riverscapes, and VBET calculates a suite of such metrics for each DGO. At the center of each DGO, VBET places a point, referred to as an integrated geographic object (IGO), because it can be used to summarize metrics calculated over a moving window (i.e., a combination of DGO polygons) that the point IGO is at the center of. Like with the DGOs, VBET calculates various moving window metrics and adds these attributes to the IGOs. For a detailed description of the metrics, see the [metrics page](https://tools.riverscapes.net/vbet/metrics).

# References

- Gilbert J.T., Macfarlane W.W. & Wheaton J.M., 2016. [The Valley Bottom Extraction Tool (V-BET): A GIS tool for delineating valley bottoms across entire drainage networks](https://www.researchgate.net/publication/305661801_The_Valley_Bottom_Extraction_Tool_V-BET_A_GIS_tool_for_delineating_valley_bottoms_across_entire_drainage_networks). Geomorphology. DOI: [10.1016/j.cageo.2016.07.014](https://doi.org/10.1016/j.cageo.2016.07.014).
- Gilbert J.T., Macfarlane W.W. & Wheaton J.M., 2016. [The Valley Bottom Extraction Tool (V-BET): A GIS tool for delineating valley bottoms across entire drainage networks](https://www.researchgate.net/publication/305661801_The_Valley_Bottom_Extraction_Tool_V-BET_A_GIS_tool_for_delineating_valley_bottoms_across_entire_drainage_networks). Computers and Geosciences. DOI: [10.1016/j.cageo.2016.07.014](https://doi.org/10.1016/j.cageo.2016.07.014).
186 changes: 38 additions & 148 deletions docs/content/page/vbet/metrics.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,152 +6,42 @@ layout: true

![vbet_areas](https://docs.google.com/drawings/d/e/2PACX-1vRZt634xFFKJ-EoN9hb9T1WnV77q-tByKwtiJk-k5mr7btqr-6R0Xzaq0tKG1EGIdv351kQgegcWlvc/pub?w=1040&h=714)

## LevelPathI
## DGO/IGO Fields

Field|Data Type|Units|Description
---|---|---|---
`level_path`*|TEXT|N/A|Unique identifier for a given stream from where it begins to where it ends
`seg_distance`|REAL|Meters|Distance along a given level_path. The combination of level path and seg_distance uniquely identifies a DGO/IGO
`segment_area`|REAL|Square meters|Area of the DGO
`centerline_length`|REAL|Meters|Length of the centerline of the DGO/analysis window
`window_area`|REAL|Square meters|Area of the analysis window (a group of DGOs)
`FCode`*|INTEGER|N/A|A code representing the flow type (e.g., perennial, intermittent, ephemeral) for the main flowline within the DGO/analysis window

* These fields are NHD fields that are used by default, but in custom runs utlizing different datasets can be substituted for other field names.

## Metrics

The following metrics are calculated individually for each DGO polygon and/or within an analysis window (comprised of several DGOs) and attributed to the corresponding IGO point.

Field|Metric|Data Type|Units|Description
---|---|---|---|---
`active_channel_area`|Active Channel Area|REAL|Square meters|Total area of active channel within the DGO/analysis window
`active_channel_prop(ortion)`|Active Channel Proportion|REAL|Ratio|Proportion of DGO/analysis window that is active channel
`floodplain_area`|Floodplain Area|REAL|Square meters|Total area of floodplain (valley bottom - active channel) within the DGO/analysis window
`floodplain_prop(ortion)`|Floodplain Proportion|REAL|Ratio|Proportion of DGO/analysis window that is floodplain
`low_lying_floodplain_area`|Low-Lying Floodplain Area|REAL|Square meters|Total area of low-lying floodplain within the DGO/analysis window
`low_lying_floodplain_prop(ortion)`|Low-Lying Floodplain Proportion|REAL|Ratio|Proportion of DGO/analysis window that is topographically low-lying floodplain
`elevated_floodplain_area`|Elevated Floodplain Area|REAL|Square meters|Total area of elevated Floodplain within the DGO/analysis window
`elevated_floodplain_prop(ortion)`|Elevated Floodplain Proportion|REAL|Ratio|Proportion of DGO/analysis window that is elevated floodplain
`integrated_width`|Integrated Width|REAL|Meters|Integrated width calculated as window_area / centerline length (average width of the DGO/analysis window)
`active_channel_itgr_width`|Active Channel Integrated Width|REAL|Meters|Active channel area divided by centerline length within the DGO/analysis window (average width of active channel)
`floodplain_itgr_width`|Floodplain Integrated Width|REAL|Meters|Floodplain area divided by centerline length within the DGO/analysis window (average width of floodplain)
`vb_acreage_per_mile`|Valley Bottom Acreage per Mile|REAL|acres/mile|Window area converted to acres and divided by centerline length converted to miles
`vb_hectares_per_km`|Valley Bottom Hectares per Kilometer|REAL|hectares/km|Window area converted to hectares and divided by centerline length converted to kilometers
`low_lying_floodplain_itgr_width`|Low-Lying Floodplain Integrated Width|REAL|Meters|Low-lying floodplain area divided by centerline length within the DGO/analysis window (average width of low-lying floodplain)
`elevated_floodplain_itgr_width`|Elevated Floodplain Integrated Width|REAL|Meters|Elevated floodplain area divided by centerline length within the DGO/analysis window (average width of elevated floodplain)
`low_lying_acreage_per_mile`|Low-Lying Acreage per Mile|REAL|acres/mile|Low-lying floodplain area converted to acres and divided by centerline length converted to miles
`low_lying_hectares_per_km`|Low-Lying Hectares per Kilometer|REAL|hectares/km|Low-lying floodplain area converted to hectares and divided by centerline length converted to kilometers
`elevated_acreage_per_mile`|Elevated Acreage per Mile|REAL|acres/mile|Elevated floodplain area converted to acres and divided by centerline length converted to miles
`elevated_hectares_per_km`|Elevated Hectares per Kilometer|REAL|hectares/km|Elevated floodplain area converted to hectares and divided by centerline length converted to kilometers

Data Type|String
Units|NA
Description|The tributary identification provided by NHD Plus HR. All features along the longest path in a watershed possess the same level path attribute. Similarly with the next longest path down to its confluence with the longest path. see [NHD Value Added Attributes](https://www.usgs.gov/national-hydrography/value-added-attributes-vaas#LEVELPATHI)

## seg_distance

Data Type|Decimal
Units|Meters
Description|Distance from the outflow of the level path.

### stream_size

Data Type|Integer
Units|NA
Description|Stream Size Category for determining metric window size

## active_floodplain_area

Data Type|Decimal
Units|Square meters
Description|Total area of Active Floodplain within the analysis window

## active_floodplain_proportion

Data Type|Decimal
Units|Ratio
Description|Proportion of Active Floodplain area to analysis window area

## active_floodplain_area_itgr_width

Data Type|Decimal
Units|Meters
Description|Active Floodplain Area divided by centerline length within the analysis window

## active_channel_area

Data Type|Decimal
Units|Square meters
Description|Total area of Active Channel within the analysis window

## active_channel_area_proportion

Data Type|Decimal
Units|Ratio
Description|Proportion of Active Channel area to analysis window area

## active_channel_area_itgr_width

Data Type|Decimal
Units|Meters
Description|Active Channel Area divided by centerline length within the analysis window

## inactive_floodplain_area

Data Type|Decimal
Units|Square meters
Description|Total area of Inactive Floodplain within the analysis window

## inactive_floodplain_area_proportion

Data Type|Decimal
Units|Ratio
Description|Proportion of Inactive Floodplain area to analysis window area

## inactive_floodplain_area_itgr_width

Data Type|Decimal
Units|Meters
Description|Inactive Floodplain Area divided by centerline length within the analysis window

## floodplain_area

Data Type|Decimal
Units|Square meters
Description|Total area of Floodplain (Active + Inactive) within the analysis window

## floodplain_area_proportion

Data Type|Decimal
Units|Ratio
Description|Proportion of Floodplain to analysis window area

## floodplain_area_itgr_width

Data Type|Decimal
Units|Meters
Description|Floodplain Area divided by centerline length within the analysis window

## integrated_width

Data Type|Decimal
Units|Meters
Description|Integerated Width calculated as window_area / centerline_length

## vb_acreage_per_mile

Data Type|Decimal
Units|acres/mile
Description|window_area converted to acres and divided by centerline_length converted to miles.

## vb_hectares_per_km

Data Type|Decimal
Units|hectares/km
Description|window_area converted to hectares and divided by centerline_length converted to kilometers

## active_acreage_per_mile

Data Type|Decimal
Units|acres/mile
Description|active_floodplain_area plus active_channel_area converted to acres and divided by centerline_length converted to miles

## active_hectares_per_km

Data Type|Decimal
Units|hectares/km
Description|active_floodplain_area plus active_channel_area converted to hectares and divided by centerline_length converted to kilometers

## inactive_acreage_per_mile

Data Type|Decimal
Units|acres/mile
Description|inactive_floodplain_area converted to acres and divided by centerline_length converted to miles

## inactive_hectares_per_km

Data Type|Decimal
Units|hectares/km
Description|inactive_floodplain_area converted to hectares and divided by centerline_length converted to kilometers

## window_size

Data Type|Decimal
Units|Meters
Description|Target Length of analysis window

## window_area

Data Type|Decimal
Units|Square meters
Description|Total area of window

## centerline_length

Data Type|Decimal
Units|Meters
Description|Total length of centerline clipped to window

0 comments on commit f35c05a

Please sign in to comment.