LSD logo

1. Overview

Welcome to the main documentation page for LSDTopoTools!

LSDTopoTools is a software package for analysing topography. Applications of these analyses span hydrology, geomorphology, soil science, ecology, and cognate fields. The software began within the Land Surface Dynamics group at the University of Edinburgh, and now has developers and users around the world.

The documentation is organised into a series of websites, listed below in the LSDTopoTools documentation topics section.

We are in the process of updating all the documentation to work with LSDTopoTools version 2. If you want the old version of the documentation, download the documentation v1.01, unzip, and go into the html_build directory. Click on index.html to navigate the old version of the documentation.

Extreme quickstart

If you are familiar with Docker, here is an extreme quickstart guide. For other installation options, read the installation section.

  1. Make a directory for LSDTopoTools

  2. Open a terminal and start our docker container:

    $ docker run --rm -it -v C:/LSDTopoTools:/LSDTopoTools lsdtopotools/lsdtt_pcl_docker
    In the above example the LSDTopoTools directory is in the C:\ drive. You will need to update this to reflect your directory structure.

  3. In the Docker container run the startup script

    # Start_LSDTT.sh

  4. If you want the example data run the following script (this only needs to be done once):

    # Get_LSDTT_example_data.sh

  5. You should be ready to run some analyses!

2. Where is all the code?

The code lives as a series of repositories on Github: https://github.com/LSDtopotools We have packaged these up for you if you use a Docker container, so all you need to do to get started is grab our container from Docker hub and run a startup script.

Currently, in LSDTopoTools version 2 all drivers will be housed within a single LSDTopoTools v2 repository, but some functionality is still within older application specific repositories. Please check back for updates.

3. LSDTopoTools documentation topics

Please follow the links below to find the relevant documentation.

3.1. Introduction, installation, and first tutorial of LSDTopoTools

Table 1. Introduction, installation, and first tutorial of LSDTopoTools
link Description

Background and philosophy of LSDTopoTools

This brief document describes some of the background to LSDTopoTools and the philosophy behind having open, reproducible topographic analysis software.

Instructions on how to install LSDTopoTools

A guide to installation of LSDTopoTools. Includes instructions for all operating systems, using either Vagrant or Docker, or native Linux installation at the University of Edinburgh or elsewhere.

Basic topographic analyses in LSDTopoTools

This is the launch point for your first analyses in LSDTopoTools. The documents take you through some basic steps and show how to do simple, everyday analyses like get gradient and curvature, calculate drainage areas, and extract channel networks.

3.2. Background reading and associated software

If you are doing topographic analysis, you will need more than just the core LSDTopoTools packages. These documents contain instructions on how to get raster data (primarily topographic data) and manipulate it with GDAL, how to look at data in QGIS, how to use a Linux shell, and how to build our documentation on your own computer. This last section will likely only appeal to LSDTopoTools developers. The rest of you can just view the documents on the web.

Table 2. Background reading and associated software
link Description

Introduction to geospatial data

A brief introduction to geospatial data. Where to get it, how to manipulate it, and information about the different forms of this data.

A very brief introduction to using a Linux shell

To use LSDTopoTools you need to issue commands in a Linux shell. This contains minimal instructions on how to navigate in this environment.

Some tips and tricks for using QGIS

The contains some brief notes about using QGIS. Not LSDTopoTools specific, but should be useful if you want to look at output using a GIS.

Building the LSDTopoTools documentation

An overview of how to build the LSDTopoTools documentation. Most users will not need this: they can just look at the documents online!

3.3. LSDTopoTools visualisation and python

The serious number crunching in LSDTopoTools is done in C++ code, but the output needs to be visulaised with either a GIS or python. Below are documents associated with GIS and python scripts.

Table 3. LSDTopoTools python scripts
link Description

Visualisation with LSDMappingTools

Explanation of how LSDMappingTools, our python visualisation toolkit to get our python tools working. Includes some basic python notes. Also some pointers to our GIS sections.

3.4. LSDTopoTools analysis packages

These documents describe our individual analysis packages. They are more specialised than the basic metrics program. We use these packages for research: most of them are associated with one or more scientific publications, or our collaborations with government, humanitarian organisations and private businesses.

Table 4. LSDTopoTools analysis packages.
link Description

Extracting channels using LSDTopoTools

Documentation for our channel extraction algorithms.

Channel steepness analysis with LSDTopoTools

