Difference between revisions of "Hydrological Analysis Using Whitebox Geospatial Analysis Tools"

From CUOSGwiki
Jump to navigationJump to search
(Created page with "==Purpose== The purpose of this tutorial is to guide the [http://www.qgis.org/en/site/ Quantum GIS (QGIS)] user through the steps necessary to create a slope analysis model wo...")
 
 
(162 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Purpose==
The purpose of this tutorial is to guide the [http://www.qgis.org/en/site/ Quantum GIS (QGIS)] user through the steps necessary to create a slope analysis model workflow using the [http://docs.qgis.org/2.0/en/docs/user_manual/processing/toolbox.html Processing Toolbox]. The user will also learn the basics surrounding the creation of slope, hillshade and aspect maps. The user will also then learn how to export the model as a [http://en.wikipedia.org/wiki/Python_%28programming_language%29 Python] script as well as preform geoprocessing tasks using the QGIS [http://docs.qgis.org/2.0/en/docs/user_manual/working_with_raster/raster_calculator.html Raster Calculator]. This tutorial is designed for a beginner GIS user who has experience with previous GIS software packages however no experience with QGIS.

==Introduction==
==Introduction==
[[File:WhiteBox.png |200px]]
QGIS is a free open source geographical information system application that has geographical viewing, editing and analyzing capabilities. Within QGIS are tools called [https://plugins.qgis.org/ "Plug-ins"]. Plug-ins are essentially developed geoprocessing features made by the QGIS developers as well as independent users who would like to expand and contribute to the functionality of the software. One particular plug-in extension found in QGIS is the Processing toolbox extension. The Processing toolbox extension is similar to the features that are found in ArcMap’s ModelBuilder. Processing is an efficient application that is capable of creating, editing and managing geographical models. The user is able to connect together workflow diagrams that involve a series of geoprocessing algorithms. For the purposes of this tutorial, a workflow will be created using geographical data of [http://en.wikipedia.org/wiki/Carp,_Ontario Carp, Ontario] in order to create a [http://en.wikipedia.org/wiki/Digital_elevation_model digital elevation model (DEM)]. This will then be used to create the slope, hillshade and aspect maps.


This tutorial uses Whitebox tools, an open source GIS software that was developed within the Center for Hydrogeomatics in Guelph University. As a result this software package has a heavy focus on hydrological analysis. For this reason Whitebox was chosen for this tutorial on hydrological analysis. WhiteBox has recently been completely re-written from the ground up using a more advanced backend. This means that the toolset has migrated away from a stand-a-lone software. It is now accessible either through code (Python or R) or as a package using QGIS. This tutorial originally used the older version but has been updated to use the QGIS version in October 2026.
This tutorial was also done as a partial requirement of Carleton University's Advanced Topics in Geographic Information Systems 4008 course.


The area of focus in this tutorial is Calabogie Ontario. This location was chosen because the Calabogie peak adds some relief to the area, and the author knew it well enough to tell if there were any errors that occurred during the analysis process.
[[File:QGIS2.18.13.png|center]]


This tutorial uses a single input, a Digital Elevation model, and produces a multitude of outputs from it, adding information that could be used for future analysis. The process that will be undergone in this tutorial is displayed in the image below. To understand the context of each tool used in this tutorial please refer back to this image as needed.
==Data==
In this tutorial the only necessary layer is a Comma Separated Value (CSV) point elevation file of your area of interest. In this tutorial we are focusing on Carp, ON. It is recommended that you use the Carp, Ontario data for following along. It can be acquired and downloaded [https://www.dropbox.com/s/651jlnr63k92qxc/CarpPointData.csv?dl=0 here].
A sample of this data is shown bellow.


[[File:ExampleData.png]]
[[File:Overview.PNG|800x400px]]


==Data Acquisition==
For the event that the dropbox link has become inactive the process of obtaining this data is described below to make this tutorial relevant for longer.
In this tutorial the only necessary layer is a Digital Elevation Model (DEM) file of your area of interest. In this tutorial we are focusing on Calabogie, ON. It is recommended that you use tthis same dataset for following along.
Access the Government of Canada Geospatial Data Extraction Application [http://maps.canada.ca/czs/index-en.html here].


It can be acquired and downloaded [https://www.dropbox.com/s/gd19qoa0bgqmue3/DEM.tif?dl=0 here].
In the “Find a location” bar enter “Carp” and select the following entry from those that appear:


A sample of this data is shown bellow.
[[File:Extent.png|700px]]


[[File:DataExa.PNG|600px]]
Select the [[File:Zoom.png]] button to center the map on this location.


For the event that the dropbox link has become inactive the process of obtaining this data is described below to make this tutorial relevant for longer.
Next access the bar called “Select clipping area” and select “Current Map Extent”.
Under “Select Data to be extracted” Select “Elevation – Point data”.
Under “Select options and submit job” fill all of the required boxes so that it matches the figure below. Make sure to enter the email address that you would link to have the file sent to in the “Email Address” field.


Access the Government of Canada Geospatial Data Extraction Application [http://maps.canada.ca/czs/index-en.html here].
[[File:DataAccess.png]]


In the “Select Clipping Area” bar enter change the selection to "Predefined Clipping Area" and then select "Drainage areas" from the drop down list that appears.
An email will be sent to the entered email address shortly which contains a URL for the direct download of the data.


[[File:SelectClipArea.png]]
If neither of these options are available, since this tutorial starts with a basic csv file it can be run with any other point elevation csv file.


This produces a long list of sequential drainage area names. Search through the names until you find "02KE000" and select it. I found this on the 17th page of drainage area names.
==Acquiring QGIS 2.18.13==
QGIS version: 2.18.13 (The current long-term release version of QGIS as of October20th 2017 is QGIS 2.18.13 and this was the version used for this tutorial. A list of the download links for all of the versions of QGIS can be found [http://www.qgis.org/en/site/forusers/download.html here].


The map extent on the right side of the web page should now match the image below.
==Getting Started==


[[File:MapExtent.PNG | 600px]]
===Launching QGIS 2.18.13===
When the installation process has finished, an icon should appear on your desktop similar to the one shown below.


[[File:DeskIcon.png]]


Under “Select Data to be extracted” Select “Elevation – Digital elevation model”.
Double-click on that icon and QGIS 2.18.13 will display on your screen.


Under “Select options and submit job” fill all of the required boxes so that it matches the figure below. Make sure to enter the email address that you would like to have the file sent to in the “Email Address” field.
===Setting Project Coordinate Reference System (CRS)===
Following the launch of QGIS 2.18.13, navigate to the top menu bar, select '''Project''', '''Project Properties''', then '''CRS''' on the left column of the popup window.


[[File:ProjectionSelection.png]]
[[File:SelectOptions2.png | 300px]]


An email will be sent to the entered email address shortly which contains a URL for the direct download of the data.
Make sure that '''Enable 'on the fly' CRS transformation''' is checked. Once enabled, filter search '''NAD83 (1)''' and select '''NAD83''' under the '''Geographic Coordinate Systems''' '''(2)'''. When finished select '''OK (3)'''.


If neither of these options are available, any DEM raster can be used.
[[File:ProjectionProperties.png]]


==Acquiring and Installing Whitebox Plugin (QGIS)==
===Adding Point Data===
Please note the previous version of Whitebox used for this tutorial is now [https://github.com/opengeos/whiteboxR/issues/138#issuecomment-4545971338 deprecated] and has transitioned to be used via coding APIs or QGIS only. This tutorial will now use Whitebox Geospatial Analysis Tools in QGIS instead of the older version. This tutorial presumes the user has some QGIS knowledge and already has QGIS installed. For more details, please see the the [https://qgis.org/download/official QGIS download page] for more instructions.


To setup your QIGS workspace for WhiteBox you will need to install the "WhiteBox Workflows for QGIS" plugin.
Adding the Carp elevation data or your desired .csv data requires navigating to the menu bar, select '''Layer''' and '''Add Layer''', '''Add Delimited Text Layer...'''.


To start, find the plugin manager in QGIS by going to plugins > Manage and Install Plugins...
[[File:AddCSV.png]]


[[File:Plugin installer.png|400px]]
In the popup window browse for the .csv file that holds the elevation point data. Select '''CSV (comma separated values)''' for the file type. The rest of the options should default to the correct settings, but if the popup does not match the figure below make sure that you correct these differences.


Then search all plugins for "WhiteBox Workflows for QGIS"
[[File:CSVSettings.png]]


[[File:Install Plugin Whitebox.png|400px]]
Next you will be asked to choose the projection that the data has. As before filter search '''NAD83 (1)''' and select '''NAD83''' under the '''Geographic Coordinate Systems (2)'''. When finished select '''OK (3)'''.


Install the plugin, once that is finished please move on to the next section.
[[File:ProjectionProperties.png]]


==Getting Started==
You should now be able to see your point data in the layers panel but your map view will not be focused on this data. Right click on the point data entry in the layers panel and select '''Zoom to layer'''.
===Accessing WhiteBox Tools===
You're now all set to start using WhiteBox Tools. If you do not see them go to Processing > Toolbox to display the window.


[[File:ZoomTo.png]]
[[File:Toolbox location.png|400px]]


You will find the whitebox tools displayed at the bottom of the list. These tools will be used for the rest of the tutorial so please make sure you have access to them as shown here.
===Converting Point Data to a Shapefile===


[[File:Whitebox in toolkit.png|500px]]
Next we will save this CSV file as a Shapfile to allow for more analysis to be done with it. Right click on the point data entry in the layers panel once again and select '''Save As…'''
===Import DEM into QGIS===
Import the DEM you downloaded into QGIS by adding it as a layer. You can do this by finding the layer in the QGIS browser or simply dragging it from the directory into QGIS. If it correctly imported, you should see the DEM displayed on the screen.


[[File:SaveAs.png]]
[[File:DataExa.PNG|600px]]


==Hydrological Analysis==
In the popup that appears set the format to '''ESRI Shapefile''', set the file name and directory and ensure that the checkbox beside '''Add saved file to map''' is filled. Select '''OK''' once this is done.


[[File:ToShapefile.png]]


===DEM Pre-Processing===
You should now be ready for analysis.


Pre-processing is an important first step in any hydrological analysis as this process identifies and corrects all features within the DEM that may disrupt the flow analysis. Since all products are derived from the DEM it is important to make these corrections at the begging of the process to prevent these errors from carrying through into all of the hydrological outputs.
==Processing Toolbox==


In this tutorial the "Fill Depressions" tool is used to hydrologically correct the DEM. This was chosen because it is much more computationaly efficient than any of the breach tools, finishing much quicker.
===Open Processing Toolbox===


This tool is found in the location below.
If the Processing Toolbox is not already displayed on the right side of the QGIS 2.18.13 window, under '''Processing''' in the menu bar, select '''Toolbox'''.


[[File:Toolbox.png]]
[[File:Fill depressions tool location.png]]


The dialog box that appears for this tool is shown below. The input file should be set to the original Calabogie DEM.
This will display the Process Toolbox on the right side of the screen.


[[File:Image007.png]]
[[File:Fill depressions tool.png|600px]]


The output of this tool is shown below. It does not appear very different to the original DEM, but will closer inspection differences within the areas identified in the Find No-Flow Cells output can be seen.
===Creating a model using Graphical modeler===


[[File:FillDepressionsOtp.PNG|600px]]
To create a model workflow navigate to the menu bar, under '''Processing''', select '''Graphical modeler'''.


===Flow Pointer===
[[File:Image008.png]]


A flow pointer tool in Whitebox is a tool that identifies which area surrounding a cell is the lowest. The value of this cell is then assigned corresponding to the relative direction of this area. This information is not too useful on its own, but it is used as an input to many other hydrology tools because it denotes the direction that water will flow from each cell.
Once the modeler window has opened, you can begin to create the desired workflow. For this particular tutorial, the Carp elevation shapefile will be used to create a slope analysis workflow.


Whitebox has many different flow pointer tools that each use a different method to produce their results.
Before creating the model, you must enter a desired model name and group name '''(1)'''. I named my model '''Slope Analysis Turotial''' under a group name called '''GEOM 4008'''. Once a model and group name have been entered, select '''Save (2)''', and save the model to your desired folder. I would recommend creating a folder just for QGIS models under this project.
In this tutorial "D8 Flow Pointer" was used because many of the tools in the "Watershed Tools" toolset will only work with the output from the D8 Flow Pointer as an input.
This tool is found in the location shown below.


[[File:D8 flow tool location.png]]
To begin your model, you'll first have to add an input parameter. On the left side of the modeler window, select '''Vector Layer (3)'''. That will then display a '''Parameter definition (4)''' window. Enter the '''Parameter name''' as '''Input elevation points''' (or something similar), '''Shapefile''' to '''Point''', and '''Required''' to '''Yes'''. Select '''Ok'''.


The dialog box for this too is shown below. The input DEM raster file should be set to the output from the Fill Depressions tool.
Now navigate to the '''Algorithm (5)''' tab, to being adding geoprocessing algorithms.


[[File:InputParameter.png]]
[[File:D8 flow tool.png|600px]]


The output from this tool is displayed below. This image contained 8 colours corresponding to the 8 directions of flow. This image appears chaotic, but will be used in other tools to create more informative data products.
===Adding Geoprocessing Algorithms===


[[File:FlowPointerOtp.PNG|600px]]
====3D transformation====


===Flow Accumulation===
The first algorithm that will be added will transform our 2-dimensional point data into a 3-dimensional dataset. This is required because by default point data in QGIS is interpreted as 2-dimensional meaning that only the X and Y values from the attribute table are considered for analysis, not the Z which is the elevation data. The algorithm used can be found by doing a search filter for '''3D (1)''', and select '''v.to.3d (2)''' under '''GRASS Commands'''.
A window will open asking for the specifications '''(3)'''. Enter the specifications that you desire.
Make sure that the '''Input layer''' is the elevation point data initially added, and that the Name of attribute column used for height is '''Z'''. Also add an '''Output Vector''' name of your choice. Select '''OK'''.


Flow Accumulation tools analyze the magnitude of cells that pour into or through an area.
[[File:3D.png]]
This is useful on its own, allowing us to determine the relative flow through areas by comparing values of the output, and is also used as an input for many other analyses.


In this tutorial the "D8 Flow Accumulation" tool was used, as this was the one that corresponded to the D8 Flow Pointer output that was created with the previous tool.
====Inverse Distance Weighted (IDW)====
This tool is located in the location displayed below.


[[File:D8 accumulation tool location.png]]
The second algorithm that will be added is an '''Inverse Distance Weighted (IDW)''' [http://en.wikipedia.org/wiki/Interpolation interpolation]. This particular algorithm can be found by doing a search filter for '''IDW (1)''', and select '''v.surf.idw (2)''' under '''GRASS Commands'''.


The dialog box for this tool is displayed below. The input D8 flow pointer raster file should be set to the output from the D8 flow pointer tool. In the example the "Output Type" was set to "cells" so that a greater cell value in the output would correspond to a greater number of cells flowing through that cell. The "Log-transform output" box was left unchecked in this example, though checking this would help normalize the data for better display. After these inputs have been set click, run the tool.
A window will open asking for interpolation specifications '''(3)'''. Enter the specifications that you desire.


[[File:D8 accumulation tool.png|600px]]
Make sure that the '''Input layer''' is the output from the '''2D to 3D transformation'''.


The output of this tool is displayed below. The brighter areas correspond to areas of higher accumulated flow. These areas of high flow correspond to the areas where more water gathers and flows together. A beter picture of the data can be gathered by zooming into the output in Whitebox.
For my slope analysis, I had to enter '''Z''' into the '''Attribute table column with values to interpolate''' field because the column under the '''PointDataShapefile''' Attribute Table used for elevation points is named '''Z'''.


[[File:FlowAccumulationOtp.PNG|600px]]
I also used a '''GRASS region cellsize''' of '''0.0005'''. This can be changed if you'd like, although it may take longer to process with a smaller cell size value. Also add an '''Output raster''' name of your choice. Select '''OK'''.


===Isobasin===
[[File:IDW.png]]


The isobasin tool divides a study area into equally sized drainage areas (iso-basins) of a specified size.
====Slope====


The location of this tool is displayed below.
Following the IDW interpolation, a slope map expressed in degrees will be created using the IDW output.


[[File:Isobasins tool location.png]]
Execute a search filter for '''Slope (1)''', and select '''Slope (2)''' under '''GDAL/OGR'''.


The dialog box for this tool is displayed below. The input is the original, hydrologically conditioned (depression fill) raster.
This will display a window for the Slope geoalgorithm '''(3)'''. Leave the field parameters as default except for '''Slope expressed as percent''' to '''No'''. Make sure that the '''Input layer''' is the '''Interpolated IDW output'''.


[[File:Isobasins tool.png|600px]]
Also add an '''Output raster''' name of your choice. Select '''OK'''.


The output from this look is displayed below. It can be seen that the area has been broken down into 11 different basins of approximately equal size. It also appears that the basins do not fill the entire study area. This is likely because no more basins of a size of 500,000 cells could be fit into these areas. If the target basin size was set to a lower number these basins would conform to the study area more completely.
[[File:SlopeAlg.png]]


[[File:IsobasinOtp.PNG|600px]]
====Aspect====


===Extract Streams===
Execute a search filter for '''Aspect (1)''', and select '''Aspect (2)''' under '''GDAL/OGR'''.


Stream networks can be useful as an input for other tools. Also, on their own they allow knowledge of areas of high water and nutrient flow, as well as connecting areas between water habitats.
This will display a window for the Aspect geoalgorithm '''(3)'''. Leave the specifications as default. Make sure that the '''Input layer''' is the '''Interpolated IDW output'''.


The "Extract Streams" tool was used for this purpose. This tool extracts all values from a flow accumulation output that are greater than the specified value. This tool is part of the "Stream Network Analysis" toolset.
Also add an '''Output raster''' name of your choice. Select '''OK'''.
The location of this tool is displayed below.


[[File:AspectAlg.png]]
[[File:Extract streams tool location.png]]


The dialog box for this tool is displayed below. The input flow-accumulation raster file should be set to the output from the D8 Flow Accumulation (D8 Flow Accumulation). The "Channelization Threshold" is the cutoff value that will be used to determine which cells are a stream and which cells aren't. Trial and error was used to determine a value that produced an appropriate stream network. A value of 5,000 was settled on. Please make sure to check the "If true, non-stream background is 0 instead of NoData" box. This is because later tools in this analysis require rasters without NoData values.
====Hillshade====


[[File:Extract streams tool.png|600px]]
Execute a search filter for '''Hillshade (1)''', and select '''Hillshade (2)''' under '''GDAL/OGR'''.


The output of the tool is displayed below. This output looks patchy at the full extent, but by zooming into it within Whitebox you can confirm that a network of continuous lines has been produced.
This will display a window for the Hillshade geoalgorithm '''(3)'''. Leave the specifications as default. Make sure that the '''Input layer''' is the '''Interpolated IDW output'''.


[[File:ExtractStreamsOtp.PNG|600px]]
Also add an '''Output raster''' name of your choice. Select '''OK'''.


===Sub-basins===
[[File:HillShade.png]]


The sub-basin tool breaks the down the study area into a number of basins, with one basin for each segment of a stream network for the area. As a result each of these basins represent the catchment area for each segment of the river network.
===Running a model===


The location of this tool is displayed below.
Once all of the geoprocessing algorithms have been added, the model should look similar to the capture below.
<br>


[[File:Subbasins tool location.png]]
Make sure that you '''Save (1)''' the model before '''Running the model (2)'''.
<br>


The dialog box for this tool is displayed below. The input streams raster file should be set to the output from the extract streams tool, and the input D8 flow pointer raster should be set to the output from the D8 flow pointer tool . After these inputs have been set, run the tool.
[[File:RunModel.png]]
<br>


[[File:Subbasins tool.png|600px]]
When the '''Run model''' button is select, a window the same as the capture below will appear.
<br>


The output from this tool is displayed below. This image shows a much greater number of basins than any of the outputs from other tools in this tutorial, likely due to the complexity of the stream network fed into the tool. It would be expected that if the channelization threshold used for the extract streams tool was higher, there would be less sub-basins, and if it was lower there would be more.
In this window make sure you save the output files to an appropriate destination folder. Select '''OK''' to run the model.
<br>


[[File:SubbasinsOtp.PNG|600px]]
Also check to make sure that '''PointDataShapefile''' is the '''Input elevation points''' that will be Transformed first in the model.


===Watershed Analysis===
[[File:FullModel.PNG]]
In order to run the Watershed tool this first step will be to create pour points. Once this is done The watershed analysis can be done.
====Pour Points====
Pour points are used in watershed analysis to define each of the watersheds that will be output. Simply put, a watershed is the entire area that flows into a pour point. As a result the placement of these pour points greatly effects the output of the watershed analysis. Pour points are usually located in areas of high accumulated flow, so are usually located on points of a stream network.


There is no way to create a pour point file in Whitebox automaticaly, so this must be done manualy. You can do this by creating a new point layer in QGIS. Go to layer > Create layer
Once the model is finished running, the output layers will be displayed in the '''Layer''' toolbox on the left side.


[[File:LayerOutput.png]]
[[File:Create new layer location.png | 400px]]


You can create whichever data structure you prefer for vectors, for this tutorial we use a shapefile. Make sure to set your CRS to the same CRS as the hydrological products that have already been created. Then set the geometry type to Point. Your dialog box may look something like below.
===Displaying output rasters from model===


[[File:Create points layer.png | 500px]]
Once the model is run and the output rasters appear in the '''Layer''' toolbox. They will only appear as single band image styles.


Pour points must now be identified and added. Before this can be done, the layers in the data tab have to be set up. I made sure that only the extract streams output and the create blank outlet raster output were visible.
One way to change this is to change this '''right click''' on '''Output IDW''', select '''Properties'''.


Next the vector layer must be set to editing mode, start by enabling editing like so.
[[File:IDWProperties.png]]


[[File:Toggle editing.png]]
A '''Layer Properties''' window will appear. Navigate to '''Style (1)''', select the '''Render type''' to '''Singleband pseudocolour (2)'''. The rest of the properties can be changed to your personal desire. For my output I selected '''Spectral (3)''' for the color and '''Quantile''' mode '''(4)''' and then selected '''OK (4)'''.


You can then create points from here by first clicking on the 'Add Point Feature' button
[[File:IDWSymbology.png]]


[[File:Add point feature.png]]
This process can be done for any of the output raster layers. The IDW output was done as an example. The output should look similar to the capture below, depending on the cell size used in the modeling process.


After clicking this button your cursor will become a cross-hair when mousing over your data frame. The center of this cross-hair is the location of the pixel that will be altered using this tool.
[[File:IWDOutput.png]]


Click on a location along the stream network, such as the location displayed below. When you click on it a small window like the one below will appear. Give your point an a unique ID so that it can be saved in the vector.
It is also possible to change the transparencies of the layers and overlay them on top of one another for more visually pleasing final maps. The following map was created by setting the transparency of the IDW layer to 10% and overlaying it onto of the Hillshade layer.


[[File:IWDAndHillShadeOutput.png]]
[[File:Place pour point.png|500px]]


Repeat this process until you are happy with the placement of your pour points, making sure that the value of each pour point is unique.
===Exporting your model===
For the example in this tutorial 10 pour points were spread evenly along the stream network and were given sequential values from 1 to 10.


It is important that the placement of these pour points is on the stream network, so the Jenson Snap Pour Points tool will now be used to make sure that this is true.
Once you finish your model it can be exported for further use.


The location of this tool is displayed below.
[[File:ModelOutput.png]]


[[File:Jenson snap pour points tool location.png]]
====As an Image====


The dialog box for this tool is displayed below. The input streams raster should be set to the output from the extract streams tool. After these inputs have been set, run the tool.
If you'd like to print out the finished model or include it in a report it is possible to save the model as an image for future reference a picture of the model can be saved using the indicated button '''(1)'''.


[[File:Jenson snapped pour points.png | 500px]]
====As a Python script====


After this you will get a new point layer that is perfectly snapped to the stream network. Use this point layer for future analysis instead of your manually created layer.
It is also possible to export the model as Python script using the second indicated button '''(2)'''.
This Python script can be edited in a program such as Notepad++.


====Watershed====
[[File:PythonModel.png]]


Now that the pour point raster has been created and snapped to the stream network the watershed analysis can be undergone. The location of this tool is displayed below.
==Raster Calculations==


[[File:Watersheds tool location.png]]
In addition to creating a model using the Processing toolbox, the '''QGIS raster calculator''' can be used to input certain expressions to preform multiple geoprocessing tasks. For the purposes of this tutorial I will be extracting all areas from the slope map that are not flat, (i.e. '''don't have a slope of 0 degrees''').
First navigate to the menu bar, under '''Raster''', select '''Raster Calculator...'''.


The dialog box for this tool is displayed below. The D8 flow pointer raster file should be set to the output from the D8 flow pointer tool. The pour point file should be set to the output from the Jenson snap pour points tool. After these inputs have been set, run the tool.
[[File:CalcSelection.png]]


[[File:Watersheds tool.png|600px]]
A '''Raster calculator''' window will open. Inside the expression field insert the following expression '''(1)''': '''( "Output Slope@1" > 0 ) OR ( "Output Slope@1" < 0 )'''. I would recommend manually clicking the operators to avoid typing error. When done entering the expression, at the bottom of the window it should say "expression valid".


The output of this tool is displayed below. This shows 10 watershed ares, corresponding to the locations that the pour points were located. Each of these watersheds also conserve the value that its pour point had, meaning that any hierarchy or numbering system will be kept.
Remember to save the output as something that is easily recognizable '''(2)''', example, SlopeCalc.tif. Select '''OK (3)'''.


The number and location of your watershed areas will differ as a result of the different pour points used.
[[File:RasterCalculator.png]]


[[File:WatershedOtp.PNG|600px]]
When finished you should have an output map like the one indicated below. All areas without a slope of 0 degrees are represented in black and all other areas are in white.

[[File:SlopeCalc.png|box]]

The following process can be done for any of the output terrain maps. Extracting areas without a slope of 0 degrees was done as an example.


==Conclusion==
==Conclusion==
In conclusion, this tutorial was aimed to give the user the skills to create workflows using the QGIS Processing Toolbox while also creating a workshop for slope and terrain analysis. This tutorial also gives the user the very basic introduction into the GIS world of Python scripting as well. The Python scripts that were exported can be slightly edited to preform the same geoprocessing tasks but with different parameters if necessary.

==Resource Links==
[http://docs.qgis.org/2.18/en/docs/index.html QGIS version 2.18 Documentation]

[http://www.gdal.org/ GDAL - Geospatial Data Abstraction Library]

[http://support.esri.com/en/knowledgebase/GISDictionary/term/aspect Aspect - GIS Dictionary]

[http://support.esri.com/en/knowledgebase/GISDictionary/term/hillshading Hillshade - GIS Dictionary]

[http://support.esri.com/en/knowledgebase/GISDictionary/term/interpolation Interpolation - GIS Dictionary]

[http://support.esri.com/en/knowledgebase/GISDictionary/term/slope Slope - GIS Dictionary]

[http://learnpythonthehardway.org/ Python - Learn Python the Hard Way]

[http://notepad-plus-plus.org/ Notepad++ Homepage]

==References==
Crosetto, M., Tarantola, S., & Saltelli, A. (2000). Sensitivity and uncertainty analysis in spatial modelling based on GIS. ''Agriculture, Ecosystems and Environment'', 81(1), 71-79. doi:10.1016/S0167-8809(00)00169-9


This tutorial aimed to give the user in introduction to hydrological analysis using Whitebox GAT 3.4.0. This was done by taking the user through an organized process that linked many of the hydrology tools together and explained why they were used and how the parameters were decided for each one.
Hutchinson, M.F., 1998. Interpolation of Rainfall Data with Thin Plate Smoothing Splines – Part II: Analysis of Topographic Dependence. ''Journal of Geographic Information and Decision Analysis'', vol.2, no. 2, pp. 152-167, 1998.


The user should now have a good basis of knowledge that will help them with future hydrological analysis in Whitebox Geospatial Analysis Tools.
R.E. Crochiere and L.R. Rabiner. (1983). Multirate Digital Signal Processing. Englewood Cliffs, NJ: Prentice–Hall.

Latest revision as of 14:58, 9 October 2026

Introduction

WhiteBox.png

This tutorial uses Whitebox tools, an open source GIS software that was developed within the Center for Hydrogeomatics in Guelph University. As a result this software package has a heavy focus on hydrological analysis. For this reason Whitebox was chosen for this tutorial on hydrological analysis. WhiteBox has recently been completely re-written from the ground up using a more advanced backend. This means that the toolset has migrated away from a stand-a-lone software. It is now accessible either through code (Python or R) or as a package using QGIS. This tutorial originally used the older version but has been updated to use the QGIS version in October 2026.

The area of focus in this tutorial is Calabogie Ontario. This location was chosen because the Calabogie peak adds some relief to the area, and the author knew it well enough to tell if there were any errors that occurred during the analysis process.

This tutorial uses a single input, a Digital Elevation model, and produces a multitude of outputs from it, adding information that could be used for future analysis. The process that will be undergone in this tutorial is displayed in the image below. To understand the context of each tool used in this tutorial please refer back to this image as needed.

Overview.PNG

Data Acquisition

In this tutorial the only necessary layer is a Digital Elevation Model (DEM) file of your area of interest. In this tutorial we are focusing on Calabogie, ON. It is recommended that you use tthis same dataset for following along.

It can be acquired and downloaded here.

A sample of this data is shown bellow.

DataExa.PNG

For the event that the dropbox link has become inactive the process of obtaining this data is described below to make this tutorial relevant for longer.

Access the Government of Canada Geospatial Data Extraction Application here.

In the “Select Clipping Area” bar enter change the selection to "Predefined Clipping Area" and then select "Drainage areas" from the drop down list that appears.

SelectClipArea.png

This produces a long list of sequential drainage area names. Search through the names until you find "02KE000" and select it. I found this on the 17th page of drainage area names.

The map extent on the right side of the web page should now match the image below.

MapExtent.PNG


Under “Select Data to be extracted” Select “Elevation – Digital elevation model”.

Under “Select options and submit job” fill all of the required boxes so that it matches the figure below. Make sure to enter the email address that you would like to have the file sent to in the “Email Address” field.

SelectOptions2.png

An email will be sent to the entered email address shortly which contains a URL for the direct download of the data.

If neither of these options are available, any DEM raster can be used.

Acquiring and Installing Whitebox Plugin (QGIS)

Please note the previous version of Whitebox used for this tutorial is now deprecated and has transitioned to be used via coding APIs or QGIS only. This tutorial will now use Whitebox Geospatial Analysis Tools in QGIS instead of the older version. This tutorial presumes the user has some QGIS knowledge and already has QGIS installed. For more details, please see the the QGIS download page for more instructions.

To setup your QIGS workspace for WhiteBox you will need to install the "WhiteBox Workflows for QGIS" plugin.

To start, find the plugin manager in QGIS by going to plugins > Manage and Install Plugins...

Plugin installer.png

Then search all plugins for "WhiteBox Workflows for QGIS"

Install Plugin Whitebox.png

Install the plugin, once that is finished please move on to the next section.

Getting Started

Accessing WhiteBox Tools

You're now all set to start using WhiteBox Tools. If you do not see them go to Processing > Toolbox to display the window.

Toolbox location.png

You will find the whitebox tools displayed at the bottom of the list. These tools will be used for the rest of the tutorial so please make sure you have access to them as shown here.

Whitebox in toolkit.png

Import DEM into QGIS

Import the DEM you downloaded into QGIS by adding it as a layer. You can do this by finding the layer in the QGIS browser or simply dragging it from the directory into QGIS. If it correctly imported, you should see the DEM displayed on the screen.

DataExa.PNG

Hydrological Analysis

DEM Pre-Processing

Pre-processing is an important first step in any hydrological analysis as this process identifies and corrects all features within the DEM that may disrupt the flow analysis. Since all products are derived from the DEM it is important to make these corrections at the begging of the process to prevent these errors from carrying through into all of the hydrological outputs.

In this tutorial the "Fill Depressions" tool is used to hydrologically correct the DEM. This was chosen because it is much more computationaly efficient than any of the breach tools, finishing much quicker.

This tool is found in the location below.

Fill depressions tool location.png

The dialog box that appears for this tool is shown below. The input file should be set to the original Calabogie DEM.

Fill depressions tool.png

The output of this tool is shown below. It does not appear very different to the original DEM, but will closer inspection differences within the areas identified in the Find No-Flow Cells output can be seen.

FillDepressionsOtp.PNG

Flow Pointer

A flow pointer tool in Whitebox is a tool that identifies which area surrounding a cell is the lowest. The value of this cell is then assigned corresponding to the relative direction of this area. This information is not too useful on its own, but it is used as an input to many other hydrology tools because it denotes the direction that water will flow from each cell.

Whitebox has many different flow pointer tools that each use a different method to produce their results. In this tutorial "D8 Flow Pointer" was used because many of the tools in the "Watershed Tools" toolset will only work with the output from the D8 Flow Pointer as an input. This tool is found in the location shown below.

D8 flow tool location.png

The dialog box for this too is shown below. The input DEM raster file should be set to the output from the Fill Depressions tool.

D8 flow tool.png

The output from this tool is displayed below. This image contained 8 colours corresponding to the 8 directions of flow. This image appears chaotic, but will be used in other tools to create more informative data products.

FlowPointerOtp.PNG

Flow Accumulation

Flow Accumulation tools analyze the magnitude of cells that pour into or through an area. This is useful on its own, allowing us to determine the relative flow through areas by comparing values of the output, and is also used as an input for many other analyses.

In this tutorial the "D8 Flow Accumulation" tool was used, as this was the one that corresponded to the D8 Flow Pointer output that was created with the previous tool. This tool is located in the location displayed below.

D8 accumulation tool location.png

The dialog box for this tool is displayed below. The input D8 flow pointer raster file should be set to the output from the D8 flow pointer tool. In the example the "Output Type" was set to "cells" so that a greater cell value in the output would correspond to a greater number of cells flowing through that cell. The "Log-transform output" box was left unchecked in this example, though checking this would help normalize the data for better display. After these inputs have been set click, run the tool.

D8 accumulation tool.png

The output of this tool is displayed below. The brighter areas correspond to areas of higher accumulated flow. These areas of high flow correspond to the areas where more water gathers and flows together. A beter picture of the data can be gathered by zooming into the output in Whitebox.

FlowAccumulationOtp.PNG

Isobasin

The isobasin tool divides a study area into equally sized drainage areas (iso-basins) of a specified size.

The location of this tool is displayed below.

Isobasins tool location.png

The dialog box for this tool is displayed below. The input is the original, hydrologically conditioned (depression fill) raster.

Isobasins tool.png

The output from this look is displayed below. It can be seen that the area has been broken down into 11 different basins of approximately equal size. It also appears that the basins do not fill the entire study area. This is likely because no more basins of a size of 500,000 cells could be fit into these areas. If the target basin size was set to a lower number these basins would conform to the study area more completely.

IsobasinOtp.PNG

Extract Streams

Stream networks can be useful as an input for other tools. Also, on their own they allow knowledge of areas of high water and nutrient flow, as well as connecting areas between water habitats.

The "Extract Streams" tool was used for this purpose. This tool extracts all values from a flow accumulation output that are greater than the specified value. This tool is part of the "Stream Network Analysis" toolset. The location of this tool is displayed below.

Extract streams tool location.png

The dialog box for this tool is displayed below. The input flow-accumulation raster file should be set to the output from the D8 Flow Accumulation (D8 Flow Accumulation). The "Channelization Threshold" is the cutoff value that will be used to determine which cells are a stream and which cells aren't. Trial and error was used to determine a value that produced an appropriate stream network. A value of 5,000 was settled on. Please make sure to check the "If true, non-stream background is 0 instead of NoData" box. This is because later tools in this analysis require rasters without NoData values.

Extract streams tool.png

The output of the tool is displayed below. This output looks patchy at the full extent, but by zooming into it within Whitebox you can confirm that a network of continuous lines has been produced.

ExtractStreamsOtp.PNG

Sub-basins

The sub-basin tool breaks the down the study area into a number of basins, with one basin for each segment of a stream network for the area. As a result each of these basins represent the catchment area for each segment of the river network.

The location of this tool is displayed below.

Subbasins tool location.png

The dialog box for this tool is displayed below. The input streams raster file should be set to the output from the extract streams tool, and the input D8 flow pointer raster should be set to the output from the D8 flow pointer tool . After these inputs have been set, run the tool.

Subbasins tool.png

The output from this tool is displayed below. This image shows a much greater number of basins than any of the outputs from other tools in this tutorial, likely due to the complexity of the stream network fed into the tool. It would be expected that if the channelization threshold used for the extract streams tool was higher, there would be less sub-basins, and if it was lower there would be more.

SubbasinsOtp.PNG

Watershed Analysis

In order to run the Watershed tool this first step will be to create pour points. Once this is done The watershed analysis can be done.

Pour Points

Pour points are used in watershed analysis to define each of the watersheds that will be output. Simply put, a watershed is the entire area that flows into a pour point. As a result the placement of these pour points greatly effects the output of the watershed analysis. Pour points are usually located in areas of high accumulated flow, so are usually located on points of a stream network.

There is no way to create a pour point file in Whitebox automaticaly, so this must be done manualy. You can do this by creating a new point layer in QGIS. Go to layer > Create layer

Create new layer location.png

You can create whichever data structure you prefer for vectors, for this tutorial we use a shapefile. Make sure to set your CRS to the same CRS as the hydrological products that have already been created. Then set the geometry type to Point. Your dialog box may look something like below.

Create points layer.png

Pour points must now be identified and added. Before this can be done, the layers in the data tab have to be set up. I made sure that only the extract streams output and the create blank outlet raster output were visible.

Next the vector layer must be set to editing mode, start by enabling editing like so.

Toggle editing.png

You can then create points from here by first clicking on the 'Add Point Feature' button

Add point feature.png

After clicking this button your cursor will become a cross-hair when mousing over your data frame. The center of this cross-hair is the location of the pixel that will be altered using this tool.

Click on a location along the stream network, such as the location displayed below. When you click on it a small window like the one below will appear. Give your point an a unique ID so that it can be saved in the vector.

Place pour point.png

Repeat this process until you are happy with the placement of your pour points, making sure that the value of each pour point is unique. For the example in this tutorial 10 pour points were spread evenly along the stream network and were given sequential values from 1 to 10.

It is important that the placement of these pour points is on the stream network, so the Jenson Snap Pour Points tool will now be used to make sure that this is true.

The location of this tool is displayed below.

Jenson snap pour points tool location.png

The dialog box for this tool is displayed below. The input streams raster should be set to the output from the extract streams tool. After these inputs have been set, run the tool.

Jenson snapped pour points.png

After this you will get a new point layer that is perfectly snapped to the stream network. Use this point layer for future analysis instead of your manually created layer.

Watershed

Now that the pour point raster has been created and snapped to the stream network the watershed analysis can be undergone. The location of this tool is displayed below.

Watersheds tool location.png

The dialog box for this tool is displayed below. The D8 flow pointer raster file should be set to the output from the D8 flow pointer tool. The pour point file should be set to the output from the Jenson snap pour points tool. After these inputs have been set, run the tool.

Watersheds tool.png

The output of this tool is displayed below. This shows 10 watershed ares, corresponding to the locations that the pour points were located. Each of these watersheds also conserve the value that its pour point had, meaning that any hierarchy or numbering system will be kept.

The number and location of your watershed areas will differ as a result of the different pour points used.

WatershedOtp.PNG

Conclusion

This tutorial aimed to give the user in introduction to hydrological analysis using Whitebox GAT 3.4.0. This was done by taking the user through an organized process that linked many of the hydrology tools together and explained why they were used and how the parameters were decided for each one.

The user should now have a good basis of knowledge that will help them with future hydrological analysis in Whitebox Geospatial Analysis Tools.

Retrieved from "https://dges.carleton.ca/CUOSGwiki/index.php?title=Hydrological_Analysis_Using_Whitebox_Geospatial_Analysis_Tools&oldid=24227"