Feature lifespan and design assessment

Introduction to lifespan and design mapping
Quick GUIde to lifespan and design maps
Parameter hypotheses
River design and restoration features
Code extension and modification

Introduction to lifespan and design mapping

Survival thresholds applied to a sequence of habitat enhancement features can be spatially compared with hydraulic and sediment data as a result of 2D numerical modeling. Modeled discharges (flows) can be associated with flood return periods that determine feature lifespans. The resulting lifespan maps indicate the temporal stability of particular river design features and techniques. Areas with particularly low or high lifespans help planners optimize the design and positioning of features. Moreover, discharges related to specific flood return periods enable probabilistic estimates of the longevity of particular features. Following these procedures described by Schwindt et al. (2019) (open access factsheet-version), the LifespanDesign module creates Rasters, projects (aprx), and maps (pdf) of the following types:

Lifespan maps qualitatively indicate areas where features make sense and the associated feature lifetime estimate in years.
Design maps indicate dimensional requirements for achieving the success of a feature (e.g., the minimum required log diameter for the stability of wood / LWM).

This Wiki page explains the usage of the LifespanDesign module and it is structured as follows:

A Quick Guide to the application of the code using GUI with descriptions of required input Rasters and alternative launch options.
Physical explanations of relevant parameters.
Explanations of hypotheses in the design of river modification and restoration features.
Coding conventions with descriptions of extension possibilities.

Quick GUIde to lifespan and design maps

Interface and choice of features

After successful Installation and the creation of at least one Condition, lifespan and design maps can be created from the Lifespan -> LifespanDesign tab.

lfgui

To begin with lifespan/design mapping, click on the drop-down menu “Add Features” and select relevant features. Multiple selection is possible and will extend the “Selected features” list. The LifespanDesign module enables the selection of the feature groups of “terraforming” (framework), “vegetation plantings”, “other nature-based engineering” and “connectivity / maintenance”.

Input: Condition and preparation of Rasters

The names of input Raster files are defined in a proper file format (.inp), which can be changed directly from the GUI button “Modify Raster input”. The .inp files indicate after the # if it requires a single Raster name only (STRING) or a list of Rasters (min. two Rasters, LIST). The extension .tif is not required for in the Raster names.
The maximum number of hydraulic Rasters is unlimited. The lifespans related to the hydraulic Rasters are also defined in the separate .inp file. The Get Started module provides routines for setting up input files that must be stored as RiverArchitect/01_Conditions/CONDITION/input_definitions.inp for every Condition.
Modifications of map extents can be made by clicking on the “Modify map extent” button or (un-)check the Limit computation extent to background (back.tif) Raster box.

Input: The threshold values workbook `threshold_values.xlsx` and calculation hierarchy

The “Modify survival threshold values” button opens the master workbook containing threshold values and survival identifiers (location: LifespanDesign/.templates/threshold_values.xlsx). thresholds

Any threshold value can be changed or defined for any feature, but the workbook structure may not be modified (i.e., cells, columns or rows may not be shifted, moved or deleted). The unit system (U.S. customary or SI metric) in the threshold values spreadsheet are independent of the GUI settings but they need to be coherent with the input Rasters of the Condition.

River Architect automatically identifies defined threshold values for selected features. Moreover, River Architect automatically applies all defined threshold values to the extent of Rasters available within a Condition. The identification and execution of possible analyses follow a strictly hierarchical order. If an analysis cannot be executed because of missing threshold value definitions or Rasters, River Architect automatically proceeds to the hierarchically next lower analysis. The analysis hierarchy is defined in order to first created lifespan maps (if row 24 in threshold_values.xlsx is set to TRUE for a feature), and second to save design maps (if row 25 in threshold_values.xlsx is set to TRUE for a feature). When defining threshold values in threshold_values.xlsx carefully study the following hierarchy and parameter application of River Architect (read more about threshold application to features):

Dimensional hydraulic parameter analysis:
- Flow depth starting with the lowest discharge to the highest discharge Raster (hQQQQQQ_QQQ.tif). A threshold value for the flow depth above which a feature will fail can be defined in row 12 in threshold_values.xlsx.
- Bed shear stress τ_b calculated as
  ras_tb = {[uQQQQQQ_QQQ / (5.75 * Log₁₀(12.2 · hQQQQQQ_QQQ / (2 · 2.2 · dmean)))]²}
  where
  - A threshold value for mobility according to the bed shear stress τ_{\b, cr} can be defined in row 6 of threshold_values.xlsx (read more for example in Lamb et al. 2008)
  - ρ_w = water density (1000 kg / m³)
  - uQQQQQQ_QQQ (m/s or fps), hQQQQQQ_QQQ (m or ft), and d84 = 2.2 · dmean (m or ft) are arcpy.Raster()s considering that the grain diameter D₈₄ can be approximated by D₈₄ = 2.2 · D₅₀ (Rickenmann and Recking 2011)
  - g = gravitational acceleration (9.81 m/s²)
  - s = ratio of sediment grain and water density (2.68)
  - Note that the τ_b analysis is omitted if SF is defined, which enables to run either a τ_b analysis OR a mobile grain analysis.
