Installation

River Architect applies on ArcGIS Pro’s arcpy package and needs to be executed with ArcGIS Pro’s conda environment (C:\Program Files\ArcGIS\Pro\bin\Python\scripts\propy.bat). The requirements section provides more details and installation hints for external packages. River Architect is designed as an external application rather than a python package, but its modules can be imported as packages for external use (see the Alternative Run sections in the module Wikis).

Installation with Git Bash/GUI

We recommend downloading and updating River Architect using Git Bash (or Git GUI). Alternatively, River Architect can be downloaded as zip file. However, updates are tricky when River Architect is downloaded as zip file.

Git Bash
GitHub provides detailed descriptions and standard procedures to work with their repositories (read more). The following “recipe” guides through the first time installation (cloning) of River Architect:

  1. Open Git Bash

  2. Type cd "D:/Target/Directory/" to change to the target installation directory (recommended: cd "D:/Python/RiverArchitect/"). If the directory does not exist, it can be created in the system explorer (right-click in empty space > New > > Folder).

  3. Clone the repository: git clone https://github.com/RiverArchitect/program

Done. Close Git Bash and start working with River Architect.

Git GUI
For using Git GUI, open Git GUI and choose Clone Existing Repository. Enter the Source Location: https://github.com/RiverArchitect/program, and the Target Directory: D:/Python/RiverArchitect (or any other directory, but ensure that the directory does not exist). Click Clone. Done.

Update with Git Bash/GUI (re- pull)

Currently, Git Bash (or Git GUI) are the only options to update local copies of River Architect. Before updating River Architect, we recommend to save any files and Conditions produced with River Architect externally (create a save copy).

Git Bash
Open Git Bash and do the following:

  1. Go to the local River Architect installation directory: cd "D:/Python/RiverArchitect/program/" (or wherever River Architect was cloned).

  2. Check the current status: git status

  3. Pull changes: git pull

Please note that merge errors may occur when changes were made in the local copy of River Architect. In this case, Git Bash will guide through the manual merge process. If you modified template workbooks (Fish.xlsx or threshold_values.xlsx): Create a .gitignore file in the /RiverArchitect/ directory. Open the .gitignore file with a text editor and enter the following:


/LifespanDesign/.templates/threshold_values.xlsx
/.site_packages/templates/Fish.xlsx

Save the .gitignore file and close the text editor. Now git pull will no longer overwrite Fish.xlsx and threshold_values.xlsx.

Git GUI
Open Git Bash and open D:/Python/RiverArchitect from the Open Recent Repository list (or wherever River Architect is installed). If not listed, click on Open Existing Repository and select the River Architect installation directory. Then:

  1. Click on Rescan.

  2. Click on the Remote drop-down menu > Fetch from > origin.

  3. Click on the Merge drop-down menu > Local Merge.

Launch River Architect

To start using River Architect:

  1. Right-click on DRIVE:\path\to\...\RiverArchitect\Start_River_Architect.bat and click on Edit.

    • In the Start_River_Architect.batchfile, ensure that the Python path is correctly defined according to the installed version of ArcGIS: call EDIT>>"%PROGRAMFILES%\ArcGIS\Pro\bin\Python\Scripts\propy"<<"%cd%\master_gui.py". For more information about running standalone Python scripts in ArcGIS Pro’s conda environment, read their descriptions.

    • Save and close Start_River_Architect.bat.

  2. Double-click on DRIVE:\path\to\...\RiverArchitect\Start_River_Architect.bat to start River Architect.

  3. Create a Condition on the Welcome (Get Started) tab.

  4. Analyze and create ecohydraulic paradises for Physical Habitats prefered by target (fish) species with sustainable river design features using lifespan maps.
    Hint: The Quick GUIde sections in the module Wikis provide straight-forward application guidance.

River Architect starts in a GUI that is stored in master_gui.py. Alternatively, the modules can be individually launched by double-clicking on the LAUNCH_Windows_x64.bat in the module folders (not recommended and may be abandoned in future versions).

ragui

Package structure, requirements and logfiles

File structure

