August, 2019

Arc Hydro: Project

Development Best Practices
Table of Contents
Section Title Page
1.0 Introduction ................................................................................................ 2
1.1 Document history ............................................................................................... 2
2.0 The Arc Hydro Mantra ................................................................................ 2
3.0 Arc Hydro Tools installation ..................................................................... 3
4.0 Data organization ....................................................................................... 3
4.1 Naming conventions........................................................................................... 5
4.2 Initial database/mxd organization ....................................................................... 5
5.0 General Items ............................................................................................. 6
6.0 Debugging and workarounds ................................................................... 8

i
1.0 Introduction

Arc Hydro is a data model, toolset, and workflows developed over the years to support specific
GIS implementations in water resources. The initial implementation of Arc Hydro was in 2002
with the data model, Arc Hydro book published by Esri Press, and initial set of about 30 tools.
Since then, Arc Hydro has been used in many projects and in the process new tools and
workflows have been developed. Arc Hydro tools now number in the 300s and continue to be
expanded based on work on specific implementations.

This document captures what works well when implementing Arc Hydro projects. It is based on
many years of implementing ArcGIS and Arc Hydro projects across the world, support for Arc
Hydro users, training, and specific feedback from some of our Arc Hydro users (always
welcome). There are other recommendations that could/should be made, and this document will
be expanded in the future to include them as they become apparent.

This document is not focused on a specific version of ArcGIS or Arc Hydro – it is a set of
generic recommendations that transcend specific versions. Most of these recommendations will
work well for any ArcGIS project, not just the ones based on Arc Hydro.

1.1 Document history

Table 1. Document Revision History

Version Description Date

1 First Version (DD) 02/2013
2 Minor revisions, new “look” (DD) 01/2019
2.1 Minor revisions, ArcGIS Pro reference (DD) 08/2019

2.0 The Arc Hydro Mantra

• Arc Hydro is a “system” of tools and data structures that work in unison to provide rich
and effective experience for GIS users in water resources community.

• If you are using Arc Hydro, you will most likely be doing ANALYSES – there are
important considerations for GIS implementation when doing analyses that are different
than using GIS just for mapping. Respect that.

Arc Hydro: Project Development Best Practices 2 8/2019

 • When using the tools, you are building a “system”, not just using a “bunch” of
independent tools to produce a “bunch” of independent data.

o Of course, there are plenty of Arc Hydro tools that can be used independently of
the “system”. Use them as such and enjoy.

• When starting an Arc Hydro project, think ahead of the system you will be building. Plan
ahead. Organize, then execute.

• Keep it simple – Ockham ’s razor is alive and well!

• Analytical system, analytical system, analytical system, …

3.0 Arc Hydro Tools installation

• Arc Hydro’s GeoNet home page will have a pointer to the latest released versions of Arc
Hydro tools.

o https://community.esri.com/community/gis/solutions/arc-hydro/pages/overview

• Arc Hydro tool setup can change often. That does not mean that you need to upgrade
each time a new setup is released – do it only if the changes are relevant to you (a bug fix
or a new functionality that you would be using). “If it ain’t broke, don’t fix it”.

• Always uninstall before installing.

• When upgrading to new release of ArcGIS or service pack, always check if there is a new
release of Arc Hydro tools. Do not assume that they are upward (or downward)
compatible.

o This is mostly between major core version updates, but sometimes SPs will need a
separate version. Check the “Arc Hydro Installation – Versions and
Documentation” on Arc Hydro GeoNet page for clarification of which Arc Hydro
tools are compatible with which core version/sp combination.

4.0 Data organization

• Use file geodatabase or SDE for vector data.

• Keep rasters outside of the geodatabase.

Arc Hydro: Project Development Best Practices 3 8/2019

 • Do NOT use unprojected (geographic) data for analysis.

• Keep all the vector layers used in spatial operations and analytics in a single feature
dataset. This has several corollaries (for analytical layers):

o Do not use shape files.

o Do not use data in different geodatabases.

o Import data into a single feature dataset.

• Use the same spatial reference (projection) for raster and vector analytical data.

• Select appropriate projection based on the analysis being performed (usually equal area
or equal distance – something that minimizes distortions relevant to the analysis).

• Layers used for mapping ONLY can be in different feature datasets or at the geodatabase
level but keep the same spatial reference as for analytical layers if possible.

