12. Extracting Hillslope Lengths

This page gives an overview of how to use the hillslope length driver (LH_Driver.cpp) and it’s companion (LH_Driver_RAW.cpp) to quickly generate hillslope length data for a series of basins, along with other basin average metrics within a larger DEM file.

For appliactions considering landscapes at geomorphic (millenial) timescales use the main driver, for event scale measurements use the RAW driver. All instructions on this page will work for either driver. For convenicence it will refer only to LH_Driver.cpp but either driver can be used.

This code is used to to produce the data for Grieve et al. (in prep.)

12.1. Quick guide

Here is a quick overview of how to set up and run the code, if you have done it before:

1. Generate a channel head file for the landscape.
2. Get the window size for the surface fitting routines.
3. Compile the code with: make -f LH_Driver.make
4. Run the program LH_Driver.out using the path (with trailing slash), the filename prefix, window radius, basin order, critical slope and a switch to write rasters if desired as arguments.
5. Analyse the resulting data files using python.

12.2. Overview

This driver file will combine several LSDRaster Functions in order to generate as complete a range of basin average and hillslope length metrics as possible. The tool will generate:

1. A HilltopData file with metrics calculated for each hilltop pixel which can be routed to a stream pixel.
2. A file containing basin averaged values of hillslope lengths and other standard metrics.
3. An optional collection of trace files, which can be processed to create a shapefile of the trace paths across the landscape. These can be enabled by setting a flag inside the driver on line 141.

12.3. Warning

This code is for research purposes and is under continuous development, so we cannot guarantee a bug-free experience!

12.4. Before You Start

See the other docs on this site for help with loading data into the correct format and general help with using this suite of software: Getting data into LSDTopoToolbox

12.5. Input Data

12.5.1. Raw DEM

The raw DEM to be analysed should be named <prefix>_DEM.flt

12.5.2. Floodplain Mask (Optional)

A binary mask of floodplains which can be used to ensure that analysis only occurs on the hillslopes. Should be named <prefix>_FloodPlain.flt

12.5.3. Generating Channel Heads

Channel heads can be extracted using the steps outlined in Calculating channel heads using the DrEICH algorithm and the resulting channel head file should be named <prefix>_CH.flt and be placed in the same directory as the DEM.

12.5.4. Getting The Window Size

The surface fitting window size can be constrained using the steps outlined in Selecting A Window Size for Surface Fitting. This should be performed to ensure the correct parameter values are selected.

12.6. Compile The Driver

The code is compiled using the provided makefile, LH_Driver.make and the command:

make -f LH_Driver.make

Which will create the binary file, LH_Driver.out to be executed.

12.7. Run The Code

The driver is run with six arguments:

1. The data path where the Channel head file and DEM is stored, and the output data will be written.
2. The filename prefix, without an underscore.
3. Radius in spatial units of kernel used in surface fitting. Selected using Selecting A Window Size for Surface Fitting.
4. The Strahler order of basins to be extracted.
5. Critical Slope, Used to filter out hilltops with too steep a slope and is used in the E* R* calculations.
6. Switch to exclude floodplains from analysis [Requires a floodplain mask] 0 == do not exclude floodplains and 1 == exclude floodplains
7. Switch to write rasters. 0 == do not write rasters and 1 == write rasters

The syntax on a unix machine is as follows:

./LH_Driver.out <path to data files> <Prefix> <Window Radius> <Stream order> <Floodplain Switch> <Switch to write rasters>

And a complete example (your path and filenames may vary):

./LH_Driver.out /home/s0675405/DataStore/LH_tests/ Oregon 6 2 1 0

12.8. Analysing The Results

The final outputs are stored in a series of files, which are written to the data folder supplied as an argument.

<Prefix>_Paper_Data.txt

This file contains all of the basin average values for each basin in the following format:

BasinID HFR_mean HFR_median HFR_stddev HFR_stderr HFR_Nvalues HFR_range HFR_min HFR_max SA_binned_LH SA_Spline_LH LH_Density Area Basin_Slope_mean Basin_Slope_median Basin_Slope_stddev Basin_Slope_stderr Basin_Slope_Nvalues Basin_Slope_range Basin_Slope_min Basin_Slope_max Basin_elev_mean Basin_elev_median Basin_elev_stddev Basin_elev_stderr Basin_elev_Nvalues Basin_elev_Range Basin_elev_min Basin_elev_max Aspect_mean CHT_mean CHT_median CHT_stddev CHT_stderr CHT_Nvalues CHT_range CHT_min CHT_max EStar RStar HT_Slope_mean HT_Slope_median HT_Slope_stddev HT_Slope_stderr HT_Slope_Nvalues HT_Slope_range HT_Slope_min HT_Slope_max HT_relief_mean HT_relief_median HT_relief_stddev HT_relief_stderr HT_relief_Nvalues HT_relief_range HT_relief_min HT_relief_max

