AN ESRI

WHITE PAPER

AUGUST 2019

Arc Hydro: Project

Development Best
Practices
Copyright © 2019 Esri
All rights reserved.
Printed in the United States of America.

The information contained in this document is the exclusive property of Esri. This work is protected under United States copyright law and
other international copyright treaties and conventions. No part of this work may be reproduced or transmitted in any form or by any means,
electronic or mechanical, including photocopying and recording, or by any information storage or retrieval system, except as expressly
permitted in writing by Esri. All requests should be sent to Attention: Contracts and Legal Services Manager, Esri, 380 New York Street,
Redlands, CA 92373-8100 USA.

The information contained in this document is subject to change without notice.

Esri, the Esri globe logo, The Science of Where, ArcGIS, esri.com, and @esri.com are trademarks, service marks, or registered marks of Esri
in the United States, the European Community, or certain other jurisdictions. Other companies and products or services mentioned herein may
be trademarks, service marks, or registered marks of their respective mark owners
Table of Contents
Section Title Page
1.0 Introduction ................................................................................................ 2
2.0 Arc Hydro−Basic Information ................................................................... 2
3.0 Arc Hydro Tools Installation ..................................................................... 3
4.0 Data organization ....................................................................................... 3
4.1 Naming Conventions .......................................................................................... 3
4.2 Initial Database/MXD File Organization ............................................................. 5
5.0 General Items ............................................................................................. 6
6.0 Debugging and Workarounds ................................................................... 8

i
1.0 Introduction

Arc Hydro consists of a data model, toolset, and workflows developed over the years to support
specific geographic information system (GIS) implementations in water resources. The initial
implementation of Arc Hydro was in 2002 with the data model. It was accompanied by an Arc
Hydro book published by Esri Press and a 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. There
are more than 300 Arc Hydro tools now, and they continue to be expanded.

This document captures what works well when implementing Arc Hydro projects. It is based on
many years' experience in implementing ArcGIS and Arc Hydro projects around the world;
providing support and training for Arc Hydro users; and receiving specific feedback from some
of our Arc Hydro users (which is 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.

2.0 Arc Hydro−Basic Information

Here is some basic information about Arc Hydro to keep in mind:

• Arc Hydro is a system of tools and data structures that work in unison to provide a rich
and effective experience for GIS users in the 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 require GIS for more
than just mapping. Respect that.

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

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

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

Arc Hydro: Project Development Best Practices 2 8/2019

 • You should keep the approach to Arc Hydro implementation simple. Ockham's razor is
alive and well!

You may want to use the Arc Hydro mantra: "Analytical system, analytical system, analytical
system . . .". Always consider how what you are doing fits into the system you are developing.
Understand what was done before and what comes after the step you are working on.

3.0 Arc Hydro Tools Installation

When installing Arc Hydro tools:

• Arc Hydro's GeoNet home page will have links to the latest versions of Arc Hydro tools
and specific comments related to the core version of the software (e.g. any required
patches or service packs).

o Go to community.esri.com/community/gis/solutions/arc-hydro/pages/overview.

• The 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 (for a bug
fix or for a new functionality that you would be using). If it ain't broke, don't fix it.

• Always uninstall old versions before installing new ones.

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

o This is mostly the case between major core version updates, but sometimes SPs
will need a separate version. Check Arc Hydro Installation—Versions and
Documentation on the Arc Hydro GeoNet page for clarification on which Arc
Hydro tools are compatible with which core version/SP combinations.

4.0 Data Organization

When organizing Arc Hydro data:

• Use a file geodatabase or special database engine (SDE) for vector data.

• Keep rasters out 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 recommendation has several corollaries (for analytical layers):

o Do not use shapefiles.

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 the appropriate projection based on the analysis being performed (usually equal
area or equal distance—something that minimizes distortions of the data that is relevant
to the analysis).

• Note that layers used for mapping only, can be in different feature datasets or at the
geodatabase level but have the same spatial reference as the one for analytical layers, if
possible.

o An exception is display layers that will be published on the web for display—in
that case, use Web Mercator or a 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, 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 an internal hard drive (HD) if possible (not USB).

o Use an internal solid-state drive (SSD) drive if possible.

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

• Observe that once the initial project database is assembled, you will need to 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.

Arc Hydro: Project Development Best Practices 4 8/2019

 • Set vertical units for the digital elevation model (DEM) if they are not the same as the
horizontal units.

o It is recommended to keep the horizontal and vertical units the same.

4.1 Naming Conventions

The following naming conventions should be followed:

• Keep the 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. An underscore (_) is the only
exception.

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

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

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

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

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

• Keep raster names to no more than 13 characters (although this is not required for non-
Esri grid formats such as TIF).

4.2 Initial Database/MXD File Organization

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

• A project folder that will contain all the project data and MXD files—This excludes base
data that can be anywhere. The project folder will include:

o A subfolder called Layers. This folder is used to store all the raster data. Note the
following:

Arc Hydro: Project Development Best Practices 5 8/2019

  The DEM is usually the starting point of the analysis. 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.

 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

DEM’s spatial reference. The input vector data used in the project is
imported into this feature dataset.

o A project MXD file. Give the MXD file the same name as the geodatabase (e.g.,
aaa.mxd if you have a file named aaa.gdb).

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

o Open a new ArcMap map. Add the project DEM to it first, before any other layer
(or basemap). This will set the spatial reference of the data frame to the spatial
reference of the DEM.

o Save the project 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 the document Arc Hydro—ArcGIS Pro
Project Startup Best Practices. It includes different alternatives in ArcGIS Pro for project startup
that will establish a well-defined Arc Hydro project structure.

5.0 General Items

Following these guidelines will improve your Arc Hydro implementation experience:

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

Arc Hydro: Project Development Best Practices 6 8/2019

 o Go to 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) open at the same time.

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