Documentation for our tools for analysing channel profiles and extracting the chi coordinate. These tools are used to make inferences about erosion and/or uplift rates, as well as detecting signals of divide migration.

Knickpoint analysis with LSDTopoTools

Documentation for our tools for extracting knickpoints and knickzones from river profiles. Uses the same program as that used for general chi analysis.

Computing erosion rates based on 10Be and 26Al concentrations with LSDTopoTools

Documentation for our tools for calculating erosion rates using in-situ cosmogenic nuclides.

Floodplain and terrace analysis using LSDTopoTools

Documentation for our tools for extracting floodplains and terraces. Note that this requires the extra dependencies that you can read about in the last section of the installation instructions.

Hillslope metrics using LSDTopoTools

Documentation on how to get hillslope lengths, ridgetop curvature, hillslope relief and similar operations that can aid in determining sediment flux laws and landscape transience.

Landscape evolution using LSDTopoTools

Documentation for our simple landscape evolution model, MuddPILE.

3.5. LSDTopoTools technical details

Table 5. LSDTopoTools technical details
link Description

Troubleshooting LSDTopoTools

Common problems and their solutions.

4. Versions of the LSDTopoTools documentation

We will archive all versions of the documentation. Links to these versions will reside here.

Table 6. LSDTopoTools documentation topics
link description

Development version

This is the in-progress documentation.

Version 1.01

This is the last version of the documentation before the migration to LSDTopoTools v2. Download, unzip, and go into the html_build directory to get the old documentation.

5. LSDTopoTools authors

LSDTopoTools has had many developers over the years.

Table 7. LSDTopoTools developers
Person Notes links

Simon M. Mudd

Started the LSDRaster and LSDFlowInfo objects as a 3 month side project. "Lead developer" by virtue of being dumb enough to start the project. 95% of errors and examples of poor design are his fault. But being lead developer means he has many opportunities to leave little secrets in the code.

Web Scholar Github Twitter

Martin D. Hurst

Martin’s original code, linking python to ArcMap, was one of the inspirations for the initial version of the software. He has written a number of the routines associated with extracting tectonic information from lidar data.

Web Scholar Github Twitter

David T. Milodowski

Wrote many of the filtering and surface metric algorithms. Also wrote algorithms related to ecology, and has contributed throughout the code.

Scholar Github Twitter

Stuart W.D. Grieve

Wrote many of the hillslope length algorithms (along with Martin) as well as many of the algorithms and objects related to basin selection and processing.

Web Scholar Github Twitter

Fiona J. Clubb

Wrote many of the channel extraction algorithms as well as the floodplain and terrace algorithms. Has contributed throughout the software.

Web Scholar Github Twitter

Marie-Alice Harel

Wrote a number of automation algorithms for cosmogenic processing and linking basin erosion statistics to channel properties. Now working full time as an illustrator.

Instagram Twitter

Declan A. Valters

The lead developer of HAIL-CAESER, an LSDTopoTools port of CAESAR-LISFLOOD. Also helped write channel steepness analysis algorithms and a number of visualisation tools.

Web Scholar Github Twitter

Boris Gailleton

Has developed, along with Fiona Clubb, the knickpoint extraction algorithms. Also has developed routines for linking lithology to topography.

Web Github Twitter

Your name here

If you want to develop LSDTopoTools and add routines, contact Simon and your name could appear on this list.

Web Scholar Github Twitter

6. LSDTopoTools publications and software releases

We have published papers that descrbe the algorithms, papers that use the software, and other groups have also used the software for their work. We also publish releases of the software that are fully citable.

6.1. Citable versions of our software

For a complete, up to date list please see our Zenodo page

  1. Clubb, F. J., Mudd, S. M., Milodowski, D. T., & Grieve, S. W. D. (2017). LSDDrainageDensity v1.0. Zenodo. https://doi.org/10.5281/zenodo.824423

  2. Clubb, F. J., Mudd, S. M., Milodowski, D. T., Grieve, S. W. D., & Hurst, M. D. (2017). LSDChannelExtraction v 1.0. Zenodo. https://doi.org/10.5281/zenodo.824198

  3. Clubb, F. J., Mudd, S. M., Grieve, S. W. D., Milodowski, D. T., Valters, D. A., & Hurst, M. D. (2017). LSDTerraceModel v1.0. Zenodo. https://doi.org/10.5281/zenodo.824205

  4. Goodwin, G. C. H., Mudd, S. M., & Clubb, F. J. (2017). LSDtopotools Marsh Platform Identification Tool. Zenodo. https://doi.org/10.5281/zenodo.1007788

  5. Mudd, S. M., Jenkinson, J., Valters, D. A., & Clubb, F. J. (2017). MuddPILE the Parsimonious Integrated Landscape Evolution Model. Zenodo. https://doi.org/10.5281/zenodo.997407