1. BasinID = Unique ID for the basin.
2. HFR_mean = Mean hilltop flow routing derived hillslope length.
3. HFR_median = Median hilltop flow routing derived hillslope length.
4. HFR_stddev = Standard deviation of hilltop flow routing derived hillslope length.
5. HFR_stderr = Standard error of hilltop flow routing derived hillslope length.
6. HFR_Nvalues = Number of values used in hilltop flow routing derived hillslope length.
7. HFR_range = Range of hilltop flow routing derived hillslope length.
8. HFR_min = Minimum hilltop flow routing derived hillslope length.
9. HFR_max = Maximum hilltop flow routing derived hillslope length.
10. SA_binned_LH = Hillslope length from binned slope area plot.
11. SA_Spline_LH = Hillslope length from spline curve in slope area plot.
12. LH_Density = Hillslope length from drainage density.
13. Area = Basin area.
14. Basin_Slope_mean = Mean basin slope.
15. Basin_Slope_median = Median basin slope.
16. Basin_Slope_stddev = Standard deviation of basin slope.
17. Basin_Slope_stderr = Standard error of basin slope.
18. Basin_Slope_Nvalues = Number of basin slope values.
19. Basin_Slope_range = Range of basin slopes.
20. Basin_Slope_min = Minimum basin slope.
21. Basin_Slope_max = Maximum basin slope.
22. Basin_elev_mean = Mean basin elevation.
23. Basin_elev_median = Median basin elevation.
24. Basin_elev_stddev = Standard deviation of basin elevation.
25. Basin_elev_stderr = Standard error of basin elevation.
26. Basin_elev_Nvalues = Number of basin elevation values.
27. Basin_elev_Range = Range of basin elevations.
28. Basin_elev_min = Minimum basin elevation.
29. Basin_elev_max = Maximum basin elevation.
30. Aspect_mean = Mean aspect of the basin.
31. CHT_mean = Mean hilltop curvature of the basin.
32. CHT_median = Median hilltop curvature of the basin.
33. CHT_stddev = Standard deviation of hilltop curvature of the basin.
34. CHT_stderr = Standard error of hilltop curvature of the basin.
35. CHT_Nvalues = Number of hilltop curvature values used.
36. CHT_range = Range of hilltop curvatures.
37. CHT_min = Minimum hilltop curvature in the basin.
38. CHT_max = Maximum hilltop curvature in the basin.
39. EStar = E* value from Roering (2007).
40. RStar = R* value from Roering (2007).
41. HT_Slope_mean = Mean slope calculated using (relief/hillslope length).
42. HT_Slope_median = Median slope calculated using (relief/hillslope length).
43. HT_Slope_stddev = Standard deviation of slope calculated using (relief/hillslope length).
44. HT_Slope_stderr = Standard error of slope calculated using (relief/hillslope length).
45. HT_Slope_Nvalues = Number of slope values calculated using (relief/hillslope length).
46. HT_Slope_range = Range of slopes calculated using (relief/hillslope length).
47. HT_Slope_min = Minimum slope calculated using (relief/hillslope length).
48. HT_Slope_max = Maximum slope calculated using (relief/hillslope length).
49. HT_relief_mean = Mean relief.
50. HT_relief_median = Median relief.
51. HT_relief_stddev = Standard deviation of relief.
52. HT_relief_stderr = Standard error of relief.
53. HT_relief_Nvalues = Number of relief values used.
54. HT_relief_range = Range of reliefs.
55. HT_relief_min = Minimum relief.
56. HT_relief_max = Maximum relief.

These files can be analysied using a series of python routines located here and the original figures for Grieve et al. (in prep) can be reproduced using code stored here.

<Prefix>_HilltopData.csv

This file contains hillslope metrics calculated for every hilltop pixel in the dataset which was routed successfully to a stream pixel. The file format is as follows:

X,Y,hilltop_id,S,R,Lh,BasinID,StreamID,HilltopSlope,DivergentCountFlag,PlanarCountFlag,E_Star,R_Star,EucDist

1. The first 2 columns are the map coordinates of the hilltop pixel
2. hilltop_id is the value of the hilltop pixel.
3. S is the slope calculated as relief/hillslope length.
4. R is the relief, the change in elevation between the hilltop and the channel
5. Lh is the hillslope flow length.
6. BasinID is the junction outlet number of the basin the hilltop is within.
7. StreamID is the value of the stream pixel reached by the trace.
8. HilltopSlope is the gradient of the pixel hwere the trace started.
9. DivergentCountFlag is the count of divergent pixels crossed. Depreciated
10. PlanarCountFlag - Count of planar cells crossed Depreciated
11. E_Star - E* value from Roering (2007).
12. R_Star - R* value from Roering (2007).
13. EucDist - Eculidean length of the trace from hilltop to channel

These files can be analysied using a series of python routines located here and the original figures for Grieve et al. (in prep) can be reproduced using code stored here.

<easting>_<northing>_trace.txt

If the trace creation switch is set to true a large number of files fill be created with this filename in a given directory. These files follow the format:

easting northing DivergentCountFlag length PlanarCountFlag E_Star R_Star EucDist

1. easting - The easting of the trace
2. northing - The northing of the trace
3. DivergentCountFlag - Count of non-planar cells crossed Depreciated
4. length - Cumulative length of the trace
5. PlanarCountFlag - Count of planar cells crossed Depreciated
6. E_Star - E* value from Roering (2007).
7. R_Star - R* value from Roering (2007).
8. EucDist - Eculidean length of the trace from hilltop to channel

These files can be processed using the accompanying python script, trace_process_1_1.py, to produce a shapefile of the traces, this file can be found here.

Output Raster Data

If the output switch is set to 1 a series of rasters representing intermediate processing steps will be written to the supplied path. These files are as follows:

1. Filled DEM
2. Slope
3. Aspect
4. Curvature
5. Stream Network
6. Basins
7. Hilltop Curvature
8. Hillslope Length
9. Hillslope Gradient
10. Relief
11. Hillshade