• Start a new Arc Hydro project only from a newly opened ArcMap session (that is, 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. If in doubt, test
the function in the background with a smaller dataset first and if it completes, run it on
the larger dataset.

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

processing to have any effect.

• When 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., choosing the Save As option).

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

• Perform occasional directory cleanup. Geoprocessing in general and Arc Hydro in

particular generate a lot of temporary files that are stored in the %temp% system
directory. 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 a default ArcGIS geoprocessing target location to store your results—be
explicit about where results are to be directed (your project directory and geodatabase).

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

• Improve the performance of geoprocessing tools that generate many intermediate layers:

Arc Hydro: Project Development Best Practices 7 8/2019

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

o Go to ArcMap Options > General, then uncheck the option Make newly added
layers visible by default.

6.0 Debugging and Workarounds

Things will go wrong.

• They will not go wrong often if you are following the suggestions above.

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

• There will be hardware problems. Lack of system memory and/or hard drive space will
often either generate an ArcMap crash or a generic error message 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 ones. Try to
increase the maximum number of entries a raster attribute table can have. Note that while
this can increase stability of the system, it might also somewhat degrade its performance.

o If you have administrator access, you can use ArcMap Advanced Settings Utility
(you need to be administrator to configure some settings) and increase the
attribute limit under the Raster tab from the default 65,536 to 1,000,000. This
application can be found in the Utilities folder in the ArcMap installation
directory (e.g., typically for ArcGIS 10.5 it is C:\Program Files
(x86)\ArcGIS\Desktop10.5\Utilities).

o If you do not have administrator access, you can change this setting in ArcMap
options. Go to Customize > ArcMap Options > Raster > Raster Dataset, then
modify the Maximum number of unique values to render value. Note that on the
Raster tab, under Options, there are five subtabs. Scroll to the left if you do not
see the Raster Dataset subtab initially.

• There may be problems caused by a raster dataset. Use the Copy Raster option to copy
the raster dataset that might be causing problems. Then use this copy in your work. This
might be needed with some rasters that were not developed using Esri software.

• Data problems result when your data is bad. Do not expect tools to work. Fix the data.

Arc Hydro: Project Development Best Practices 8 8/2019

 • Clear selection on a layer when you want to process everything within that layer.

• There will be data problems if your data is too big. Divide and conquer—split the dataset
into smaller chunks and process it in parts. This might also speed up the overall
processing time, as processing times are nonlinear (especially in the raster domain).

o In many water resources applications, watersheds are natural chunks and make 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 will be minimized if you follow both the best practices presented
here (e.g., steps for eliminating projection mishaps) and well-established Arc Hydro
processing workflows.

• There might be some tool bugs, especially after the release of new core software or major
service packs. If you identify any bugs, 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 and suddenly do not—are

usually related to file locking issues. Try 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 an ArcMap session).

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

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

o Close ArcMap, then reopen it.

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

o Close all apps, reboot, then reopen them.

o Delete the MXD file. Create a new map, add the data, and configure the layers by
choosing Data Management. Set target locations by choosing Set Target
Locations.

Arc Hydro: Project Development Best Practices 9 8/2019