- Flow velocity starting with the lowest discharge to the highest discharge Raster (uQQQQQQ_QQQ.tif). A threshold value for the velocity above which a feature will fail can be defined in row 13 in threshold_values.xlsx.
Dimensionless hydraulic parameter analysis:
- Dimensionless bed shear stress τ_* calculated as
  ras_taux = {ρ_w · [uQQQQQQ_QQQ / (5.75 * Log₁₀(12.2 · hQQQQQQ_QQQ / (2 · 2.2 · dmean)))]²} / [ρ_w · g (s - 1) · dmean]
  where
  - A threshold value for mobility according to the critical dimensionless bed shear stress τ_{*, cr} can be defined in row 7 of threshold_values.xlsx (read more for example in Lamb et al. 2008)
  - ρ_w = water density (1000 kg / m³)
  - uQQQQQQ_QQQ (m/s or fps), hQQQQQQ_QQQ (m or ft), and d84 = 2.2 · dmean (m or ft) are arcpy.Raster()s considering that the grain diameter D₈₄ can be approximated by D₈₄ = 2.2 · D₅₀ (Rickenmann and Recking 2011)
  - g = gravitational acceleration (9.81 m/s²)
  - s = ratio of sediment grain and water density (2.68)
  - Note that the τ_* analysis is omitted if SF is defined, which enables to run either a τ_* analysis OR a mobile grain analysis.
- Froude number Fr as
  ras_Fr = uQQQQQQ_QQQ / (g · hQQQQQQ_QQQ)^1/2
  - A threshold value for mobility according to the Froude number can be defined in row 13 of threshold_values.xlsx
- Mobile grains (bed mobility) ras_Dcr, fine sediment ras_Dcf size Rasters as:
  ras_Dcx = = SF · uQQQQQQ_QQQ² · n² / [(s - 1) · hQQQQQQ_QQQ^1/3 · τ_{*, cr} ] where
  - τ_{*, cr} is the critical dimensionless bed shear stress (i.e., threshold value) above which sediment is mobile (read more for example in Lamb et al. 2008). τ_{*, cr} can be defined in row 6 of threshold_values.xlsx.
  - n is Manning's n in s/m^1/3 (or s/ft^1/3 - an internal conversion factor of k = 1.49 applies), which can be changed in the LifespanDesign GUI
  - SF is a dimensionless safety factor that can be defined within threshold_values.xlsx; the angular boulders / grains threshold definitions indicate the application of a safety factor of 1.3. The Mobile Grain analysis is omitted if SF is not defined, which enables to run either a τ_* analysis OR a mobile grain analysis.
  - Note that a Mobile Grain analysis will only work if a safety factor is defined in row 19 of threshold_values.xlsx.