The main directory (/RiverArchitect/) contains the program launcher named Start_River_Architect.bat and the Python3 file master_gui.py. The River Architect modules are located in sub-folders. The master folder (/RiverArchitect/) includes the following files and directories (the full list of all files for developers is available here):

  • .sitepackages Contains adapted third-party Python packages and own packages

    • openpyxl Contains a modified version of the openpyxl package (version 2.5.2) adapted for River Architect

    • riverpy Particular python scripts with recurring routines and classes that are used in multiple modules.

      • cDefinitions.py contains inter-module information of reach and feature keywords.

      • cFeatures.py contains river design features classes with pointers to parameters and threshold values.

      • cFish.py contains the class that reads characteristic species and lifestage data from riverpy/templates/Fish.xlsx.

      • cFlows.py contains classes for creating flow duration curves and interpolating the annual/seasonal flow durations of 2D-modeled discharges.

      • cGravel.py contains subfeatures of the Gravel augmentation-feature in cFeatures.

      • cInputOutput.py contains workbook (.xlsx) read and write routines.

      • cInterpolator.py provides routines for interpolating data between exact data points (x and y).

      • cLogger.py contains the Logger() class that specifies the appearance of logging messages.

      • cMakeTables.py make habitat evaluation workbook tables (.xlsx format).

      • cMapper.py contains mapping routines (see Mapping Wiki).

      • cPlants.py contains subfeatures of the Plantings-feature in cFeatures and the ModifyTerrain module.

      • cReachManager.py processes reach information and reach-wise terrain change (volume differences).

      • cThresholdDirector.py provides the ThresholdDirector() class for reading threshold values from the “thresholds.xlsx” workbook.

      • config.py contains global parameter definitions and pointers to workbooks.

      • fGlobal.py provides functions that are required in this module and the other modules in several classes.

    • templates contains global template files (content will be enriched in future versions)

  • 00_Flows contains templates for flow (discharge) analyses.

  • 01_Conditions contains Condition folders with parameter Rasters. The condition name begins with a 4-digit year number (e.g., 2018), optionally followed by a 3-characters reach ID (e.g., xyz) and a feature layer indicator (e.g., lyr10 for terraforming features). The syllables are separated by an underscore. The process of defining of reaches is explained in the Signposts and the ModifyTerrain Wiki.

  • 02_Maps contains a map templates subfolder that is copied by River Architect’s modules for processed conditions (e.g., 02_Maps/CONDITION/) for Mapping of Rasters and Shapefiles. The following templates and folders may be modified:

    • symbology\ contains a standard symbology layer file (.lyrx) for partially logarithmic lifespan classification

    • river_template.aprx is the standard ArcGIS Pro project file, where developers recommend to adapt background image (layer) connections.

  • Module (folder): RiverArchitect/StrandingRisk for stranding risk analyses of restoration efforts.

    • Output directory where Stranding Risk module outputs are saved.

    • connect_gui.py is a standalone script that creates the graphical user interface (GUI) for running the Stranding Risk module.

    • cConnectivityAnalysis.py provides methods for calculating stranding risk metrics.

    • cGraph.py contains graphic representation routines for habitat connectivity analyses.

  • Module (folder): RiverArchitect/GetStarted prepare input Conditions from scratch or existing conditions.

    • .cache folder occurs temporarily when the module is executed.

    • .templates folder should not be modified and contains the welcome screen imagery.

    • cConditionCreator.py contains a managing class for creating and populating Conditions.

    • cDetrendedDEM.py provides routines for generating detrended DEM Rasters.

    • cMakeInp.py provides routines for creating input files (.inp) for lifespan mapping.

    • cMorphUnit.py provides routines for calculating instream morphological units (Wyrick and Pasternack 2014).

    • cWaterLevel.py provides routines for calculating depth to water table Rasters.

    • fSubCondition.py contains routines for creating a spatial subset of an existing Condition.

    • popup_ ... .py contain popup window classes guiding through the creation and population of Conditions.

    • welcome_gui.py contains the Get Started tab source code.

  • Module (folder): RiverArchitect/LifespanDesign for Lifespan and Design analyses of restoration features.

    • Output folder with sub-folders for Rasters from individual module runs.

    • .cache folder occurs temporarily when the module is executed.

    • .templates folder should not be modified and contains input (*.inp) files; if required, the module includes routines for changing the input files.

    • cLifespanDesignAnalysis.py contains a GIS-based functional core for processing Raster files.

    • cParameters.py contains the parameter input core with pointers to Rasters and Raster names.

    • cReadInpLifespan.py contains classes that read input data from *.inp files.

    • feature_analysis.py coordinates class and function calls.

    • lifespan_design_gui.py is a standalone script that creates the graphical user interface (GUI) for running the LifespanDesign module.

  • Module (folder): RiverArchitect/MaxLifespan for maximum lifespan assessment of feature groups (concurring features)

    • Output folder with sub-folders for Layouts, Maps and Rasters from individual module runs.

    • .cache folder occurs temporarily when the module is executed.

    • .templates folder contains additional Rasters, which are required by this module; other Rasters are loaded from 01_Conditions.

    • action_gui.py is a standalone script that creates the graphical user interface (GUI) for running the MaxLifespan module.

    • action_planner.py coordinates class instantiations and function calls.

    • cActionAssessment.py contains the GIS-based functional core that identifies optimum lifespans and associated features by processing lifespan/design Raster and shape files.

    • cFeatureActions.py contains pointers to river restoration feature data in the LifespanDesign module.

    • cReadActionInput.py contains functions for reading *.inp files from the .templates folder.

  • Module (folder): RiverArchitect/ModifyTerrain performs half-automated terrain modifications

    • Input folder containing optional modified DEMs for volume difference assessment.

    • Output folder with sub-folders Rasters from individual module runs.

    • RiverBuilder folder contains original River Builder code (riverbuilder.r) and input files, as well as help messages.

    • .cache folder occurs when the module is executed.

    • .templates folder contains the reach-defining workbook computation_extents.xlsx.

    • cModifyTerrain.py contains GIS-based functional core for modifying DEM Rasters with threshold values (grading and widening).

    • cRiverBuilder.py contains routines for launching River Builder.

    • cRiverBuilderConstruct.py contains routines for creating input files for River Builder.

    • modify_terrain_gui.py is a standalone script that creates the graphical user interface (GUI) for running the ModifyTerrain module.

    • sub_gui_rb.py contains the GUI for creating River Builder input files.

  • Module (folder): RiverArchitect/SHArC creates Habitat Suitability Index Rasters/maps and quantifies annually usable habitat area for target fish species and user-defined ranges of discharges.

    • CHSI contains subfolders with composite habitat suitability index Rasters for pre- and post-project conditions.

    • HSI contains subfolders with habitat suitability index Rasters for pre- and post-project conditions.

    • SHArea contains result workbooks with SHArea values for examined conditions. The Rasters subfolder contains the associated composite habitat suitability Rasters.

    • .cache folder occurs temporarily when the module is executed.

    • .templates folder contains spreadsheet templates for the quantification of annually usable habitat area and the definition of fish species, lifestages, and associated habitat suitability curves.

    • cHSI.py contains classes to calculate composite habitat suitability Rasters, hydraulic habitat suitability Rasters and interpolating the annual flow duration of considered discharges.

    • sharc_gui.py contains the class of this module.

    • sub_gui_covhhsi.py opens a new GUI window to create cover habitat suitability Rasters.

    • sub_gui_hhsi.py opens a new GUI window to create hydraulic habitat suitability Rasters and determine associated annual flow duration.

  • Module (folder): RiverArchitect/ProjectMaker applies on results from MaxLifespan and SHArC, as well as manual inputs to calculate project cost-benefit metrics.

    • .cache folder occurs temporarily when the module is executed.

    • .templates folder contains a template folder tree and template workbooks with unit cost tables, as well as sample application data that illustrate potential results of the module.

    • cSHArC.py applies SHArC results, in particular cHSI Rasters for calculating SHArea in the project area.

    • project_maker_gui.py contains the class of this module.

    • s20_plantings_delineation.py applies LifespanDesign and MaxLifespan for assessing the most suitable vegetation plantings within the project area.

    • s21_plantings_stabilization.py applies LifespanDesign and MaxLifespan outputs as well as user-defined input parameters for mapping nature-based engineering features required to stabilize vulnerable vegetation plantings.

    • s30_terrain_stabilization.py applies LifespanDesign and MaxLifespan outputs to stabilize terraforming features.

    • s40_compare_wua.py applies on SHArC cHSI Rasters used in cSHArC.py for assessing the annually usable habitat area for a target fish species and lifestage within the project area.

    • LAUNCH_Windows_x64.bat is a batchfile that runs project_maker_gui.py on Windows x64.

  • Module (folder): RiverArchitect/VolumeAssessment calculates excavation / fill volumes of terraforming features.

    • Output folder for calculation results.

    • .cache folder occurs when the module is executed.

    • .templates folder contains volume_template.xlsx.

    • cVolumeAssessment.py contains GIS-based functional core for calculating volumes using an ArcGIS “3D” extension.

    • volume_gui.py is a standalone script that creates the graphical user interface (GUI) for running the VolumeAssessment module

  • Folder: Tools applies on results from MaxLifespan and SHArC, as well as manual inputs to calculate project cost-benefit metrics.

    • .cache folder occurs temporarily when the module is executed.

    • .templates folder contains a template workbooks for multiple purposes.

    • Products folder contains results of any script in this folder.

    • cHydraulic.py contains a class with routines for calculating cross-section-averaged flow characteristics.

    • cInputOutput.py contains classes required for reading and writing data, as well as calculation progress logging.

    • cPoolRiffle.py provides routines for designing self-sustaining pool-riffle channels.

    • fTools.py is a set of functions used by other Python applications within this folder.

    • make_annual_peak.py prepares required input data for statistic flow analyses and with the U.S. Army Corps of Engineers’ HEC-SPP software.

    • make_annual_flow_duration.py - deprecated (will be removed) creates flow duration curves (annual averages) for the assessment of SHArea (deprecated). A more sophisticated version of this function is integrated in the SHArC module with options to limit flow duration assessments to fish-lifestage seasons.

    • morphology_designer.py creates design tables for self-sustaining pool-riffle channels (uses cHydraulic.py and cPoolRiffle.py).

    • run_make_….bat are a batchfiles that run make_….py on Windows.

    • run_morphology_designer.bat is a batchfiles that runs morphology_designer.py.