o Exception are display layers that will be published to the web for web display – in
that case use Web Mercator or similar projection.

• Organize all the data for a project into a single “parent” folder if possible.

• Do NOT use the data over a network drive if possible. Instead, copy the data to the local
machine, perform the analysis locally, and then copy the data back to the central location.

o The exception is if you have a specialized network drive with specialized network
connection hardware.

• Use internal HD if possible (not USB).

o Use internal SSD drive if possible.

• If using default Arc Hydro geodatabase/feature dataset creation capabilities, make sure
that the first function that will create the geodatabase/feature dataset is picking up the
right input spatial reference (either from the input dataset or map data frame).

• Once the initial project database is assembled, carefully manage HydroIDs if any of the
input layers have them (they might have to be recalculated). Make sure you adjust the
HydroID dispenser field (LASTID) in the APUNIQUEID table.

• Set vertical units for the DEM if not the same as horizontal.

Arc Hydro: Project Development Best Practices 4 8/2019

4.1 Naming conventions

• Keep names of directories, geodatabases, layers, and attributes short.

o Do not have too many nested subdirectories containing your project folder.

• Do not use spaces or special characters in any of the names. “_” is the only exception.

• Start names always with a letter, never with a number.

• Do not use reserved keywords for names. This includes SQL commands and ArcGIS
commands.

• Develop a “standard” layer nomenclature and apply it consistently (e.g. start all flow
direction rasters with “fdr” followed by descriptor of what flow direction is based on –
e.g. “fil” for filled DEM, so “fdrfil” is a flow direction derived from a filled DEM).

• If using a specific threshold and there is more than one in the project, include the
threshold in the name of the layer (e.g. str50k to indicate a stream grid based on a
threshold of 50,000 cells).

o Not a bad idea even when a single threshold is used in the project.

• Raster names must be kept to less or equal to 13 characters (although this is not required
for non Esri grid formats – e.g. tif)

4.2 Initial database/mxd organization

Standard Arc Hydro database/project organization consists of (recommended, not required):

• Project folder that will contain all the project data and mxds. This excludes base data that
can be anywhere.

o A subfolder “Layers” in the project folder. This folder is used to store all the
raster data.

▪ DEM is usually the starting point of the analyses. Copy the clipped DEM
raster into this folder. Clipping should be based on the relevant project
area of interest. Apply projection if needed. Apply vertical unit
adjustments if needed.

▪ If other rasters are used as inputs, copy them into this folder as well.
Apply projection if needed.

Arc Hydro: Project Development Best Practices 5 8/2019

 ▪ Use input rasters that have the same cell size, extent, and snap layout as
the underlying analytical raster (e.g. DEM and/or flow direction).

o A project geodatabase.

▪ A feature dataset called “Layers” is created within the geodatabase using

selected spatial reference. Input vector data used in the project are
imported into this feature dataset.

o A project mxd. Name the mxd the same as the geodatabase (e.g. if you have
aaa.gdb, call your mxd aaa.mxd).

• Initial workflow if starting from DEM and using Arc Hydro tools to generate project
geodatabase:

o A new ArcMap map is opened. The project DEM is added to it first, BEFORE
any other layer (or base map). This will set the spatial reference of the data frame
to the spatial reference of the DEM.

o The project is saved using the same name you want to give to the geodatabase.
Arc Hydro tools will create the geodatabase and the “Layers” feature dataset
when needed – you do not have to do it yourself. This will happen when the first
Arc Hydro function that generates a vector output is run.

• If using ArcGIS Pro version of Arc Hydro tools, review document “Arc Hydro - ArcGIS
Pro Project Startup Best Practices” on different alternatives in Pro for project startup that
will establish well-defined Arc Hydro project structure.

5.0 General Items

• Leverage Arc Hydro’s GeoNet home page to interact with broader Arc Hydro user’s
community (including Esri’s Arc Hydro development and maintenance team).

o https://community.esri.com/community/gis/solutions/arc-hydro/pages/overview

• Perform Arc Hydro geoprocessing analyses through ArcMap (not ArcCatalog).

• Save your ArcMap project often.

• Save after each major subtask.

• Do not have multiple ArcMap projects (or ArcCatalog) pointing to the same data open at
the same time.

Arc Hydro: Project Development Best Practices 6 8/2019

 • If you need to use ArcCatalog, use it from within ArcMap if possible instead of starting a
