User guide to channel extraction using LSDTopoTools

The parameter file has keywords followed by a value. The format of this file is similar to the files used in our LSDTT_BasicMetrics program, which you can read about in the our section introducing LSDTopoTools: Basic usage of LSDTopoTools.

The parameter file has keywords followed by the : character. After that there is a space and the value.

Below are options for the parameter files. Note that all DEMs must be in ENVI bil format (DO NOT use ArcMap’s bil format: these are two different things. See the documentation on data sources if you want more details). The reason we use bil format is because it retains georeferencing which is essential to our file output since many of the files output to csv format with latitude and longitude as coordinates.

Below is an example parameter file. This file is included in the repository along with the driver functions.

We can extract threshold area channel networks using the driver function called channel_extraction_area_threshold.cpp. To compile the code you first need to navigate to the driver functions folder in the repository.

When in this folder type the following to compile the driver:

This will create a program called channel_extraction_area_threshold.out

To run the analysis you first need to create a parameter file, with which we will set the key user-defined parameters. To create your parameter file, open any text editor and create a file with the following lines:

The threshold area must be given in m². You need to save this parameter file in the folder LSDTopoTools_ChannelExtraction (one folder above the driver functions folder). For the Indian Creek site we can create a parameter file called indian_creek_threshold.driver with the following lines:

After creating the parameter file we can then run the code using the following command:

For our Indian Creek example our command would be:

Once this program has run, it will create several files with the extracted channel network. These include:

The figure below shows the extracted channel network for the Indian Creek field site with a threshold of 1000 m².

The Geonet algorithm filters the DEM using a Perona-Malik filter, then uses a planform curvature threshold which is statistically derived from the landscape to detect channel heads. For full information on how Geonet works please see Passalcqua et al. (2010a, b, 2012). It then uses a contributing area threshold to thin the skeleton and create the final channel network. The Geonet algorithm is available free to download from the Geonet website. This site also contains the code documentation and user guides on how to get started with Geonet. It is a cross platform MATLAB package (you will need a MATLAB licence to run in its present form).

Pelletier (2013) developed an algorithm that is similar to Geonet in that it identifies channel heads based on a planform curvature threshold. The main differences between this algorithm and Geonet are:

The Pelletier algorithm has been implemented in LSDTopoTools. In order to run it you should follow the steps below.

Within LSDTopoTools we have also developed a method for extracting channel heads via planform curvature. We first of all filter the DEM using an Optimal Wiener filter, then use a quantile-quantile threshold to statistically determine the planform curvature threshold from the landscape. It then uses a connected components threshold to extract the channel network.

We first need to create a parameter file. To create your parameter file, open any text editor and create a file with the following lines:

The threshold area is given in m². You need to save this parameter file in the folder LSDTopoTools_ChannelExtraction (one folder above the driver functions folder). For the Indian Creek site we can create a parameter file called indian_creek_wiener.driver with the following lines:

After creating the parameter file we can then run the code using the following command:

For our Indian Creek example our command would be:

Once this program has run, it will create several files with the extracted channel network. These include:

The figure below shows the extracted channel network using the LSDTopoTools geometric algorithm with an Optimal Wiener filter for the Indian Creek field site.

Before the Dreich algorithm can be run the m/n value for the landscape must be determined. This can be done using the chi analysis tools in LSDTopoTools.

We can extract threshold area channel networks using the driver function called channel_extraction_dreich.cpp. To compile the code you first need to navigate to the driver functions folder in the repository. When in this folder type the following to compile the driver:

This will create a program called channel_extraction_dreich.out

We first need to create a parameter file. To create your parameter file, open any text editor and create a file with the following lines:

You need to save this parameter file in the folder LSDTopoTools_ChannelExtraction (one folder above the driver functions folder). For the Indian Creek site we can create a parameter file called indian_creek_dreich.driver with the following lines:

After creating the parameter file we can then run the code using the following command:

For our Indian Creek example our command would be:

Once this program has run, it will create several files with the extracted channel network. These include:

The figure below shows the extracted channel network using the DrEICH algorithm for the Indian Creek field site.

First navigate to the folder where you will keep the GitHub repository. If you have downloaded LSDTopoTools using vagrant, then this should be in the folder Git_projects. Please refer to the documentation on installing LSDTopoTools. To navigate to this folder in a UNIX terminal use the cd command:

You can use the command pwd to check you are in the right folder. Once you are in this folder, you can clone the repository from the GitHub website:

Navigate to this folder again using the cd command:

If you don’t want to use git, you can download a zipped version of the code:

We have provided some example datasets which you can use in order to test the drainage density analysis. In this tutorial we will work using a LiDAR dataset from the Guadalupe Mountains, New Mexico. This is a clip of the original dataset, which we have resampled to 2 m resolution. The full dataset is available from OpenTopography.. If you are using the vagrant distribution, create a new folder within the Topographic_projects folder, and then navigate to this folder:

You can get the clip from our ExampleTopoDatasets repository using wget:

This dataset is already in the preferred format for use with LSDTopoTools (the ENVI bil format). The figure below shows a shaded relief map of part of the Guadalupe Mountains DEM which will be used in these examples.