Program environment setup and batchfile modification

The package is designed for an ArcGIS Pro’s Python3 conda environment. Before launching the River Architect package for the first time, the batchfiles may require adaptions for the system environment. On Windows only (Linux is not yet available because of arcpy issues - we are working on it), set the batch file environment as follows:

  1. Right-click on Start_River_Architect.bat and choose Edit (with Texteditor) or Open with … and choose a Texteditor software.

  2. Check, and if necessary, replace the path to the good python interpreter:
    Default: "%PROGRAMFILES%\ArcGIS\Pro\bin\Python\Scripts\propy"
    Note: Future versions of River Architect’s will require gdal and rasterio. Therefore, developers recommend to create a new conda environment and to install these packages to that new environment:

    • Open “ArcGIS Pro” and click on the Project pane in the upper left corner

    • Click on the Python tab

    • Click on the Manage Environments button and on Clone default (or manually copy the default environment) to, for example, C:\Python\envs\arcgispro-py3-cust

    • When cloning was successful, restart ArcGIS Pro and go back to the Project > Python tab and click on Add Packages

    • Search for, and install gdal (lib-gdal also works) and rasterio

    • For starting River Architect from an IDE, set the new conda environment as interpreter (e.g., C:\Python\envs\arcgispro-py3-cust\python.exe). The new environment may also be used in the batchfiles.

    • The ArcGIS Pro website provides more information on how to install Python packages.

  3. Save LAUNCH_River_ArchitectWINx64.bat and close Texteditor.

  4. Set default application to open input file type documents (*.inp files):
    Go to folder ...\River Architect\LifespanDesign\.templates\ and right-click on mapping.inp to access the menu Open with .... Choose any text editor, such as Notepad, Texteditor or Notepad++ and click OK.