separate instance of ArcCatalog.

• When starting a new Arc Hydro project always start from a newly opened ArcMap
session (start a new instance of ArcMap).

• Background processing will in general allow processing of larger datasets, but not
necessarily any faster. And it can cause some functions to malfunction. So test a
function in the background with a smaller dataset first and if it completes run on the
larger dataset.

o You need to have 64-bit geoprocessing support installed for background

processing to have any effect.

• If functions that generate new feature classes have been executed (creating domains in
particular), it is good to save and close the project (close all instances of ArcMap and
ArcCatalog running), and then reopen the project.

• Do not change project name (e.g. save as …).

• If you are doing a lot of geoprocessing and do not need the logs, wipe them out often or
turn logging off (suggested only when working on datasets that were previously tested).

• Geoprocessing in general and Arc Hydro in particular generates a lot of temporary files
that are stored in a %temp% system directory. It is good to wipe that directory clean
from time to time (delete all the files in there that you can after closing all the apps).

• Do not use default ArcGIS geoprocessing target location to store your results – be
explicit where results are directed (your project directory and geodatabase).

• Be aware that some of the Arc Hydro functions need higher versions of licensing.

• To improve performance of executing geoprocessing tools that generate many

intermediate layers:

o Turn off all the layers in the map (no data are displayed).

o Uncheck option “Make newly added layers visible by default” (ArcMap Options -
> General).

Arc Hydro: Project Development Best Practices 7 8/2019

6.0 Debugging and workarounds

• Things will go wrong.

• If you followed the suggestions so far, it will not be often.

• There are several types of problems you will face, and each will require a different
approach to identifying and fixing/or working around.

• Hardware problems. Lack of system memory and/or hard drive space will often either
generate ArcMap crash or a generic error that will be difficult to interpret. If something
used to work, but does not now, check if available resources have changed (HD space or
available memory).

• Some raster functions fail on large integer rasters but work on smaller. Try to increase
maximum number of attributes a raster can have. Use “ArcMap Advanced Settings
Utility” (you need to be administrator to configure some settings) and increase “Attribute
Limit” under “Raster” tab from default 65,536 to 1,000,000. This application can be
found in the “Utilities” folder under ArcMap installation directory (e.g. typically for
ArcGIS 10.5 it is C:\Program Files (x86)\ArcGIS\Desktop10.5\Utilities). Note that while
this can increase stability of the system, it might also somewhat degrade its performance.

• Use “Copy Raster” to copy a raster dataset that might be causing problems. Then use this
copy in your work. This might be needed with some rasters not developed using Esri
software.

• Data problems – your data are bad – do not expect tools to work. Fix the data.

• Make sure you do not have a selected set active when you wanted to process everything.

• Data problems – your data are too big. Divide and conquer – split the dataset into smaller
“chunks” and process in parts. This might also speed up the overall processing time as
processing times are non-linear (especially in raster domain).

o In many water resources applications, watersheds are “natural” chunks and a good
starting point when considering how to chunk up the data. In the USA,
WBD/HUCs are a great starting point for AOI definition.

• Procedural problems – those will be minimized if you followed the best practices
presented here (e.g. projection mishaps will be eliminated) and are following well-
established Arc Hydro processing workflows.

Arc Hydro: Project Development Best Practices 8 8/2019

 • Tool bugs – yes, there might be some, especially after new core software releases or
major service packs. If you identify any, please let us know and we will fix them (often
you will have to provide the data if we cannot reproduce the bug on our test datasets).

• “Gremlins”. Things that used to work in an existing project suddenly do not. This is
usually related to file locking issues. Try to fix by applying fixes in the following order:

o Make sure you have enough HD space and working memory (if you are not
running 64-bit processing/background, you are limited to how much memory is
accessible for processing within ArcMap session).

o Make sure there is only one instance of ArcMap open (this also includes
ArcCatalog).

o Make sure the source and target locations, and layer tags are all properly set.

o Close ArcMap and reopen.

o Close ArcMap and all other apps, delete content of %temp% directory, reopen.

o Close all apps, reboot, reopen.

o Delete the mxd. Start the new map, add the data, and configure the layers using
“Data Management”. Set target locations using “Set Target Locations”.

Arc Hydro: Project Development Best Practices 9 8/2019