6.2. Publications describing LSDTopoTools algorithms

  1. Clubb, F. J., Mudd, S. M., Milodowski, D. T., Valters, D. A., Slater, L. J., Hurst, M. D., & Limaye, A. B. (2017). Geomorphometric delineation of floodplains and terraces from objectively defined topographic thresholds. Earth Surface Dynamics, 5(3), 369–385. https://doi.org/https://doi.org/10.5194/esurf-5-369-2017

  2. Clubb, F. J., Mudd, S. M., Milodowski, D. T., Hurst, M. D., & Slater, L. J. (2014). Objective extraction of channel heads from high-resolution topographic data. Water Resources Research, 50(5), 4283–4304. https://doi.org/10.1002/2013WR015167

  3. Grieve, S. W. D., Mudd, S. M., & Hurst, M. D. (2016). How long is a hillslope? Earth Surface Processes and Landforms, 41(8), 1039–1054. https://doi.org/10.1002/esp.3884

  4. Grieve, S. W. D., Mudd, S. M., Hurst, M. D., & Milodowski, D. T. (2016). A nondimensional framework for exploring the relief structure of landscapes. Earth Surface Dynamics, 4(2), 309–325. https://doi.org/10.5194/esurf-4-309-2016

  5. Milodowski, D. T., Mudd, S. M., & Mitchard, E. T. A. (2015). Topographic roughness as a signature of the emergence of bedrock in eroding landscapes. Earth Surface Dynamics, 3(4), 483–499.

  6. Mudd, S. M., Attal, M., Milodowski, D. T., Grieve, S. W. D., & Valters, D. A. (2014). A statistical framework to quantify spatial variation in channel gradients using the integral method of channel profile analysis. Journal of Geophysical Research: Earth Surface, 119(2), 2013JF002981. https://doi.org/10.1002/2013JF002981

  7. Mudd, S. M., Harel, M.-A., Hurst, M. D., Grieve, S. W. D., & Marrero, S. M. (2016). The CAIRN method: automated, reproducible calculation of catchment-averaged denudation rates from cosmogenic nuclide concentrations. Earth Surface Dynamics, 4(3), 655–674. https://doi.org/10.5194/esurf-4-655-2016

6.3. Publications from our group that use LSDTopoTools

  1. Clubb, F. J., Mudd, S. M., Attal, M., Milodowski, D. T., and Grieve, S. W. D. (2016) The relationship between drainage density, erosion rate, and hilltop curvature: implications for sediment transport processes. Journal of Geophysical Research: Earth Surface, 121(10), 1724-1745. https://doi.org/10.1002/2015JF003747

  2. Devrani, R., Singh, V., Mudd, S. M., & Sinclair, H. D. (2015). Prediction of flash flood hazard impact from Himalayan river profiles. Geophysical Research Letters, 42(14), 2015GL063784. https://doi.org/10.1002/2015GL063784

  3. Grieve, S. D., Mudd, S. M., Milodowski, D. T., Clubb, F. J., & Furbish, D. J. (2016). How does grid-resolution modulate the topographic expression of geomorphic processes? Earth Surface Dynamics, 4(3), 627–653. https://doi.org/10.5194/esurf-4-627-2016

  4. Harel, M.-A., Mudd, S. M., & Attal, M. (2016). Global analysis of the stream power law parameters based on worldwide Be-10 denudation rates. Geomorphology, 268, 184–196. https://doi.org/10.1016/j.geomorph.2016.05.035

  5. Mudd, S. M. (2017). Detection of transience in eroding landscapes. Earth Surface Processes and Landforms, 42(1), 24–41. https://doi.org/10.1002/esp.3923

  6. Parker, R. N., Hales, T. C., Mudd, S. M., Grieve, S. W. D., & Constantine, J. A. (2016). Colluvium supply in humid regions limits the frequency of storm-triggered landslides. Scientific Reports, 6, srep34438. https://doi.org/10.1038/srep34438

6.4. Publications from other groups that have used LSDTopoTools

This is an incomplete list! If you use the code and write a paper or have a conference abstract please let us know by contacting Simon.