GitLocker: The Coding Marketplace

Description:

rhessysworkflows 1.34

**RHESSysWorkflows** {#index}**Introduction**RHESSysWorkflows provides a series of Python tools for performing[RHESSys](http://fiesta.bren.ucsb.edu/~rhessys/) data preparationworkflows. These tools build on the workflow system defined by[EcohydroLib](https://github.com/selimnairb/EcohydroLib).Before reading ahead, you might want to check out [this screencast](http://youtu.be/vbIqsSVROiU), which provides a conceptual overview RHESSysWorkflows.**Table of Contents**- [Authors](#authors)- [Funding](#funding)- [Source code](#source-code)- [Installation instructions](#installation-instructions) - [Installing on OS X using Homebrew](#installing-on-os-x-using-homebrew) - [Install dependencies for GRASS, QGIS, and RHESSysWorkflows](#install-dependencies-for-grass-qgis-and-rhessysworkflows) - [Install RHESSysWorkflows and Python packages](#install-rhessysworkflows-and-python-packages) - [Upgrading to a new version of RHESSysWorkflows](#upgrading-to-a-new-version-of-rhessysworkflows) - [Install GRASS and QGIS](#install-grass-and-qgis) - [Installing on Ubuntu Linux 14.04 or 15.04](#installing-on-ubuntu-linux-1404-or-1504) - [Install RHESSysWorkflows and Python packages under Linux](#install-rhessysworkflows-and-python-packages-under-linux) - [Upgrading to a new version of RHESSysWorkflows](#upgrading-to-a-new-version-of-rhessysworkflows-1) - [A note on RHESSysWorkflows version numbers](#a-note-on-rhessysworkflows-version-numbers) - [Install GRASS Addons for RHESSysWorkflows](#install-grass-addons-for-rhessysworkflows) - [Setup EcohydroLib and RHESSysWorkflows configuration file](#setup-ecohydrolib-and-rhessysworkflows-configuration-file)- [Using RHESSysWorkflows - Introduction](#using-rhessysworkflows---introduction)- [Using RHESSysWorkflows - Typical workflows](#using-rhessysworkflows---typical-workflows) - [National spatial data workflow](#national-spatial-data-workflow) - [Specify a USGS streamflow data to locate on the NHD network](#specify-a-usgs-streamflow-data-to-locate-on-the-nhd-network) - [Extract NHD catchments that drain through the streamflow gage](#extract-nhd-catchments-that-drain-through-the-streamflow-gage) - [Get bounding box for study area](#get-bounding-box-for-study-area) - [Acquire terrain data from U.S. Geological Survey](#acquire-terrain-data-from-us-geological-survey) - [Extract landcover data from local NLCD 2006 or 2011 data](#extract-landcover-data-from-local-nlcd-2006-or-2011-data) - [Download soils data from SSURGO](#download-soils-data-from-ssurgo) - [Registering custom local data: LAI data](#registering-custom-local-data-lai-data) - [Create a new GRASS location](#create-a-new-grass-location) - [Import RHESSys source code into your project](#import-rhessys-source-code-into-your-project) - [Import RHESSys climate data](#import-rhessys-climate-data) - [Create climate stations map](#create-climate-stations-map) - [Delineate watershed and generate derived data products](#delineate-watershed-and-generate-derived-data-products) - [Generating a patch map](#generating-a-patch-map) - [Generating soil texture map](#generating-soil-texture-map) - [Import LAI map into GRASS](#import-lai-map-into-grass) - [Generate landcover maps in GRASS](#generate-landcover-maps-in-grass) - [Creating the worldfile for a watershed](#creating-the-worldfile-for-a-watershed) - [Creating the flow table](#creating-the-flow-table) - [Initializing vegetation carbon stores](#initializing-vegetation-carbon-stores) - [Running RHESSys models](#running-rhessys-models) - [Working in watersheds outside the United States](#working-in-watersheds-outside-the-united-states) - [Custom local data workflow](#custom-local-data-workflow) - [Import a DEM into your project](#import-a-dem-into-your-project) - [Use a DEM with streams and storm drains burned into it](#use-a-dem-with-streams-and-storm-drains-burned-into-it) - [Import streamflow gage coordinates](#import-streamflow-gage-coordinates) - [Importing data into GRASS for use with RHESSys](#importing-data-into-grass-for-use-with-rhessys) - [Importing other raster layers](#importing-other-raster-layers) - [Landcover data](#landcover-data) - [Rooftop connectivity](#rooftop-connectivity) - [Vegetation LAI](#vegetation-lai) - [Custom patch map](#custom-patch-map) - [Custom soils data](#custom-soils-data) - [Climate station zone map](#climate-station-zone-map) - [Isohyet map](#isohyet-map) - [Generating RHESSys definitions for custom soil data](#generating-rhessys-definitions-for-custom-soil-data) - [Creating a world file template in areas with low slope](#creating-a-world-file-template-in-areas-with-low-slope) - [Creating a surface flow table using a roof connectivity map](#creating-a-surface-flow-table-using-a-roof-connectivity-map) - [Creating the worldfile and initializing vegetation carbon stores](#creating-the-worldfile-and-initializing-vegetation-carbon-stores) - [Running custom commands](#running-custom-commands) - [Creating multiple worldfiles based on subbasins](#creating-multiple-worldfiles-based-on-subbasins)- [Appendix](#appendix) - [Visualizing RHESSys output](#visualizing-rhessys-output) - [OS X](#os-x) - [Linux (Debian/Ubuntu-based systems)](#linux-debianubuntu-based-systems) - [Deprecated installation instructions](#deprecated-installation-instructions) - [OS X 10.7 through 10.10 using Kyngchaos GIS packages](#os-x-107-through-1010-using-kyngchaos-gis-packages) - [Install Xcode (OS X developer tools):](#install-xcode-os-x-developer-tools) - [Install RHESSysWorkflows Python modules (including EcohydroLib)](#install-rhessysworkflows-python-modules-including-ecohydrolib) - [Install GRASS Addons for RHESSysWorkflows](#install-grass-addons-for-rhessysworkflows-1) - [Setup EcohydroLib and RHESSysWorkflows configuration file](#setup-ecohydrolib-and-rhessysworkflows-configuration-file-1) - [OS X 10.6](#os-x-106) - [Download and install Python 2.7 from: http://www.python.org/download/](#download-and-install-python-27-from-httpwwwpythonorgdownload) - [Download setuptools from: https://pypi.python.org/pypi/setuptools/0.8](#download-setuptools-from-httpspypipythonorgpypisetuptools08) - [Install Xcode (OS X developer tools)](#install-xcode-os-x-developer-tools) - [Install PIP, a tool for installing Python modules](#install-pip-a-tool-for-installing-python-modules) - [Install GIS tools: GRASS & QGIS](#install-gis-tools-grass-&-qgis) - [Install GDAL Python modules](#install-gdal-python-modules) - [Install RHESSysWorkflows Python modules (including EcohydroLib)](#install-rhessysworkflows-python-modules-including-ecohydrolib-1) - [Install GRASS Addons for RHESSysWorkflows](#install-grass-addons-for-rhessysworkflows-2) - [Setup EcohydroLib and RHESSysWorkflows configuration file](#setup-ecohydrolib-and-rhessysworkflows-configuration-file-2) - [Install local data](#install-local-data) - [Setup NLCD2006 data](#setup-nlcd2006-data) - [Setup pre-packaged NHDPlusV2 data](#setup-pre-packaged-nhdplusv2-data)Authors-------Brian Miles - brian_miles@unc.eduLawrence E. Band - lband@email.unc.eduFor questions or support contact [Brian Miles](brian_miles@unc.edu)Funding-------This work was supported by the following NSF grants- Award no. 1239678 EAGER: Collaborative Research: Interoperability Testbed-Assessing a Layered Architecture for Integration of Existing Capabilities- Award no. 0940841 DataNet Federation Consortium.- Award no. 1148090 Collaborative Research: SI2-SSI: An Interactive Software Infrastructure for Sustaining Collaborative Innovation in the Hydrologic SciencesSource code-----------Source code can be found at: https://github.com/selimnairb/RHESSysWorkflowsDocumentation can be found at: http://pythonhosted.org/rhessysworkflows Installation instructions-------------------------These instructions will lead you through installing RHESSysWorkflows(and EcohydroLib) as well as GRASS 6.4 and QGIS open source GISapplications; GRASS is required by RHESSysWorkflows, and QGIS isconvenient to have for visualizing GIS data acquired and produced asyou make RHESSys models.These instructions are tailored to OS X and Linux users (specifically Ubuntu 14.04, or 15.04; 15.10 is not compatible as itships with GRASS 7 rather than GRASS 6.4), however installationunder other Linux distributions is also possible. RHESSysWorkflows may in theory work under Windows, but this has never been tested. Windows users are encouraged to run an Ubuntu under a virtual machine.RHESSysWorkflows is compatible with OS X 10.6 through 10.11, but onlyversions 10.9 through 10.11 are officially supported. For installationinstructions for OS X 10.6 through 10.8, see [Deprecated installation instructions](#deprecated-installation-instructions)toward the end of this document.To find out what version of OS X you are currently running, click onthe apple in the upper left corner of the screen and select *Aboutthis Mac*. To find out the latest version of OS X you computer canrun, visit this helpful[page](http://www.everymac.com/systems/by_capability/maximum-macos-supported.html).If you encounter problems during installation, please check the[installationnotes](https://github.com/selimnairb/RHESSysWorkflows/wiki/Installation-Notes)before contacting the developers for support.### Installing on OS X using HomebrewPrevious [methods](#deprecated-installation-instructions) forinstalling RHESSysWorkflows under OS X relied on the official GRASS6.4 GIS[packages](https://grass.osgeo.org/download/software/mac-osx/).Unfortunately, the official GRASS 6.4 (and the new GRASS 7 for thatmatter) are not compatible with new security enhancements in OS X10.11 (El Capitan). Rather than disable this new security measure(called System Integrity Protection), we recommend thatRHESSysWorkflows users use a new [Homebrew](http://brew.sh/)-basedinstallation method, which will install GRASS without requiring that the security features of your operating system be disabled.Homebrew is a third-party package management system that makes it easyto install open-source software under OS X. Each software package onecan install through Homebrew is called a formula. To search foravailable software formula, visit[Braumeister](http://braumeister.org).- Install Homebrew by following the instructions [here](http://brew.sh).> During installation you may be prompted to install OS X command line> developer tools. Choose "Install".**If you already have Homebrew installed, make sure to do the followingbefore proceeding**:```brew updatebrew upgrade```- Next, install the OSGeo4Mac tap for Homebrew by following the instructions [here](https://github.com/OSGeo/homebrew-osgeo4mac).> A tap allows software developers to maintain a collection of> software formulae; OSGeo4Mac curates a number of formula related to> open source GIS software.Now Homebrew is installed and we just need to install a few softwaredependencies before installing RHESSysWorkflows.#### Install dependencies for GRASS, QGIS, and RHESSysWorkflowsFirst, install XQuartz, which is needed by GRASS, by running thefollowing command from the Terminal application: brew install Caskroom/cask/xquartzNext, install Python 2.7: brew install python> Note, this will install a separate copy of Python 2.7 so it will not> interfere with the copy of Python 2 that ships with OS X.#### Install RHESSysWorkflows and Python packagesTo install RHESSysWorkflows and its dependencies (including EcohydroLib), enter the following from the terminal Terminal: pip install rhessysworkflows##### Upgrading to a new version of RHESSysWorkflowsTo upgrade to a newer version of RHESSysWorkflows, enter the followinginto the Terminal: pip install rhessysworkflows --upgrade --force-reinstall If pip does not install the version you expect, it may be necessaryto first remove RHESSysWorkflows and Ecohydrolib before installing the new version (especially under Linux where some Python packages fail tobuild when installed via *pip*): pip uninstall rhessysworkflows pip uninstall ecohydrolibThen install as above: pip install rhessysworkflows #### Install GRASS and QGISInstall GRASS and QGIS using Homebrew as follows from the Terminal: brew install grass-64 gdal-20 qgis-214 --without-server ffmpeg brew link grass-64 --force brew linkapps qgis-214 You will also need to install a Python library for accessing PostGISgeospatial databases; This is required by QGIS: pip install psycopg2 # Do after installing QGIS, which will install PostqreSQLThis concludes the OS X Homebrew-specific portion of the installationinstructions.### Installing on Ubuntu Linux 14.04 or 15.04Install RHESSysWorkflows/EcohydroLib dependencies using apt-get: sudo apt-get install build-essential git subversion p7zip-full \ python python-dev python-pip python-scipy \ libxml2-dev libxslt-dev \ gdal gdal-bin python-gdal \ grass grass-dev \ libbsd-dev ffmpeg vlcNote: the above works for Ubuntu 14.04. For 15.04 the packaging of GDAL has changed use the following to install dependencies underUbuntu 15.04: sudo apt-get install build-essential git subversion p7zip-full \ python python-dev python-pip python-scipy \ libxml2-dev libxslt-dev \ libgdal-dev libgdal-doc gdal-bin python-gdal \ grass grass-dev \ libbsd-dev ffmpeg vlc > Ubuntu 15.10 is not compatible with RHESSys or RHESSysWorkflows> as this version of Ubuntu uses GRASS 7, which is not yet supported> by RHESSys or RHESSysWorkflows. If you want to use another > Linux distribution, make sure that it provides similar versions> of the above dependencies.#### Install RHESSysWorkflows and Python packages under LinuxTo install RHESSysWorkflows and its dependencies (including EcohydroLib), enter the following from your Terminal: sudo pip install rhessysworkflows##### Upgrading to a new version of RHESSysWorkflowsTo upgrade to a newer version of RHESSysWorkflows, enter the following into the Terminal: sudo pip install rhessysworkflows --upgrade --force-reinstall If pip does not install the version you expect, it may be necessaryto first remove RHESSysWorkflows and Ecohydrolib before installing the new version (especially under Linux where some Python packages fail tobuild when installed via *pip*): sudo pip uninstall rhessysworkflows sudo pip uninstall ecohydrolibThen install as above: sudo pip install rhessysworkflowsThis concludes the Linux-specific portion of the installation instructions.### A note on RHESSysWorkflows version numbers Each project can only be used with compatible versions ofRHESSysWorkflows/Ecohydrolib. Compatible versions are those thatwrite the same version number to the metadata store for a givenproject. This compatibility check is necessary to ensure bothscientific reproducibility and to make sure your workflows do notbecome corrupted by incompatible versions. We strive to maintaincompatibility between releases of RHESSysWorkflows/Ecohydrolib,however sometimes enabling new workflow scenarios requiresincompatible changes. The release notes for each release will notewhen a new version breaks backward compatibility. The good news isthat you can have multiple copies of RHESSysWorkflows/Ecohydrolibinstalled on your computer at the same time. To do so, you must dothe following:1. Install [virtualenv](https://pypi.python.org/pypi/virtualenv)2. Create a new virtual environment for each version ofRHESSysWorkflows you would like to run3. Activate a virtual environment you would like to install a specificversion of RHESSysWorkflows into4. Install RHESSysWorkflows in the virtual environment, for example toinstall version 1.0: pip install rhessysworkflows==1.0 Not that you do not need to use 'sudo' when running in a virtualenvironment as the files are installed in a directory owned by youruser account.#### Install GRASS Addons for RHESSysWorkflowsFollow these steps to install the GRASS addons under OS X and Linux:1. Start GRASS: - OS X: In the Terminal, type:```brew link gettext --force # Make sure GRASS's g.extension program can find gettext, which is used in internationalization.grass64``` - Linux: on a command line type: ``` grass64 ``` 2. Create a new location (it doesn't matter where, we'll only use it to runthe g.extension command to install the extensions).3. Install r.soils.texture g.extension extension=r.soils.texture4. Install r.findtheriver g.extension extension=r.findtheriver5. Exit GRASS (close all GUI windows, then type *exit* in the GRASScommand line window).6. On OS X only, once you have exited GRASS do the following:```brew unlink gettext # Re-hide the version of gettext installed by Homebrew, which may conflict of that of OS X.```For more information on these addons (r.soils.texture and r.findtheriver), see:- [r.findtheriver](http://grasswiki.osgeo.org/wiki/AddOns/GRASS_6#r.findtheriver)and r.soils.texture- [r.soils.texture](http://grasswiki.osgeo.org/wiki/AddOns/GRASS_6#r.soils.texture).### Setup EcohydroLib and RHESSysWorkflows configuration file- Choose the appropriate prototype configuration file: + [OS X](https://raw.github.com/selimnairb/RHESSysWorkflows/master/docs/config/ecohydro-OSX-homebrew.cfg) + [Linux](https://raw.github.com/selimnairb/RHESSysWorkflows/master/docs/config/ecohydro-Linux.cfg)- Save into a file named '.ecohydro.cfg' stored in your home directoryand replace all occurances of *<myusername>* with your user name(To find out your OS X or Linux user name, use the *whoami* command inTerminal). - Set ECOHYDROLIB_CFG environment variable so that RHESSysWorkflows can find your configuration file + Under OS X, from Terminal, do the following: echo "export ECOHYDROLIB_CFG=HOME/.ecohydro.cfg">> /.bashprofile+Ifyou′rerunningLinux,dothefollowing:echo"exportECOHYDROLIBCFG={HOME}/.ecohydro.cfg" >> ~/.profile echo "export LD_LIBRARY_PATH=/usr/lib/grass64/lib:You can't use 'macro parameter character #' in math modeYou can't use 'macro parameter character #' in math mode{STATION}.base fileassociated with each climate station. > When we create the world file template later on in this tutorial,> the tool that we use to do so, GenerateWorldTemplate, will make sure> that there is a climate base station file for each unique raster value> in your base station map; the world file template will not be generated> if this is not the case.The second and third columns represent the X and Y coordinates (or easting and northing) of the point feature we will use to represent the location of the climate station. The final column is the name of the climate station and should match STATIONin{STATION}.base (i.e. if your base station file name is 'bwi.base', the final field should be 'bwi').Now we're ready to use GenerateBaseStationMap to: import the climate stationpoints; make Thiessen polygons based on the points, and rasterize the polygons: GenerateBaseStationMap.py -p standard -b /path/to/dummy_stations1.txt> The GRASS tool > [v.voronoi](http://grass.osgeo.org/grass64/manuals/v.voronoi.html)> is used to generate the Thiessen polygons. Note that some versions of> this tool can fail if you have only two points. Hopefully this will be> fixed when GRASS 6.4.3 is released later in 2013.#### Delineate watershed and generate derived data productsRHESSysWorkflows automates the process of delineating your studywatershed based on the location of the streamflow gage registered inthe workflow. As part of this process, many datasets needed byRHESSys will be derived from the DEM. To delineate the watershed: DelineateWatershed.py -p standard -t 500 -a 1.5Here the *-t* (a.k.a. *--threshold*) parameter specifies the minimumsize (in DEM cells) for subwatersheds generated by the GRASS command[r.watershed](http://grass.osgeo.org/grass64/manuals/r.watershed.html).The *-a* (a.k.a. *--areaEstimate*) parameter allows you to provide aguess of the area (in sq. km) of the delineated watershed.DelineateWatershed will report whether the watershed is within 20% ofthe area. You can view the delineated watershed in GRASS by displayingthe raster map named *basin*. If the area or the shape of thedelineated watershed differs greatly from what you expect, you mayneed to vary how DelineateWatershed snaps your streamflow gage ontothe stream network. This is accomplished by either changing the *-s*(a.k.a. *--streamThreshold*) or stream threshold parameter and/or the*-w* (a.k.a. *--streamWindow*) parameter passed to[r.findtheriver](https://svn.osgeo.org/grass/grass-addons/grass6/raster/r.findtheriver/description.html).To debug watershed delineation problems, it is also helpful to viewthe original streamflow gage and the snapped streamflow gage overlaidon the upslope accumulated area map (UAA). DelineateWatershed willcreate vector layers for each of the streamflow gage coordinants(named *gage* and *gage_snapped*) as well as a UAA raster map (named*uaa*).> Though we do not recommend that you make changes to the metadata> store by hand, as a last resort, you can snap the gage location by> hand using GRASS and update the *gage_easting_raw* and> *gage_northing_raw* attributes in the *rhessys* section of the> metadata store. Then re-run DelineateWatershed as before with the> addition of the *--overwrite* option.For a listing of the derived datasets generated by DelineateWatershed,use the GRASS command *g.list rast* or check the DelineateWatershed[sourcecode](https://github.com/selimnairb/RHESSysWorkflows/blob/master/bin/DelineateWatershed.py).#### Generating a patch mapRHESSysWorkflows provides GeneratePatchMap, an automated tool forcreating gridded and clumped patch maps. Gridded patch maps consistof a regular grid of the same resolution and extent as the DEM;clumped maps can be created using elevation or topographic wetnessindex rasters. Modelers can also use custom patch maps registered viaEcohydroLib's RegisterRaster tool and imported into GRASS usingImportRasterMapIntoGRASS (see below for a general description of thiscommand).To create a gridded patch map, enter the following into your Terminal: GeneratePatchMap.py -p standard -t gridTo create an elevation clumped patch map: GeneratePatchMap.py -p standard -t clump -c elevation... and a topographic wetness index clumped map: GeneratePatchMap.py -p standard -t clump -c wetness_indexClumped patch maps are generated by calling GRASS's r.clump commandwith the appropriate source raster as import.> By default GeneratePatchMap will set the zone map to be that of the> patch map, but only if a custom zone map has not been registered> with the workflow (e.g. via a combination of RegisterRaster and> ImportRasterMapIntoGRASS; see custom data tutorial below). If you> wish to overwrite your custom zone map with the patch map, use the > *--forceZone* option to GeneratePatchMap.#### Generating soil texture mapSince we used EcohydroLib's SSURGO tools to generate percent sandand percent clay raster maps for our watershed, we can use the GRASSadd-on r.soils.texture to generate USDA soil texture classes, for whichRHESSys's ParamDB contains parameters. It is also possible to usecustom soil maps, which we'll explore in the *custom local dataworkflow* section below.To generate our soil texture map in GRASS, as well as thecorresponding RHESSys soil definition files, use theGenerateSoilTextureMap tool as follows: GenerateSoilTextureMap.py -p standardThis command will print information about what soil texture classeswere encountered in the soil texture map, and what RHESSys soildefault IDs these classes map onto. You can view the resulting soiltexture map (named *soil_texture*) in GRASS. The soil definitionfiles will be stored in the *defs* directory of the *rhessys* directorystored in your project directory.#### Import LAI map into GRASSWe'll use the general command ImportRasterMapIntoGRASS to import ourLAI map from the project directory into GRASS, where RHESSys will beable to make use of it (you can also derive an LAI map from your landcovermap; see below): ImportRasterMapIntoGRASS.py -p standard -t lai -m nearestThe *-m* (a.k.a. *--method*) paramer specifies how GRASS shouldresample the raster being imported. Value resampling methods arethose supported by GRASS's[r.resamp.interp](http://grass.osgeo.org/grass64/manuals/r.resamp.interp.html)command, as well as *none*, which will cause ImportRasterMapIntoGRASSto skip the resampling step.#### Generate landcover maps in GRASSRHESSysWorkflows uses a single landcover map to generate the following mapsused by RHESSys:- Vegetation type (stratum)- Land use- Roads- Impervious surfaces- Leaf area index (LAI; optional)The first step in generating these maps is to import the landcoverraster from your project directory into GRASS usingImportRasterMapIntoGRASS: ImportRasterMapIntoGRASS.py -p standard -t landcover -m nearestIn our case, the landcover map in our project directory came the NLCD 2011 data hosted by USGS. However, RHESSysWorkflows supports the use ofcustom landcover maps regsitered via RegisterRaster. In either case,we need to provide raster reclassification rules so thatRHESSysWorkflows will know how to generate vegetation, land use,roads, impervious, and optionally LAI maps from the landcover map. To do this, we use the RegisterLandcoverReclassRules tool: RegisterLandcoverReclassRules.py -p standard -kNLCD2011 is a known landcover type in RHESysWorkflows (in addition to NLCD2006),so all we need do is use the *-k* (a.k.a. *--generateKnownRules*)option. For a custom landcover map, we could instead use the *-b*(a.k.a. *--buildPrototypeRules*) option to generate prototype rulesthat we can edit as needed. It is also possible to specify thatexisting reclass rules should be imported from another directory onyour computer using the *-r* (a.k.a. *--ruleDir*) parameter. To include LAI reclass rules when registering prototype or existing rules, you must use the *-l* (a.k.a. *--includeLaiRules*) parameter> The known rules for NLCD2006 and NLCD2011 that ship with RHESSysWorkflows include> an LAI reclass rules file with values for grassland, and evergreen> needle leaf and deciduous broadleaf forests (both temperate) drawn > from the International Satellite Land Surface Climatology Project II> (ISLSCP II) project. These data can be downloaded [here](http://daac.ornl.gov/cgi-bin/dsviewer.pl?ds_id=971).Whether using known rules, building prototype rules, or importingexisting rules, RegisterLandcoverReclassRules will result in thefollowing four rules files being created in the *rules* directory ofyour project directory:- stratum.rule- landuse.rule- impervious.rule- road.rule- lai-recode.rule (if the *--includeLaiRules* option was selected)There is no need to edit these rules for this NLCD2011 example, butyou should take a moment to look at how these rules work.RHESSysWorkflows uses GRASS's[r.reclass](http://grass.osgeo.org/grass64/manuals/r.reclass.html)command ([r.recode](http://grass.osgeo.org/grass64/manuals/r.recode.html)for creating LAI maps), and so the rules files follow this format. It's important to note that the landcover reclass rules for stratum and landuse must result in raster maps whose values labels match class names present in the RHESSys ParamDB database. Thus, be very careful in editing the righthand side of the expressions in your stratum and landuse reclass rules.Note that to keep track of edits you make to your project's reclassrules in your project metadata, you should use the RunCmd workflowcommand (see the section on custom workflows to learn how to use thistool). > You can find information on NLCD classes [here](http://www.mrlc.gov/nlcd2011.php)Once the landcover reclass rules are in place, it is very easy togenerate the raster maps derived from the landcover data as well asthe vegetation and land use definition files needed by RHESSys; thisis done using the following command: GenerateLandcoverMaps.py -p standard> If you would like an LAI map to be generate, you must use the *-l*> (a.k.a. *--makeLaiMap*) parameter on the above command line. This> will only work if you are using known landcover reclass rules, or> if you requested that RegisterLandcoverReclassRules include LAI > reclass rules when creating prototype rules or using existing rules. Like with the soil texture map and definition generation step,GenerateLandcoverMaps will provide descriptive output of thevegetation and land use definition types encountered in the rasterdata.#### Creating the worldfile for a watershedNow we are almost ready to create the worldfile for our watershed. First we must create the template from which the world file will becreated. To do this, we'll use the GenerateWorldTemplate tool. Fortunately this is very easy because the metadata store contains nearly all the information needed to create the template. If you are using multiple climate stations, and therefore have a base stationmap that you created using GenerateBaseStationMap, all you need dois: GenerateWorldTemplate.py -p standard If you are using a single climate station and did not create a climatestation map, you must specify the climate station as follows: GenerateWorldTemplate.py -p standard -c bwiHere we're using the climate station named *bwi*.In either case, if your workflow is missing any information necessaryfor making the world template, GenerateWorldTemplate will exit witha corresponding error.> If you want to see the template file generate, as well as other> information, use the *-v* (a.k.a. *--verbose*) optionNow use the CreateWorldfile tool to create a world file using this template: CreateWorldfile.py -p standard -vWe've specified the the *-v* (a.k.a. *--verbose*) command line option.This will print details about what CreateWorldfile, and the programsit runs on your behalf, is doing. This is recommended as theseprograms can fail in complex ways that CreateWorldfile may not be ableto detect, so you'll likely want to know what's going on under thehood.When CreateWorldfile finishes, it will create an initial worldfilenamed *worldfile_init* in the *worldfiles* directory in the *rhessys*directory in your project directory.#### Creating the flow tableAs with worldfile creation, at this point in the workflow,RHESSysWorkflows's metadata store contains nearly all the informationneeded to create a flow table using the createflowpaths (CF) RHESSysprogram. The two choices you have are whether CF should create a flowtable that includes roads and/or includes a surface flow table tomodeling non-topographic routing of rooftops. We'll route roads inthis example, leaving rooftops for the *custom local data* workflowdiscussed below.Run CreateFlowtable as follows: CreateFlowtable.py -p standard --routeRoadsThis will result in the creation of a flow table called *world.flow*in the *flow* directory of your *rhessys* directory. Now we havealmost everything we need to run RHESSys simulations.#### Initializing vegetation carbon storesRHESSys provides a program called LAIread to initialize vegetationcarbon stores in your worldfile. > Note, LAIread should only be used for RHESSys simulations with > static vegetation (i.e. not dynamic vegetation mode enable via > the *-g* command line option to RHESSys).Initializing carbon stores is a multi-step process that involves running LAI read to generate a redefine worldfile, running a 3-day RHESSys simulation to incorporate the redefine worldfile, writing out a new worldfile with initialized vegetation carbon stores. RHESSysWorkflows automates all of these processes for you, it can even figure out what date to start the 3-day RHESSys simulation on based on your climate data.> In the current version of RHESSysWorkflows, RunLAIRead is only able> to read simulation start dates from point time-series climate data.> Users of ASCII or NetCDF gridded climate data must run LAI read by> hand. The next release of RHESSysWorkflows will add support for> gridded climate data to RunLAIRead.You can run RunLAIRead as follows: RunLAIRead.py -p standard -vNote that we use the verbose command line option here as well. Thenew GRASS-based version of LAIread is relatively new and not as welltested, so we advise you to keep a close watch on what it is doing.LAIread relies on allometric relationships to initialize vegetationcarbon stores. These allometric parameters have not yet been added toRHESSys ParamDB. A default version of the parameters for RHESSys basevegetation classes is stored in the RHESSys ParamDB source code[repository](https://github.com/RHESSys/ParamDB/blob/develop/allometry/allometric.txt).RHESSysWorkflows stores this file under the name *allometric.txt* inthe *allometry* folder of the *ParamDB* of your *rhessys/db* folder. You can edit this file to suit your needs before running RunLAIRead. Consult the[RHESSys wiki](https://github.com/RHESSys/RHESSys/wiki) for more information on allometric relationships used by LAIread.When finished, a final worldfile named *world* will be created in the*worldfiles* directory of your *rhessys* directory. With thisworldfile, you are ready to perform subsequent model workflow stepsincluding: spin-up, calibration, scenario runs, and analysis andvisualization.This concludes this tutorial using RHESSysWorkflows to create aRHESSys world file and flow table using standard spatial datainfrastructure.#### Running RHESSys modelsWe need one more thing before we can run our model, a *TEC file*.TEC stands for "temporal event controller". We use a *TEC file*to tell RHESSys to do things on at certain times during a simulation. For example, to redefine the worldfile to simulate timber harvest or forest fire. We also use tec files to tell RHESSys what model outputs should be produced when. To create a TEC file that tells RHESSys to print daily model outputs starting on 10/1/2008, do the following: RunCmd.py -p standard echo "2008 10 1 1 print_daily_on" > standard/rhessys/tecfiles/tec_daily.txtFor more information on tec file format, see the [RHESSys wiki](https://github.com/RHESSys/RHESSys/wiki/Temporal-Event-Control-File-(TEC-file)). Once you have built a RHESSys model using RHESSysWorkflows, you can runyour model manually. However this will not capture information aboutmodel runs in your project metadata. If you would like to record yourruns in your project metadata, use the RunModel command: RunModel.py -v -p standard -d "Test model run" --basin -pre test -st 2008 1 1 1 -ed 2010 10 1 1 -w world -t tec_daily.txt -r world.flow -- -s 0.07041256017 133.552915269 1.81282283058 -sv 4.12459677088 78.3440566535 -gw 0.00736592779294 0.340346799457 Notice the '--' in the command line. All of the command line options beforethe '--' are options required by RunModel.py; some of these are also commonRHESSys options. All of the options after the '--' will be passed to RHESSys. Because the project metadata knows where RHESSys is installed in yourproject directory, you don't have to specify the full path of any of the RHESSys inputfiles (e.g. world files, flow tables, tec files, etc), just specify the filenames.RunModel will echo RHESSys console outlet to the screen (if the *-v* or verboseoption is specified as above), and will always save the same output intoa file named 'rhessys.out' stored in the output folder for each model run. The outputfolder will be named based on the value you provide for the '-pre' or output prefixoption. ### Working in watersheds outside the United StatesThe above standard U.S. spatial data acquisition workflow steps do notprovide access to data outside the U.S. (by definition). However, it isstill possible to use RHESSysWorkflows to develop RHESSys models for watershedsoutside the U.S. One option is to use custom local data, which is described[here](#custom-local-data-workflow). If you are working in Australia, EcohydroLib (and by extension RHESSysWorkflows) provides access to 1-second (~30-meter) resolution DEM data (derived from SRTM data) using web services interfaces provided by [Geoscience Australia](http://www.ga.gov.au/data-pubs/web-services/ga-web-services).These data can be accessed using the *GetGADEMForBoundingBox* command. A typicalworkflow would begin as follows. First, define your study area using the*RegisterStudyAreaShapefile* command: RegisterStudyAreaShapefile.py -p PROJECT_DIR -s /path/to/my/study/area/shapfile.shp (Replace PROJECT_DIR with the name of your EcohydroLib project).next, extract the bounding box coordinates for your study area: GetBoundingboxFromStudyareaShapefile.py -p PROJECT_DIR then, download Geoscience Australia DEM data: GetGADEMForBoundingBox.py -p PROJECT_DIR Currently, there are three types of DEM data available:* 1 second SRTM Digital Elevation Model of Australia* 1 second SRTM Digital Elevation Model - Hydrologically Enforced* 1 second SRTM Digital Elevation Model - SmoothedTo acquire the *1 second SRTM Digital Elevation Model of Australia* data,run *GetGADEMForBoundingBox* as follows: GetGADEMForBoundingBox.py -p PROJECT_DIR -d dem_1sto acquire the *1 second SRTM Digital Elevation Model - Hydrologically Enforced* data: GetGADEMForBoundingBox.py -p PROJECT_DIR -d dem_h_1s and to acquire the *1 second SRTM Digital Elevation Model - Smoothed* data: GetGADEMForBoundingBox.py -p PROJECT_DIR -d dem_s_1s Consult the [Geoscience Australia metadata catalog](http://www.ga.gov.au/metadata-gateway/metadata/record/gcat_72759)for more information about these data sets. The remainder of your workflow would proceed with importing streamflow gage coordinatesand subsequent steps described [here](#import-streamflow-gage-coordinates). In addition to Australia DEM, EcohydroLib provides access to gridded soils data provided by CSIRO and availble as part of the [Soil and Landscape Grid of Australia](http://www.clw.csiro.au/aclep/soilandlandscapegrid/)dataset. To download these data into your project use the*GetSoilGridAustralia* command: GetSoilGridAustralia.py -p PROJECT_DIR This will download a subset of the available gridded AustraliaSoils Data from the Australia-wide 3D Soil Attributes dataset; currently*GetSoilGridAustralia* will download the percent sand, percent silt, and percent clay layers. Data for the first 1-m of the soil profile isdownloaded, and a depth-weighted average value for each pixel isgenerated using these layers. Once these data have been downloaded,you can use the *GenerateSoilTextureMap* command to generate RHESSyssoil texture map and parameters for USDA soil classes: GenerateSoilTextureMap.py -p PROJECT_DIR See [above](#generating-soil-texture-map) for more details.### Custom local data workflowThe following sections outline how one might use RHESSysWorkflows tobuild RHESSys input files using custom data already available on yourcomputer. Unlike the above standard spatial data tutorial, we won'tprovide data for the workflow steps below. Instead, we'll describehow your data should be formatted to work with each workflow tool.To avoid duplication, only those concepts specific to using local datain RHESSysWorkflows will be discussed. You are encouraged to read thestandard spatial data tutorial above as well. The workflow sequencecovered below is not the only possible workflow involving local data.Also, it is possible to combine steps from this example workflow withsteps from the standard spatial data tutorial.#### Import a DEM into your projectWhen working in watersheds outside the coverage of the NHD (such aswhen working outside of the U.S.) the first workflow step is to importa digital elevation model data using the RegisterDEM tool. The DEMto be imported must be in a format readable by[GDAL](http://www.gdal.org/formats_list.html). Run RegisterDEM as follows: RegisterDEM.py -p PROJECT_DIR -d /path/to/my/DEM.tif -b "City of Springfield, Custom LIDAR"To run this command, replace *PROJECT_DIR* with the absolute orrelative path of an empty directory where you would like the data andmetadata for your project to be stored (i.e. your project directory).It is also possible to reproject or resample the DEM on import. SeeRegisterDEM's help for more information (i.e. run with the *-h*option).RegisterDEM will result in the DEM being copied to your projectdirectory, also the DEM extent will be used to determine the boundingbox for the study area; a polygon of the DEM extent will be generatedand saved as a shapefile in your project directory.#### Use a DEM with streams and storm drains burned into itIf you are working with an urbanized catchment, it is often necessaryto "burn" streams or storm drains into your DEM so that you can properlydelineate the "sewershed." RHESSysWorkflows allows you do use both a"stream burned" and a standard "non-burned" DEM in the same workflow. The burned DEM will only be used for operations that require it (e.g.watershed delineation, flow table creations); the standard DEM will be used for determining elevation, slope, aspect, etc. To use a streamburned DEM, do the following: RegisterRaster.py -p PROJECT_DIR -t stream_burned_dem -r /path/to/my/burnedDEM.tif -b "City of Springfield, Custom LIDAR, storm drain burned with Whitebox GAT 3.1.2"Once the stream burned raster has been registered with the workflow the*DelineateWatershed* and *CreateFlowtable* tools will know to use this rasterinstead of the standard DEM; all other tools that use the DEM will continueto use the standard DEM. If you want to override this behavior (e.g. totest the effect that the burned DEM has on watershed delineation), you canpass the *--ignoreBurnedDEM* option to *DelineateWatershed* or *CreateFlowtable*, which will cause them to use the standard DEM instead.> We recommend the excellent open-source [Whitebox GAT](http://www.uoguelph.ca/~hydrogeo/Whitebox/)> for burning streams into DEM datasets.#### Import streamflow gage coordinates The coordinates of the streamflow gage associated with your watershedare registered with the workflow using the RegisterGage tool. Thetool takes as input a point shapefile containing one or more points;the WGS84 lat-lon coordinates for the desired gage will be extractedfrom the shapefile. These coordinates will be written to the metadatastore, and a new point shapefile containing a point only for theselected gage will be created in the project directory.A typical way to run RegisterGage is: RegisterGage.py -p PROJECT_DIR -g /path/to/gage/shapefile.shp -l DATASET_NAME -a GAGE_ID_ATTRIBUTE -d GAGE_IDTo run this comment, replace *PROJECT_DIR* as above, specify the inputshapefile you'd like to use, the name of the dataset within theshapefile, the name of the ID gage attribute in the dataset, and theID of the desired gage. The name of the dataset is usually the sameas the filename of the shapefile (minus the .shp). If you are unsure,you can use the command line tool[ogrinfo](http://www.gdal.org/ogrinfo.html), which ships with GDAL.#### Importing data into GRASS for use with RHESSysThe following workflow steps are identical whether using standardspatial data or custom local data and will not be covered here:- Create a new GRASS location- Import RHESSys source code into your project- Import RHESSys climate data- Delineate watershed and generate derived data products- Generate landcover maps in GRASSSee the above standard spatial data tutorial for detailed informationon these steps.#### Importing other raster layersFor a list of all of the current raster map types supported byEcohydroLib, run the RegisterRaster tool as follows: RegisterRaster.py -hThis will also show all of the resampling and other import optionsavailable.What follows is a series of examples showing how to input some ofthese raster types. All rasters must be stored in a file formatreadable by GDAL (see above).##### Landcover data RegisterRaster.py -p PROJECT_DIR -t landcover -r /path/to/my/landcover_map.tif --noresample -b "Baltimore Ecosystem Study LTER" --forceHere we are importing a landcover raster map obtained from theBaltimore Ecosystem Study LTER where we've asked RegisterRaster not toresample the raster (unless its spatial reference system differs fromthe DEM; i.e. the resolution of the raster cells won't be changed).We're also telling RegisterRaster to ignore the fact that the extentof the landcover raster does not exactly match the extent of theDEM/study area. After import, you are strongly encouraged tovisualize the landcover map overlaid on the DEM using QGIS to ensurethat the landcover will cover an adequate portion of your study area.> For landcover maps, we recommend that you do not resample when> registering the raster using RegisterRaster, but instead let GRASS> handle the resampling.To make the landcover map in the project directory available toRHESSys, it must be imported into GRASS as follows: ImportRasterMapIntoGRASS.py -p PROJECT_DIR -t landcover -m nearestThis will import the landcover raster into GRASS, and then resamplethe raster using the nearest neighbor method. For a list of validresampling methods, run ImportRasterMapIntoGRASS with the *-h* option;you may also specify *none* as the resampling method and the rasterwill not be resampled.##### Rooftop connectivityStarting with RHESSys 5.16, the createflowpaths (CF) utility is ableto create surface flow tables that can incorporate non-topographicrouting of flow from rooftops to nearby impervious and pervious areas.RHESSys 5.16 can use separate surface and subsurface flow tables tosimulate the effect of such non-topographic routing on the landscape.You can find more information on using surface flowtable routing in RHESSys[here](https://github.com/RHESSys/RHESSys/wiki/Surface-Flowtable-Routing).To import a rooftop connectivity raster, use RegisterRaster as follows: RegisterRaster.py -p PROJECT_DIR -t roof_connectivity -r /path/to/my/roof_map.tif --noresample --force> As with landcover maps, we recommend do not let RegisterRaster> resample roof connectivity rasters, instead letting GRASS handle the> resampling. RegisterRaster uses GDAL to resample rasters. GDAL> ignore null/nodata pixels when resampling, whereas GRASS's> r.resamp.interp does not. Thus, when a landcover and a roof top> connectivity raster, which contains nodata values for all non-roof> pixels, are resampled in RegisterRaster, they can become> mis-registered, which will result in an invalid surface routing> table.Then make your rooftop connectivity raster available for RHESSys byimporting it into GRASS: ImportRasterMapIntoGRASS.py -p PROJECT_DIR -t roof_connectivity -m nearest##### Vegetation LAIAs described in the standard spatial data tutorial above,EcohydroLib/RHESSysWorkflows requires that the user provide their ownLAI data, which can be imported into a project using RegisterRaster: RegisterRaster.py -p PROJECT_DIR -t lai -r /path/to/my/lai_map.tif --forceNow make your LAI raster available for RHESSys by importing it intoGRASS: ImportRasterMapIntoGRASS.py -p PROJECT_DIR -t lai -m none##### Custom patch mapA custom patch map can be imported into a project as follows: RegisterRaster.py -p PROJECT_DIR -t patch -r /path/to/my/patch_map.tif --noresampleThen make your patch raster available for RHESSys by importing it intoGRASS: ImportRasterMapIntoGRASS.py -p PROJECT_DIR -t patch -m none##### Custom soils dataA custom soils map can be imported into a project as follows: RegisterRaster.py -p PROJECT_DIR -t soil -r /path/to/my/soils_map.tif -b "Brian Miles <brian_miles@unc.edu>, based on field observations"Then make your soil raster available for RHESSys by importing it intoGRASS: ImportRasterMapIntoGRASS.py -p PROJECT_DIR -t soils -m none##### Climate station zone mapThe GeneratePatchMap tool will use the patch map as the zonemap. If you wish to use another map for the zone map, do thefollowing after running DelineateWatershed: RegisterRaster.py -p PROJECT_DIR -t zone -r /path/to/my/zone_map.tif -b "Brian Miles <brian_miles@unc.edu>, climate station zones based on lapse rate"Then make your zone raster available for RHESSys by importing it intoGRASS: ImportRasterMapIntoGRASS.py -p PROJECT_DIR -t zone -m none##### Isohyet mapBy default no isohyet map will be used when creating the world file fora watershed. If you wish to use an isohyet map, do the following beforerunning GenerateWorldTemplate: RegisterRaster.py -p PROJECT_DIR -t isohyet -r /path/to/my/isohyet_map.tif -b "Brian Miles <brian_miles@unc.edu>, isohyet map"Then make your isohyet raster available for RHESSys by importing it intoGRASS: ImportRasterMapIntoGRASS.py -p PROJECT_DIR -t isohyet -m none --integer> Note that we tell ImportRasterMapIntoGRASS to transform the isohyet> raster values to integers on import. This is necessary due to limitations> in the current version of the RHESSys tool grass2world. When doing the,> integer conversion, ImportRasterMapIntoGRASS wil multiply the raster> values by 1000, giving three significant digits. To use another value,> specify the *--multiplier* option.#### Generating RHESSys definitions for custom soil dataWhen using custom soil data with RHESSysWorkflows you need to createsoil definition files before you can create a worldfile. To createsoil definitions, you must first create raster reclass rules that mapbetween your soil type and a soil type known to RHESSys ParamDB. Atpresent, ParamDB contains definitions drawn from the literature forUSDA soil textures. However you may load custom soil parameters intoyour own local copy of ParamDB. For more information, see the ParamDB[README](https://github.com/RHESSys/ParamDB).To create prototype soil reclass rules for a project, do the following: RegisterCustomSoilReclassRules.py -p PROJECT_DIR -bHere we're using the *-b* (a.k.a. *--buildPrototypeRules*) commandline option. This will result in the creation of a file called*soils.rule* in the *rules* directory of your project directory. Youwill need to edit this file as necessary to map your custom soil typesto ParamDB soil types. > Make sure that the soil class names on the righthand side of each> reclass rule correspond to soil class names in ParamDBYou can also import existing soil reclass rules as follows: RegisterCustomSoilReclassRules.py -p PROJECT_DIR -r /path/to/my/existing/reclass_rules/The *-r* (a.k.a. *--ruleDir*) parameter must point to a directory thatcontains a file named soils.rule. This will will be copied into the*rules* directory of your project directory.Once you have valid soil reclass rules in place, you can generateRHESSys soil parameter definition files for your custom soils usingthe following command: GenerateCustomSoilDefinitions.py -p PROJECT_DIR This tool will print information to the screen about each soil typeencountered and the RHESSys ParamDB soil parameter classes they mapto. If you see no such print out, check your soil reclass rule fileto make sure it is correct. The resulting soil definition files willbe written to the *defs* directory in the *rhessys* directory of yourproject directory.> Remember most RHESSysWorkflows commands support the *--overwrite*> command line option for overwriting existing data stored in the> project directory or in GRASS.#### Creating a world file template in areas with low slopeDue to limitations in the current version of RHESSys's *grass2world*tool, slope values less than 1.0 will be truncated to 0.0. This causesvalues of NaN (i.e. not a number) to result for the spherical average of aspect calculation. To work around this, you can use the *--aspectMinSlopeOne* command line option to instruct*GenerateWorldTemplate* to use a slope map whose minimum value is 1.0when calculating the spherical average of aspect: GenerateWorldTemplate.py -p PROJECT_DIR --aspectMinSlopeOne -c MY_CLIMATE_STATION1#### Creating a surface flow table using a roof connectivity mapIf you are using a roof connectivity map in your workflow, you need toexplicitly tell CreateFlowtable to use the roof connectivity map togenerate a surface flow table. Do so as follows: CreateFlowtable.py -p PROJECT_DIR --routeRoofs --routeRoadsHere we're using both the *--routeRoofs* and *--routeRoads* options.You are not required to use both together, but usually when modelingrooftop connectivity you will be working in a watershed that also hasroads whose effects on routing you will also want to consider.#### Creating the worldfile and initializing vegetation carbon storesThe following workflow steps are identical whether using standardspatial data or custom local data and will not be covered here:- Creating the worldfile for a watershed- Initializing vegetation carbon storesSee the above standard spatial data tutorial for detailed informationon these steps.#### Running custom commandsRHESSysWorkflows provides many tools for preparing RHESSys models, however there are many possible other tools and workflow stepsthat can be used to build a model. To allow arbitrary commandsto be carried out on data stored in a project directory, RHESSysWorkflows provides the RunCmd command, for example youmay which to edit your worldfile template and then re-run *grass2world*by hand: RunCmd.py -p PROJECT_DIR cp PROJECT_DIR/rhessys/templates/template PROJECT_DIR/rhessys/templates/template.orig RunCmd.py -p PROJECT_DIR emacs PROJECT_DIR/rhessys/templates/template export PATH=PROJECT_DIR/rhessys/bin:You can't use 'macro parameter character #' in math modeYou can't use 'macro parameter character #' in math mode{HOME}/.ecohydro.cfg" >> ~/.bash_profile + Re-load bash profile (or close and open a new Terminal window): source ~/.bash_profileThis concludes installation and configuration instructions for OS X10.7 through 10.10 using Kyngchaos GIS packages.#### OS X 10.6Apple, and thus many third-party software developers, no longersupports OS X 10.6. If you are still running OS X 10.6, you may wantto explore [upgradeoptions](http://arstechnica.com/apple/2014/03/snow-leopard-updates-are-probably-done-here-are-your-os-x-upgrade-options/)as many older Macs can run newer operating systems, upto and includingthe latest version. If your Mac still has some life in it, it isimportant to upgrade from OS X 10.6 this version is no longerreceiving security updates from Apple, and because newer versions havemore security features by design.If you wish to install RHESSysWorkflows on OS X 10.6, follow theinstructions below (though we no longer have a OS X 10.6 machine totest on, so we won't be able to help if you run into problems).Due to its age, there are a few more installation steps needed underOS X 10.6. Also, once Apple stops support this version of the OS,support for OS X 10.6 will also be dropped from subsequent releases ofRHESSysWorkflows. If you were thinking of upgrading from OS X 10.6 to10.9 for other reasons, this may add another.> You will need to use the *sudo* command line tool to install many of> the components needed for EcohydroLib/RHESSysWorkflows. The sudo> command allows you to run other commands as a super user. Under OS> X, by default, only users who are 'admins' have permission to run> sudo. To check if your user account is an administrator, or to make> your user an administrator open *System Preferences > Users &> Groups*. Note that to use sudo, your account will also have to have> a non-blank password. See this Apple support> [article](http://support.apple.com/kb/HT4103?viewlocale=en_US&locale=en_US)> for more information.##### Download and install Python 2.7 from: http://www.python.org/download/Once installation has completed, make sure that Python 2.7 is thedefault Python version by doing the following from the Terminal: python This will load the Python interpreter. The first line of output willdisplay the Python version number. Type *exit()* to exit theinterpreter.##### Download setuptools from: https://pypi.python.org/pypi/setuptools/0.8Install setuptools as follows:1. Unpack the archive by double-clicking on it in Finder2. From Terminal: cd setuptools-0.8 sudo python ez_setup.py##### Install Xcode (OS X developer tools)1. Download and install Xcode 3.2.6 and iOS SDK 4.3 for Snow Leopard[here](https://developer.apple.com/downloads/index.action) (Thisrequires you to register for a free developer account)2. Download and install Git from http://git-scm.com/download/macRHESSysWorkflows uses Git to download RHESSys source code so you don't have to.##### Install PIP, a tool for installing Python modulesPip is the recommended way to install Python modules (i.e. rather thanusing easy_install). For example, Pip allows you to easily uninstallmodules. To install pip, enter the following in a Terminal window: sudo easy_install pip##### Install GIS tools: GRASS & QGISNote, GRASS version 6.4 is required for RHESSysWorkflows (GRASS 7.0 is notsupported at this time). GRASS is used internally to carry out workflow steps (leading to the creation of RHESSys world files and flow tables). You will also find it useful to use GRASS to visualize the results from some workflow steps.To install GRASS on OS X, visit http://www.kyngchaos.com/software/grassHere you will need to download and install the following:1. GDAL Complete framework2. FreeType framework3. cairo framework4. PIL (Python imaging library)5. GRASS.appWhile you are there, we recommend you also install QGIS (Quantum GIS)In addition to GRASS and components installed above, install:1. NumPy from http://www.kyngchaos.com/software/python2. SciPy from http://www.kyngchaos.com/software/python2. Matplotlib Python module from http://www.kyngchaos.com/software/python3. QGIS from from http://www.kyngchaos.com/software/qgisQGIS is useful for visualizing output for earlier workflow steps that precede the importing data into GRASS. ##### Install GDAL Python modulesEven though we installed the GDAL complete framework above, we stillneed to install the GDAL Python modules for the copy of Python 2.7 weinstalled above; the GDAL framework only installs the Python modulesfor Python 2.6, which RHESSysWorkflows is not compatible with. Theseinstallation steps are a little ugly, but bear with me (or upgradefrom OS X 10.6). From a Terminal window type the following: export PATH=You can't use 'macro parameter character #' in math modeYou can't use 'macro parameter character #' in math mode{HOME}/.ecohydro.cfg" >> ~/.bash_profile + Re-load bash profile (or close and open a new Terminal window): source ~/.bash_profileThis concludes installation and configuration instructions for OS X 10.6.### Install local dataRHESSysWorkflows allows you to use local copies of the NationalHydrography Dataset Plus (NHD Plus) to locate USGS streamflow gages,and the National Landcover Dataset (NLCD 2006). If you will be buildingmany models across the U.S. or are running RHESSysWorkflows in a server environment and would like to minimize calls to external webservices, you may wish to install these datasets locally to improveperformance. *This is entirely optional. Most users can ignore thisas querying webservices for these data is preferable to downloadingand installing these relatively large datasets.* #### Setup NLCD2006 dataTo setup a local copy of NLCD2006 land cover data, do the following:- Download NLCD2006 data [here](https://docs.google.com/file/d/0B7aK-9pTSLS-MHRrRTVVRV9zdVk/edit?usp=sharing) It is important that you download this version of the dataset, and not the official data from http://www.mrlc.gov/nlcd06_data.php. The offical data are packaged using a version of PkZip that is not compatible with OS X's GUI or commandline unzip utilities.- Copy NLCD2006 archive to the parent folder where you would like to store it For example, under OS X, create a folder called 'data' in your home directory- Unpack NLCD2006 data (this will take a while...time for a coffee break): + OS X 10.6: From the command line: tar xvjf nlcd2006_landcover_4-20-11_se5.tar.bz2 + OS X 10.7/10.8: double-click on the archive in Finder#### Setup pre-packaged NHDPlusV2 dataIf you want to setup a local copy of NHDPlusV2 data you can obtainthese data by downloading all or a subset of the NHDPlusV2 data andbuilding the database as described in the [EcohydroLibdocumentation](https://github.com/selimnairb/EcohydroLib).Alternatively, you can download a pre-built copy of the NHDPlusV2database needed by RHESSysWorkflows[here](https://docs.google.com/file/d/0B7aK-9pTSLS-dGVzWGRCd1NwNzQ/edit?usp=sharing).To download and unpack the pre-built data, do the following:- Download pre-packaged NHDPlusV2 database [here](https://docs.google.com/file/d/0B7aK-9pTSLS-dGVzWGRCd1NwNzQ/edit?usp=sharing) Note, the compressed data are nearly 7 GB, nearly 11 GB uncompressed, the download may take a while- Copy the pre-packaged NHDPlusV2 database archive to the parent folder where you would like to store it For example, under OS X, create a folder called 'data' in your home directory- Unpack NHDPlusV2 database archive (this will take a while...have a cup of tea) + OS X 10.6: From the command line: tar xvjf NHDPlusV2.tar.bz2 + OS X 10.7/10.8: double-click on the archive in Finder ### Setup EcohydroLib and RHESSysWorkflows configuration file for local data - Choose the appropriate prototype configuration file: + [OS X 10.6](https://raw.github.com/selimnairb/RHESSysWorkflows/master/docs/config/ecohydro-OSX_10.6-local.cfg) + [OS X 10.7/10.8](https://raw.github.com/selimnairb/RHESSysWorkflows/master/docs/config/ecohydro-OSX-local.cfg) + [Linux](https://raw.github.com/selimnairb/RHESSysWorkflows/master/docs/config/ecohydro-Linux-local.cfg)- Save into a file named '.ecohydro.cfg' stored in your home directory Replace all occurances of '<myusername>' with your user name (To find out your OS X or Linux user name, use the *whoami* command in Terminal).- Modify the example configuration to point to your NHDPlusV2 and NLCD2006 local data [if you are using these data]: If you are using OS X, and if you placed the data in a directory called 'data' in your home directory, the only changes you need to make is to substitute '<myusername>' with your user name. If you chose to store local NLCD or NHDPlusV2 somewhere else, simply use the absolute path of each file. - Set ECOHYDROLIB_CFG environment variable so that RHESSysWorkflows can find your configuration file For example, under OS X, from Terminal, do the following: + Open your bash profile in an editor: nano ~/.bash_profile + Add the following at the end of the file: export ECOHYDROLIB_CFG=${HOME}/.ecohydro.cfg + Save the file + Re-load bash profile (or close and open a new Terminal window): source ~/.bash_profile