There is no standard easy way to import ArcGIS’ arcpy package in Python running on UNIX platforms (Apple or Linux). Future versions of River Architect aim at using other packages for geodata processing, which will also run on UNIX platforms (we are currently experimenting with gdal and qgis.core).
After editing the batch files, launch River Architect by double-clicking on Start_River_Architect.bat.

Requirements and dependencies

Python packages

The execution of River Architect requires the following packages, which are part of the standard ArcGIS Pro - Python3 distribution:

  • arcpy

  • argparse

  • glob

  • logging

  • openpyxl

  • os

  • shutil

  • subprocess (not mandatory, also works without this package)

  • tkinter

Additional packages:

River Architect incorporates a modified version of openpyxl, but a more proper way is installing openpyxl with ArcGIS Pro’s package manager. Future versions may additionally require the gdal and rasterio packages (see above instructions).
Furthermore, River Architect requires ArcGIS Pro’s “Spatial Analyst” and “3D” (Volume Assessment only) extensions. Another version of River Architect based on open-source geodata processing packages is planned for the future.

Any folder beginning with a “.” for example .cache or .idea must not be modified or assessed by any other program, in particular during the execution of package methods. Files stored in .templates folders are directly called by the GUIs if user definitions are admitted. At the end of execution, the applied modules have created their output folders, which are indicated in the command prompt.

Other software and dependencies

A workbook editing software such as Excel or LibreOffice is required for modifications of user-defined databases (.xlsx files).

For the visualization of geodata (.shp and .tif files), and mapping with project files (.aprx), an installation of ArcGIS Pro is required. Open-source alternatives are QGIS or SAGA (Please note: There are more GIS alternatives out there.).

Logfiles

Logfiles logfile.log are created in the module directories during every run task. These files contain time-stamped terminal messages of program activities, warnings and error messages. Thus, logfiles enable the user to review process duration and to trace back problems. The handling of potential errors and warning messages are listed in the Troubleshooting Wiki with descriptions of problem sources (cause) and solutions (remedy).