We have also provided some examples parameter files that are used to run the drainage density analysis. These should be placed in the same folder as your DEM (e.g. in the folder /LSDTopoTools/Topographic_projects/Guadalupe_NM/. You can get the example parameter file using wget:

We have also provided some Python scripts for creating figures from the draiange density analysis. These should produce similar figures to those in Clubb et al. (2016), JGR-ES. These scripts are in the directory Python_scripts within LSDTopoTools_DrainageDensity:

Before the drainage density analysis can be run, you must create a channel network for your DEM. This can be done using any of the channel extraction algorithms within LSDTopoTools. Once you have run the channel extraction algorithm, you must make sure that the bil and hdr files with the channel head locations are placed in the same folder as the DEM you intend to use for the drainage density analysis.

Before we can run the drainage density algorithm, we need to calculate the correct window size for calculating mean hilltop curvature across the DEM. Please refer to the selecting a window size section for information on how to calculate a window size for your DEM.

In order to run the drainage density analysis code you must first create a parameter file for your DEM. This should be placed in the same folder as your DEM and the channel heads bil file. If you followed the instructions in the Get the code for drainage density analysis section then you will already have an example parameter file for the Guadalupe Mountains DEM called drainage_density_guadalupe.driver. Parameter files should have the following structure:

An example parameter file for the Guadalupe Mountains DEM is set out below:

The first step of the analysis creates a text file with all the junction numbers of the basins of the specified stream order. Before the code can be run, you must compile it using the makefile in the folder LSDTopoTools_DrainageDensity/driver_functions_DrainageDensity. Navigate to the folder using the command:

and compile the code with:

This may come up with some warnings, but should create the file drainage_density_step1_junctions.out. You can then run the program with:

For our example, the command would be:

The program will create a text file called DEM_name_DD_junctions.txt which will be ingested by step 2 of the analysis. It will also create some new rasters:

The second step of the analysis ingests the junctions text file created in step 1. For each junction it will extract the upstream drainage basin, and calculate the drainage density and mean hilltop curvature for the basin. This will be written to a text file which can be plotted up using our Python script.

First, compile the code with the makefile:

This may come up with some warnings, but should create the file drainage_density_step2_basins.out. You can then run the program with:

For our example, the command would be:

This program will create 2 text files. The first one will be called DEM_name_drainage_density_cloud.txt and will have 3 rows:

This text file represents the data for every basin in the DEM. The second text file will be called DEM_name_drainage_density_binned.txt, where the drainage density and hilltop curvature data has been binned with a bin width of 0.005 m^-1. It has 6 rows:

These text files are read by drainage_density_plot.py to create plots of the drainage density and mean hilltop curvature. The code also produces DEM_name_basins.bil, which is a raster with all the basins analysed.

Navigate to the folder Python_scripts within the LSDTopoTools_DrainageDensity repository. You should find the following files:

Open the file called drainage_density_plot_cosmo.py. We suggest doing this on your host machine rather than the virtual machine: for instructions about how to install Python on your host machine please see the section on the LSDTopoTools python toolchain.

Open the file called drainage_density_plot.py. We suggest doing this on your host machine rather than the virtual machine: for instructions about how to install Python on your host machine please see the section on the LSDTopoTools python toolchain.

If you want to run the script on the example dataset you can just run it without changing anything. The script will create the file Guadalupe_DEM_drainage_density_all_basins.png in the same folder as your DEM is stored in. If you want to run it on your own data, simply open the Python script in your favourite text editor. At the bottom of the file you need to change the DataDirectory (Line 165) and the DEM identifier (Line 167) to reflect your data:

You should end up with a plot like the one below:

You should now be able to extract the drainage density and mean hilltop curvature for all basins of a given order for your DEM, and use Python to plot the results.

The program needs to read in a text file with the erosion rate data. This file needs to be called DEM_name_cosmo.txt where DEM_name is the name of the DEM without extension. The file should have a row for each sample, with 4 columns, each separated by a space:

An example of the file for the Feather River is shown below (UTM Zone 10N):

This file has to be stored in the same folder as your DEM.

Along with the text file with the erosion rate data, you must also create a parameter file to run the code with. This should have the same format as the parameter file for running the analysis on all the basins, minus the last two lines. The format is shown below:

This should also be stored in the same folder as your DEM.

Before the code can be run, you must compile it using the makefile in the folder LSDTopoTools_DrainageDensity/driver_functions_DrainageDensity. Navigate to the folder using the command:

and compile the code with:

This may come up with some warnings, but should create the file get_drainage_density_cosmo.out. You can then run the program with:

where /path/to/DEM/location is the path to your DEM, and name_of_parameter_file.driver is the name of the parameter file you created.

The program will create a text file called DEM_name_drainage_density_cosmo.txt which can be ingested by our Python script to plot up the data. This file has 9 rows with the following data:

It will also create some new rasters:

Navigate to the folder Python_scripts within the LSDTopoTools_DrainageDensity repository. You should find the following files:

Open the file called drainage_density_plot_cosmo.py. We suggest doing this on your host machine rather than the virtual machine: for instructions about how to install Python on your host machine please see the section on [Getting python running].

Open the Python script in your favourite text editor. At the bottom of the file you need to change the DataDirectory (Line 131) and the DEM identifier (Line 133) to reflect your data:

You should end up with a plot like the one below:

You should now be able to extract the drainage density for a series of different basins across the landscape. These can either be all basins of a specific order (Step 1), or basins defined by point coordinates (e.g. for catchment-averaged erosion rates from CRN samples in Step 2).