Diversion-Runoff Calculator User Manual

Before running the DRC, you'll need to set up your working directory. The working directory is the location where DRC output is written. This is also where you'll stage the python program 'DRC_Lite.py' and the simulation input file identifying all the geospatial data and other peripheral files needed to run the DRC. The working directly should look something like the example below with the two model execution files.

There are several options for running the Diversion-Runoff Calculator (DRC) either through the UCRAF Toolbox in ArcGIS, or through a custom python environment. When running with a custom python environment this is done either through the anaconda command prompt or within an integrated development environment (IDE). The ArcGIS interface is ideal for developing a model from scratch. Power users may prefer to launch runs from the Anaconda command prompt. Developers  may prefer using an IDE like Spyder since the IDE affords a graphical interface with more debugging and package management tools. The IDE requires some additional setup. Instructions on setting up an optional Spyder IDE environment are provided in the section on Anaconda Setup. Other IDEs function similarly.

Using an Existing ArcGIS Conda Environment

If you have a licensed copy of ArcGIS Pro available locally, you already have conda and the ArcGIS API for Python installed on your system. This contains an installation of Miniconda, a smaller version of Anaconda that includes conda, Python, and the package dependencies, as well as a select set of useful packages, namely ArcPy. This is a suitable python environment for running the Diversion-Runoff Calculator.

This gives the user the option to install the UCRAF ArcToolbox and run the model within ArcGIS Pro, or you can open a Python Command Prompt and run the model without installing anything. Detailed instructions on setting up and calling the model from within ArcGIS Pro are available in the Quick Start Guide.

Use the Python Command Prompt shortcut to open a command window initialized with the active conda environment for ArcGIS Pro. Open this by searching for and selecting “Python Command Prompt” in the windows start menu. This opens an active conda environment initialized with the ArcPy functionality as shown below.

To run the DRC, you’ll need various packages including:

• pandas

• os

• matplotlib

• mulitprocessing

• re

• numpy

• openpyxl

• shutil

• subprocess

• geopandas

• fiona

• numba

• shapely

These should already be installed. To confirm this, you can see a list of all the packages included in the active environment by typing: conda list. 

Next, change the directory to your working directory containing the python program and the associated input file. To set the working directory, in the Anaconda Prompt type cd  filepath and hit “Enter”.

To run the DRC type “python” and then a space followed by the name of the python program and the name of the input file that specifies file paths and simulation period, e.g. python DRC_Lite.py inputfile.txt.

As the model runs, some output will display on the screen letting the user know which canal service area is being analyzed, and other such processes. Output files will also appear in the working directory.

Using the Anaconda Command Prompt

If you do not have a licensed copy of ArcGIS Pro available locally, you can use your own Anaconda distribution to run the DRC. The only limitation with this is that you will not have ArcPy available. This means you can only use with standard shapefile/raster datasets.

To open the Anaconda Command Prompt simply type “Anaconda Prompt” into the search bar on the windows start menu. Select the Anaconda Prompt application, which may be labeled 'Anaconda Prompt (anaconda3)', or 'Anaconda Prompt (miniconda3)' if using a Miniconda distribution.

Once the command prompt opens, you'll need to activate the correct environment with gdal installed, for example by typing activate  pygdal_36 and hitting enter. This changes your environment shown at the left of the cursor from the base environment to pygdal_36.

Next, change the directory to your working directory where the DRC_Lite.py program is located. To set the working directory, in the Anaconda Prompt type cd  filepath and hit “Enter”. The filepath is the is the path to your working directory. Notice that the folder path changes from your default folder to the folder where the DRC program is located (see figure below as an example).

To run the DRC type python DRC_Lite.py followed by the input file name (e.g. Duchesne.txt) and then hit Enter.  Assuming “DepletionRunoffCalculator.py” is the Diversion-Runoff Calculator python code in the example below, this model call would as follows: 

The code will run within the Anaconda Prompt. Once finished, the Anaconda Prompt will look something like the following:

Results are available in the “Output_Excel” and “Output_Figures” folders where the Diversion-Runoff Calculator python program is located. These are describe in detail in the section of Model Output.

Using the Spyder IDE

This option requires kernels that allow for interactive or file-based execution of Python code in Spyder. This requires a one-time setup described here.

Once spyder-kernels are installed, open Spyder by going to your search bar on your computer and typing “Spyder”. Select the Spyder App, which may be labeled “Spyder (anaconda3)”.

Load the Diversion-Runoff Calculator python code into Spyder.

Go to File-->Open and then navigate to your working directory that contains the DRC python code (e.g. DRC_Lite.py), select it, then click “Open”.

Once the DRC python script is loaded, hit the Play Button at the top of the program (or F5). Most IDEs, including Spyder have options to run blocks of code (Shift + Return), or even individual lines (F9).

The console display (typically in the bottom-right of the program) should display progress:

Once the program is complete, graphs should appear in the top-right of the program. Make sure the “Plots” button is selected for the display (as seen in the bottom of the following figure).

Results are available in the “Output_Excel” and “Output_Figures” folders where the Diversion-Runoff Calculator python program is located. Running a baseline and change case will not overwrite results. However, subsequent runs from the same working directory will overwrite the current files. To avoid this, create a new working directory when making a fresh run or copy the results to another directory for archival.