Topographic change Rasters tcd are applied to limit lifespan Rasters to regions where the fill and scour threshold values defined in rows 22 and 23 of threshold_values.xlsx, respectively, are exceeded. The “Topographic change: inverse relevance” threshold applies when the feature relevance refers to regions where the scour and fill rates below the specific threshold values are relevant. By default, features such as angular boulders (rocks or riprap) are relevant where the topographic change rate (scour) exceeds the angular boulder’s threshold value for scour. However, features such as grading or side cavities, are relevant where the scour or fill rates do not exceed the threshold rates because these areas are presumably disconnected from the river. Thus, “Topographic change: inverse relevance” is TRUE for the grading, side cavity, and side channel features.
A Morphological Unit Raster as produced with the GetStarted module according to Wyrick and Pasternack 2014 can be used to limit lifespan mapping to morphologically reasonable regions. For example, grading of bedrock units is not reasonable and the default threshold_values.xlsx excludes bedrock in row 16. River Architect enables the application of limit morphological units with an exclusive and an inclusive method:
- If the exclusive method is chosen (set row 18 in threshold_values.xlsx to 0), River Architect will look for morphological units listed in row 16 and it will set pixels with these morphological units to NoData in lifespan maps.
- If the inclusive method is chosen (set row 18 in threshold_values.xlsx to 1), River Architect will look for morphological units listed in row 17 and it will set pixels that are not within these morphological units to NoData in lifespan maps.
- Morphological units can be entered as a comma-separated list in row 16 and 17 of threshold_values.xlsx corresponding to the settings made during the morphological unit Raster creation (morphological units are defined in RiverArchitect/.site_packages/templates/morphological_units.xlsx.
Side channel delineation work similar to morphological unit delineation and will only be executed if the Condition folder contains a Raster called sidech (or otherwise named according to the input file in line17). The side channel delineation Raster should only contain Integer values of 1 indicating pixels where a side channel may be drawn. There is no side channel threshold value.
The Depth to the water table table (see d2w.tif Raster creation with the GetStarted module) is particularly important for vegetation plantings or grading (to make terrain suitable for vegetation plantings) features. Threshold values for a lower and an upper limit of the depth to the water table value are defined in row 7 and row 8 of threshold_values.xlsx, respectively. River Architect will set all areas (pixels) that are not within the value range defined in row 7 and row 8 to NoData in lifespan (and design) maps. Leave both rows empty to avoid depth to water table-limited lifespan analyses.
The Detrended DEM threshold values (see dem_detrend.tif Raster creation with the GetStarted module) may be important to limit terraforming features, such as widening/berm setbacks to economically reasonable ranges. Threshold values for a lower and an upper limit of the detrended DEM are defined in row 9 and row 10 of threshold_values.xlsx, respectively. River Architect will set all areas (pixels) that are not within the value range defined in row 9 and row 10 to NoData in lifespan (and design) maps. Leave both rows empty to avoid detrended DEM-limited lifespan analyses.
Nature-based engineering in terms of angular boulders or streamwood are applied to areas (pixels) where a Frequency threshold (row 15 in threshold_values.xlsx) is defined.
Other nature-based engineering than angular boulders or streamwood is applied where the terrain is steep and as a function of depth-to-groundwater (baseflow level). River Architect uses the Terrain Slope threshold values defined in row 20 of threshold_values.xlsx to identify areas (pixels) where other nature-based engineering is required. The Depth to water table thresholds are used to differentiate between vegetative and mineral nature-based engineering. River Architect applies nature-based engineering such as fascines or geotextile between the (min) value in row 7 and the (max) value in row 8. Regions with at terrain slope above the threshold defined in row 20 and above the maximum Depth to the water table defined in row 8 get mineral nature-based engineering (such as rock paving or riprap) assigned. The differentiation is made because nature-based engineering features may dry out when the water table is too far away (vertically).
Design maps indicating the stability of grains (sediment) or wood (logs) extracted after the generation of all above-listed lifespan maps (i.e., design mapping is at the bottom of the hierarchy). Thus, design mapping makes sense for features where grain stability is relevant (including angular boulders, backwater zones, grading, gravel/sediment augmentation, and side channel creation) and for the streamwood feature.
- Set row 25 to TRUE
- For stable grain size design maps, make the following definitions for a feature in threshold_values.xlsx:
  - critical dimensionless bed shear stress τ_{*, cr} in row 6
  - frequency threshold in years in row 15 to define the minimum expected lifespan that is required; River Architect uses hydraulic parameter rasters (hQQQQQQ_QQQ and uQQQQQQ_QQQ) corresponding to the return period defined within the GetStarted module (read more on the calculation of stable grain sizes).
  - optional: set a required maximum grain size (e.g., to ensure the filter stability of sand for increasing the soil capilarity for vegetation plantings, the default value for the Incorporation of fine sediment feature in column S is set to 2.6 cm corresponding to 0.00667 in)
- For stable wood log design maps, make the following definitions for a feature in threshold_values.xlsx:
  - flow depth in row 11 (in m or ft)
  - Froude number in row 13 (dimensionless)
  - frequency threshold in years in row 15 to define the minimum expected lifespan that is required; River Architect uses hydraulic parameter rasters (hQQQQQQ_QQQ and uQQQQQQ_QQQ for the flow depth and Froude number calculation) corresponding to the return period defined within the GetStarted module (read more on the calculation of stable wood log sizes).

More information on threshold values is provided in the Feature descriptions with detailed discussions of the identifiers and threshold values.

Input: Optional arguments

The checkbox “Include mapping after Raster preparation” provides the optional automated mapping of results.
The checkbox “Apply wildcard Raster to spatially confine analysis” can be checked to use a Condition’s wild.tif Raster for spatial limitation of the results. This application makes sense for example if the wildcard Raster contains particular land parcels, where the owner wants to foster habitat enhancement.
The checkbox “Apply habitat matching” provides the option of habitat matching to regions where the habitat suitability index is low (<0.5, see explanations in the SHArC module.
Switching between unit systems (U.S. customary or SI - metric) is possible via the drop-down menu “Units”; please note that the unit system needs to be consistent with all input Raster files.
Manning's n (in s/m^1/3) is used in the grain mobility analysis (Angular boulder feature descriptions) to determine shear velocity that acts on grains. The default value is 0.0473934 s/m^1/3 (the GUI only shows the first three decimal places), which corresponds to a global optimum in the sample case (gravel-cobble bed river). Even if the unit system is set to U.S. customary, Manning’s n is defined in the GUI in SI-metric units (an internal conversion factor of k = 1.49 (i.e., n / k is automatically applied for U.S. customary unit settings). The logfiles (produced during the program execution) will state the applied Manning’s n value if used.

Run

Once all inputs are defined, click on “Run” (drop-down menu) and “Verify settings” to ensure the consistency of the settings (the window will freeze for some seconds). After successful verification, the selected options change to green font.
The “Run” drop-down menu provides the following functions:

Raster Maker prepares lifespan and design Rasters in the directory RiverArchitect/LifespanDesign/Output/Rasters/CONDITION/
Map Maker prepares project maps and PDF assemblies in the directory RiverArchitect/02_Maps/CONDITION/;
Before running Map Maker, ensure that the correct background image (01_Conditions/CONDITION/back.tif) is linked in the project template file RiverArchitect/02_Maps/templates/river_template.aprx.
The mapping extents can be modified using the mapping.inp input file and the Mapping Wiki explains how the symbology, layouts, and other extent settings may be modified.

Either “Run” option causes a run confirmation window popping up and clicking “OK” calls the analysis, which will run in the background Python window and it freezes the GUI windows. Running the Raster Maker may take 0.1 to 10 hours, depending on the input Raster size, feature set and habitat matching options.
After the analysis, the GUI unfreezes and a new button invites to read the logfiles with run information, as well as error and warning messages that may have occurred during the analysis.
Alternatively, the lifespan mapping functions can be imported in other Python applications (without the GUI) as described in the following Alternative Run options.

Alternative run options

The three run options of the GUI call the following methods:

Raster Maker calls feature_analysis.raster_maker for the preparation of Rasters in the directory Output/Rasters/CONDITION/
Map maker calls feature_analysis.map_maker for the preparation of an ArcGIS Pro project (aprx) file and maps assembled in pdfs in the directory RiverArchitect/02_Maps/CONDITION/; by default the layouts stored in RiverArchitect/02_Maps/CONDITION/ underlie the pdf creation but the method also accepts other input directories as an optional argument. Please note that directories always need to be absolute; relative paths will result in errors.

The alternative run options are relevant for example to batch process several Conditions. The first alternative run option is to import the LifespanDesign module in the ArcGIS Pros Python environment as follows:

Prepare input data in .../01_Conditions/CONDITION/ and adapt the background layer image datasets in RiverArchitect/02_Maps/templates/river_template.aprx
Go to ArcGIS Pros Python folder and double-click one of the following:
C:\Program Files\ArcGIS\Pro\bin\Python\scripts\propy.bat or
C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe
Enter import os
Navigate to the script direction using the command os.chdir("ScriptDirectory")
Example: os.chdir("D:/Python/RiverArchitect/LifespanDesign/")
Import the module: import feature_analysis as fa

Once the module is imported three methods are available and their use is intended in the following order:

fa.raster_maker("condition", ∗args) for Raster (GeoTIFF) creation
fa.map_maker("condition", ∗args) for map (pdf) creation

The following steps illustrate the application for creating Rasters.

Basic execution: fa.raster_maker("condition"), for example: fa.Raster_maker("2008_rrr")
The code is now running (this takes two to four hours) and it will prompt its activities.
Alternatively, the analysis can be limited to some features only (count 2 to 60 minutes per feature for input Raster sizes of 5MB and 1GB, respectively). fa.raster_maker("condition", ∗args) accepts optional arguments that are feature_list, which enables the analysis of any feature listed in the Features section. Some examples for particular applications:
-> Example 1: fa.raster_maker("condition", ["Plantings"]) analyzes plantings only.
-> Example 2: fa.raster_maker("condition", ["Plantings", "Boulders/rocks"], True)analyses plantings and angular boulders (rocks / riprap) only with an optional argument that activates the creation of layouts for plantings and angular boulders (rocks).
-> Example 3: fa.raster_maker("2008_rrr")analyses all available features.
The complete list of optional arguments of is as follows:
Hint: Respecting the order of optional arguments is crucial to ensure proper application of the desired analysis options.
- args[0] = feature_list as above described.
- args[1] = mapping, which can be True or False (default).
- args[2] = habitat_analysis, which can be True or False (default) for activating or deactivating habitat delineation (limitation) of restoration features to zones with low habitat suitability (e.g., cHSI = 0.0 to 0.5).
- args[3] = habitat_radius is a float number determining in what distance to low habitat suitability zones restoration features should be applied (default = 400.0 m or ft).
- args[4] = feature_list is either us (default) or si.
- args[5] = feature_listis either True or False (default).

The code creates a temp folder called .cache where it stores temp variables, databases, and Rasters. Avoid accessing .cache while the code is running and ensure its (manual) deletion in the case that the code crashed.

fa.map_maker(∗args, **kwargs) creates pdf map assemblies based on the layout files stored in RiverArchitect/02_Maps/CONDITION/map_CONDITION_design.aprx and Rasters prepared with fa.Raster_maker("condition", ["Featurename"], True). fa.map_maker(∗args, **kwargs) accepts an optional argument defining a CONDITION and a keyworded argument defining map-able reach IDs:

Option 1: fa.map_maker("2018_mod") uses the map folder RiverArchitect/02_Maps/2018_mod/ and Rasters stored in RiverArchitect/Output/Rasters/2018_mod/
Option 2: fa.map_maker("2018_mod", "rrr") uses the map folder RiverArchitect/02_Maps/2018_mod/, Rasters stored in RiverArchitect/Output/Rasters/2018_mod/, and limits mapping to the extents related to a reach "rrr" with its extents defined in RiverArchitect/ModifyTerrain/.templates/computation_extents.xlsx

The second alternative run option for the LifespanDesign module is to run it as a standalone script (feature_analysis.py) from the system command line:

Launch terminal (Start -> type cmd)
Navigate to the place where ArcGIS python.exe is stored:
For example: C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\
Run as script: python.exe DriveLetter:\...\LifespanDesign\feature_analysis("condition", ["Featurename"])
The code asks for a condition, which needs to be typed case-sensitive and without any apostrophes:
For example: Enter the condition (shape: >> XXXX (e.g., >> 2008))>> 2008
Next, the code asks for a feature_list, which is and optional argument (simply hitting enter works though); the feature list must be typed as list (in brackets): Enter the condition (no mandatory; do not forget brackets − example: >> ["Featurename1", "Featurename2"] >> ["Sidecavity", "Bermsetback"]
The program is now running (this takes time) and it will prompt when it finished.

Calling the module as .py script may cause errors because of differences between path interpretation methods and it is limited to the creation of Rasters only. Therefore, the fastest and most consistent way for using the feature_analysis script is to import it as above described.

Output

Rasters

The output Rasters are either of the types lifespan (lf_shortname) or design (ds_shortname) and they are created in .../Output/Rasters/CONDITION/. The usage of shortnames (see the list on the Features page) is necessary because arcpy cannot handle Rasters with names longer than 13 characters when the GRID format is used (even though the standard Raster type is GeoTIFF). The analysis automatically shortens too long Raster names based on shortnames and it creates the condition-output directory if it does not yet exist. Existing files in the Output/Rasters/CONDITION/ folder are overwritten (the code enforces overwriting and tries to delete any existing content (i.e., ensure that the output folder does not contain any important files).

Mapping

The module produces an ArcGIS Pro project file (.aprx) and .pdfs in RiverArchitect/02_Maps/CONDITION/map_CONDITION_design.aprx. The map extents can be modified in the mapping.inp input file. For map modifications, read the above descriptions or the Mapping Wiki.

Interpretation

The success of features corresponds to their ecological sustainability and physical stability, which may positively correlate (i.e., high stability corresponds to high ecological sustainability). However, features such as gravel augmentation or grading have an inverse relationship between ecological sustainability and physical stability. For example, frequently mobile gravel injections create valuable habitat but are, by definition, unstable. In such cases, the lifespan maps need to be considered oppositely: Optimum areas for application correspond to regions with low lifespans (see more in Schwindt et al. 2019).

Quit module and logfiles

The GUI can be closed via the Close dropdown menu if no background processes are going on (see terminal messages). The GUI flashes and rings a system bell when it completed a run task. If layout creation and/or mapping were successfully applied, the target folder automatically opens. After execution of either run task, the GUI disables functionalities, which would overwrite the results and it changes button functionality to open logfiles and quit the program. Logfiles are stored in the RiverArchitect/ folder with the name logfile.log. Logfiles from previous runs are overwritten.