1. Introduction to LSDTopoTools visualisation

LSDTopoTools ingests data, digests it, and then produces gleaming, steaming new datasets. The number crunching that goes on inside of LSDTopoTools programs is there to help you understand your study area. But LSDTopoTools does not provide a graphical user interface: it just spits out numbers. Frequently these numbers are in binary format. To look at the data you need to visualise it.

There are two common ways to visualise data produced by LSDTopoTools.

  • Use a Geographic Information System (GIS). QGIS or ArcMap will do. The main difference betwen these packages is that one is free and open source (QGIS) and one is very very very expensive. LSDTopoTools output is designed to be compatible with both of these GIS packages.

  • Use our python plotting packages, including LSDMappingTools. These live in their own github repository.

1.1. Should I use a GIS or python?

If you are just starting out with LSDTopoTools, you probably want to use a nice, friendly GIS that has shiny buttons and icons and lets you pan and zoom and do all those nice things.

If you want to inspect individal data points you really need to use a GIS.

However, there are some disadvantages to using a GIS, which is why we wrote LSDMappingTools.

  • You have to click a bunch of buttons to get a certain formatting, and if you are loading diffent datasets there are more buttons to click. After you have done thousands of analyses requiring clicking each time, having to click these buttons begins to get very, very tedious. In fact it can get close to driving you mad and you might start muttering to strangers on the street or plants. Eventually you realise that you are clicking buttons so much that it would actually be more time efficient to learn the nuances of geospatial data visualisation using python than to keep clicking buttons. This leads you to write scripts to automate the visualisation process. This is not a hypothetical story, it acutally happened. LSDMappingTools automates plotting of LSDTopoTools output so you don’t have to click so many buttons.

  • You want to reproduce a plot. Because a GIS involves lots of presing of buttons and clicking of mice, it is difficult to reproduce the exact same figure twice. Have we mentioned how much we hate clicking buttons? Our philosophy is that science should be reproducible. So we have written scripts to guarantee that two users with the same data can produce exactly the same plot.

  • You want a plot that is formatted for a publication. Have you ever submitted a manuscript with figures that you have spent hours perfecting in Inkscape or Illustrator or iPaidAShittonToAppleGraphix and then reviewers ask you to change the figure or add some data? Isn’t that annoying? What if you wrote scripts where all the sizing, fonts, colouring, etc was exactly the way you want it so if the data changes you can just run a script again and you get a perfect figure without having to click buttons in Inkscape? We thought that would be great so we did it ourselves.

We now use LSDMappingTools regularly to make our figures. For some analyses, our plotting routines have been streamlined to the extent that you can get publication-ready figures in one python call. Sounds great, doesn’t it?

Well, there are some serious drawbacks to using python and LSDMappingTools:

  • The scripts require loads of interdependant python packages. It means that not only is installation a pain but it also takes up a lot of space (you need to download about a GB of python packages to get everything working). We have, however, spent a lot of time experimenting with different installation techniques so we are optimistic we can get python working on your system. Loads of people are switching from languages like c++ to python since python is soooo easy to use and portable. We love python. It is easy to use. But I will throw my book "The c++ programming language" by Bjarne Stroustrup at anyone who claims that python is more portable than c++.

  • If things go wrong it helps a lot to be good at Matplotlib. This has a steep learning curve.

  • I am afraid our python repositories are a mess. Every now and then we try to clean these up but the documentation and organisation leave a lot to be desired. We are sorry about this.

If you think you are going to be using LSDTopoTools frequently in your research or work we would recommend taking the time to get the python tools working. If you just need a single result for a simple problem (i.e., you just want drainge area or a channel network) then look at LSDTopoTools output in a GIS.

2. Using a GIS to look at LSDTopoTools data

LSDTopoTools outputs both raster and vector data. If you don’t know what those are please see our section on geospatial data.

If you want specific instructions for loading data please see our QGIS section.

2.1. Raster data

Our raster datasets are in the ENVI bil format. We like this format because it is simple but contains all the georeferencing information you need to load it into a GIS.

  • The ENVI bil format can be read by both ArcMap and QGIS.

  • You can convert it to other formats using GDAL. Note that QGIS has GDAL built in.

2.2. Vector data

LSDTopoTools also produces vector data. This vector data is almost always point data. Points with locations and attributes are printed to file, and you need to get this into your GIS. LSDTopoTools outputs point data in two formats:

  • csv format: This is comma separated value.

    • Most of our csv data files include the latitude and longitude of the points.

    • If you import csv data into a GIS, you need to tell it the coordinate system. If the csv file has latitude and longitude headers, the coordinate system is WGS-84 which is the same as EPSG:4326

  • Geojson format. Some of our LSDTopoTools programs allow you to convert csv files into geojson files.

    • Geojson files contain georeferencing, so you can load them as victor data directly into a GIS: you don’t need to tell the GIS what coordinate system the data is in.

    • Geojson data is also compatible with many web mapping formats, like d3.js or leaflet.

    • Unfortunately, Geojson files are huge so if you are processing big datasets and are writing geojson data you will very quickly end up filling your hard disk!

3. Installing the LSDTopoTools python toolchain

So you have tried looking at LSDTopoTools output and are prepared to try our fancy python scripts. I am afraid before you can use these you are going to have to install our python toolchain.

The most painless way to do this is with miniconda and our environment files.

Even if the python installation works flawlessly and installs first time, it will still take some time and suck up quite a lot of space on your hard drive.

3.1. Where do I install the LSDTopoTools python toolchain

If you are working in native linux then you don’t have to worry about this. But if you are using either a Docker or Vagrant setup, you will need to worry. Do you install on your host operating system or on the Linux system that lives as a container or virtual machine?

We have installed the toolchain on our host operating system. There are three main reasons we did this:

  • The container/virtual machine systems have no windowing so you can’t use spyder. We like to use spyder so we wanted a windowing system.

  • I (SMM) tried to install the toolchain once on our vagrant machine and it killed GDAL. I don’t understand why this happened but GDAL is absolutely essential to LSDTopoTools data preparation so I had to destroy my vagrant box and start again from scratch. So I’ve only got this working on my Windows system (but others have got it working on Linux and MacOS).

  • Chances are you might want to use python for something other than LSDTopoTools and it is convenient to have python installed on your host machine.

If you really want to install the toolchain in your vagrant/docker box go ahead but it will be difficult for us to debug since we have not done this ourselves.

3.2. Setting up Python the easy way

This is a quick guide. There are many options for setting up python but this is our preferred setup.

  1. Download and install miniconda on your host machine.

  2. Open a command prompt (use the start menu to search for cmd.exe)

  3. Get our environment file. There are three of them:

    1. environment.yml is for Windows.

    2. environment_linux32.yml is for a 32 bit Linux system.

    3. environment_linux64.yml is for a 64 bit Linux system.

    4. If you are on MacOS you should try the environment_linx64.yml file. If you use MacOS please let us know if it works.

  4. Download the appropriate file onto your computer.

  5. Create the environment from that file with:

    > conda env create -f environment.yml

    I’m afraid this will take a little while.

  6. Activate the environment:

    > activate LSDTT
This environment does not include spyder, you can install it with conda install -n LSDTT spyder

3.3. Setting up python the hard way (without the environment.yml file)

If the environment file doesn’t work

If the environment.yml file doesn’t work, you can set up an environment this way.

This is an alternative to the previous section!
  1. The best way to install python is miniconda. Currently everything we use is tested on Python 2.7, but we have attempted to maintain compatibility to python 3.x. In fact, some essential packages within LSDMappingTools will soon lose Python 2.7 support so we now reccomend a python 3.x install. Unfortunately we have not tested all of the scripts for python 3.x compatibility yet!!!!

    Our visualisation routines involve some computation, and dealing with geospatial data. This means that there are a number of packages to install. This might take some time. If you are already using python for something critical you may consider setting up a virtual environment to ensure all of these new packages don’t break what you’ve already got.
  2. Once you have installed miniconda, you can go into a command prompt (windows) or terminal (MacOS and Linux) and get the other stuff you need. To get the command prompt in windows look for the cmd.exe program.

  3. You should create a python environment for LSDTopoTools. This will keep the LSDMappingTools dependencies separate from your other python installations so we don’t break your other python stuff. Read about conda python environments here:

    > conda create --name LSDTT
    > conda activate LSDTT

    After doing this you should see the name of the environment on your termial or command prompt:

    (LSDTT) >
  4. Now we start by adding a bunch of standard packages:

    > conda config --add channels conda-forge
    > conda install numpy scipy matplotlib pandas
  5. Now install the geographic tools

    > conda install gdal shapely fiona rasterio pyproj basemap
  6. Finally add descartes. Note that on windows, MacOS and 64 bit Linux you can just add descartes to the line above. The reason we need this extra line for 32 bit linux is because there isn’t a specific 32bit version of descartes.

    > conda install -c conda-forge descartes
  7. Every time you use our tools, you should activate the LSDTT python environment.

  8. To run spyder you just type spyder at the command line.

    Spyder needs an older version of a package called PyQt. If spyder doesn’t start correctly, run conda install pyqt=4.10 -f
    It is entirely possible that we have forgotten some package, but if you run one of our scripts and it tells you the package is not found, just use conda to install.

3.4. Using Spyder

Once you have installed python, you can use it from the command line (i.e. from a powershell or terminal window). That is how we do it. However, you might prefer using a nice development environment that checks your code and has pretty colours and reassuring windows. When we are not using text editors (see our section [Text editors for modifying files]) we tend to use Spyder, which has an editor that can give you help with python packages and highlight your mistakes. You should have already installed it with conda install spyder, so to get it running go into a powershell or terminal window and just type:

> spyder
You cannot run spyder on the vagrant machine since it has no windowing system. If you want to run Spyder you need to use your host operating system. This is the one of the reasons we encourage you to do your python installation on your host operating system and not the vagrant machine.

3.5. Fixing python gdal in windows

If you are using windows, there is a stupid bug in the conda gdal package where it cannot find the gdal data. To fix this:

  1. Search for the file gcs.csv. Note the folder in which it is located. On my system it is in C:\Miniconda2\Library\share\gdal

  2. Go into the control panel, go to system (or system and security, then system), click on advanced system settings and in system variables enter a new variable: GDAL_DATA. For the value of this enter the directory where the gdal data is that you found above.

4. Basic LSDTopoTools visualisation

Okay, we are going to take you through some basic visualisation using LSDMappingTools.

4.1. Getting our LSDMappingTools and other tools

Our vagrant setup has no graphical user interface (you only interact with it through a terminal) so we suggest using your host operating system for python.

  1. You need to clone our repository LSDMappingTools.

    At the moment LSDMappingTools is a complete mess. It currently serves as a bit of a sandbox for visualisation development. One day we will clean it all up and make a nice, pretty release. But for now I’m afraid you’ll need to rely on this repository.
  2. If you don’t want to install git on your host operating system, you can clone the repository from your vagrant machine. Because of the clever way vagrant works you will be able to use these files in you host operating system.

    $ cd /LSDTopoTools/Git_projects
    $ git clone https://github.com/LSDtopotools/LSDMappingTools.git
    In your host operating system these files will not be in /LSDTopoTools/Git_projects. They will be within the VagrantBoxes\LSDTopoTools\Git_projects directory (wherever you put it. On windows I put mine in the C directory).
  3. Once you have this repository you can move on to our examples in the next chapter.

4.1.1. Ensuring you can use the tools

I am very sorry to tell you that we do not have a nice pacakge installation for LSDMappingTools. If you want to make one please fork the repo and try it out. Although [Benoit Bovy] might have already done it by the time you read this.

That means:

  1. You need to ensure you are in the LSDTopoTools python environment, which is descripted in the previous section.

  2. For typical usage you need to be sitting in the directory holding LSDMappingTools (i.e., the directory into which you cloned the repository).

  3. You can avoid being in the LSDMappingTools by altering your pythonpath.

    1. You can do that within a current python session with (but you need to actually go into the python scripts and add this line):

      import sys
      
      sys.path.append("PATH/TO/LSDMappingTools/")
    2. Because that is a little bit tedious we usually just call LSDMappingTools scripts from withing the LSDMappingTools directory. We recognise this is a little obtuse but these tools have evolved as the scripts we use to create figures for papers rather than as a coherent software package. If you are unhappy with the ad-hoc state of this package we would be delighted if you forked the repo and tried to wrap it as a package.

4.2. A note on the test datasets

The examples in this section are all from the Tests folder in LSDMappingTools. The raster datasets are all in ENVI bil format, which include a bil file and a hdr file. The

  • WA.bil: The topographic raster

  • WA_HS.bil: hillshade

  • WA_AllBasins.bil: A raster map of the basins

  • WA_all.csv: A channel network generated by the print_chi_data_maps: true flag. See LSDTopoTools basic usage documentation for details

  • A python script for testing some basic plots: LSDMappingTools_test.py

These datasets have all been generated by LSDTopoTools. You can read about how to generate them in the LSDTopoTools basic usage documentation.

4.3. Your first LSDMappingTools plots

The good news here is that installing the LSDTT python toolchain is more difficult than creating your first plot. If your python environment is working you are already most of the way there!

We will walk through this example using the command line. You need to use the operating system within which you installed the LSDTT python environment. If you don’t know what that is read the installation section.

The first plots are really just to test if your environemnt is working. But we will give you a bit of information about how the scripts work after you produce the plots.

The scipts here print figures to files; you will not see a window with a figure pop up. Instead, after you run the scripts, look in the Tests directory and open the png files.
  1. Make sure your LSDTT python enviroment is activated:

    > activate LSDTT
    1. In windows you will need to be in a cmd.exe window.

    2. In linux or MacOS you might need to type source activate LSDTT to get the environment to work.

    3. If the environment is loaded you should see it in parentheses before the command prompt, e.g., (LSDTT) > or (LSDTT) $.

  2. Navigate to the folder in the LSDMappingTools repository called Tests.

  3. Call the LSDMappingTools_test.py python script. This script is called with a single number: 1,2 or 3. These make different plots.

4.3.1. A basic draped hillshade

This creates a very basic draped hillshade. The "drape" is an elevation raster draped over a hillshade. For obvious reasons it needs a elevation raster and a hillshade raster:

(LSDTT) > python LSDMappingTools_test.py 1
Draped hillshade
Figure 1. A simple draped hillshade

4.3.2. A hillshade with some basins

This creates a very basic hillshade with some basins plotted. It needs the elevation, hillshade, and basin raster, and a _BasinInfo.csv file (all of which are included in the test data folder):

(LSDTT) > python LSDMappingTools_test.py 1
Some basins
Figure 2. A simple draped hillshade

4.3.3. A hillshade with some channels

This creates a very hillshade with a channel network. The channels come from a csv file that is derived from a chi data map. You can read about how to generate these in our LSDTT basic analysis documentation.

(LSDTT) > python LSDMappingTools_test.py 1
Channels over a hillshade
Figure 3. A simple draped hillshade

4.3.4. What these basic plots do

To understand what these basic plots, we will highlight some of the basic elements of the script. You should have a basic understanding of python. If you don’t, we can recommend the extremely useful courses from either software carpentry or code academy.

Firstly, we are going to import a package called LSDMapWrappers. This is a small package that automates the most basic plots: simple draped hillshades, basin plots and channel plots.

import LSDMapWrappers as LSDMW

Later in the script there are a few options:

    if argv[0] == 1:
        print("Getting basic hillshade")
        LSDMW.SimpleHillshade(DataDir,DataFname)
    elif argv[0] == 2:
        print("Plotting some basins")
        LSDMW.PrintBasins(DataDir,DataFname)
    elif argv[0] == 3:
        print("Plotting the channels")
        LSDMW.PrintChannels(DataDir,DataFname)

You should see here that there are various types of plots from LSDMapWrappers. As it turns out each of these different basic plots has a number of options. For example, here is the code in LSDMapWrappers:

def SimpleHillshade(DataDirectory,Base_file, cmap = "jet", cbar_loc = "right", size_format = "ESURF", fig_format = "png", dpi = 250):
    """
    This function makes a shaded relief plot of the DEM with the basins coloured
    by the basin ID.
    Args:
        DataDirectory (str): the data directory with the m/n csv files
        Base_file (str): The prefix for the m/n csv files
        cmap (str or colourmap): The colourmap to use for the plot
        cbar_loc (str): where you want the colourbar. Options are none, left, right, top and botton. The colourbar will be of the elevation.
                        If you want only a hillshade set to none and the cmap to "gray"
        size_format (str): Either geomorphology or big. Anything else gets you a 4.9 inch wide figure (standard ESURF size)
        fig_format (str): An image format. png, pdf, eps, svg all valid
        dpi (int): The dots per inch of the figure
    Returns:
        Shaded relief plot. The elevation is also included in the plot.
    Author: FJC, SMM
    """

You can see that these functions take the directory of the data files, a Base_file which is the name of the base raster, and a bunch of other options that allow you to modify the figure. LSDMapWrappers assumes that different map layers have specific names (it sacrifices flexibility for ease) so if your base raster is called WA.bil then it expects the hillshade to be called WA_HS.bil and the basin raster to be called WA_AllBasins.bil1, for example.

5. LSDTopoTools visualisation from command line

In this section we are going to use some more flexible tools which you call from a command line.

5.1. Getting the example data

The data we will use in this section is in the LSDTT_chi_examples repository: https://github.com/LSDtopotools/LSDTT_chi_examples

The data is based on a series of catchements draining the southern side of the Shillong Plateau in India, one of the wettest places on Earth. The data we will use has been derived from using our channel steepness tools, but we won’t make you run the code, we simply provide the processed data.

These are:

  • Mega_divide.bil: The topographic raster

  • Mega_divide_hs.bil: hillshade

  • Mega_divide_AllBasins.bil: A raster map of the basins

  • Mega_divide_AllBasinsInfo.csv: A comma separated value file that contains information about the basins. It is generated using the print_basin_raster: true option in our chi mapping tools.

  • Mega_divide_Maskedchi.bil: A raster that contains the chi coordinates of this landscape.

  • Mega_divide_chi_data_map.csv: A csv file containing information about the channel network. It contains information like the area location, stream order, basin number, source number and chi coordinate of the extracted channel network. This comes from using the chi mapping tool with the option print_chi_data_maps: true.

    1. To get the data, you need to clone the repository https://github.com/LSDtopotools/LSDTT_chi_examples. If you are using a vagrant box or a docker container you should probably put this into the /LSDTopoTools/Topographic_projects directory.

      $ git clone https://github.com/LSDtopotools/LSDTT_chi_examples
    2. You need to know where this repository is!! MAKE SURE YOU KNOW THE PATH TO THIS DIRECTORY SINCE YOU WILL USE IT TO CALL OUR PYTHON SCRIPTS.

5.2. Getting LSDMappingTools

You also need to get LSDMappingTools. See the section Getting our LSDMappingTools and other tools. Please don’t just skim that section, it contains important information that is essential for getting the tool working properly.

5.3. A slightly different way to make plots

In the previous section, we made some plots by calling plotting routines in the package LSDMapWrappers. In this section we will use a command line tool to generate plots.

The command line tool is called PlotBasicRasters.py and you give it arguments to make plots. It wraps various functions that live within several LSDMappingTools packages.

It can be used as a general plotting tool but was primarily designed to interface with output from LSDTopoTools.

The name of this script, PlotBasicRasters.py is perhaps a bit misleading because in fact you can make a large number of plots including draped plots, plots that include basins, and channel profile plots.

5.3.1. The basic structure of a PlotBasicRasters.py call

PlotBasicRasters.py is called with a number of command line arguments. Once you are used to the syntax, you should also be able to use similar packages such as PlotMOverNAnalysis.py and PlotLithoInfo.py.

The main elements of a call are:

  • The call to the actual python script: python PlotBasicRasters.py

  • The directory of your data: -dir \My\Data\Location

  • The prefix of the data files -fname RasterPrefix

After that, there are a number of different command line options. For example:

  • -PD True: This creates a drape plot. It expects there to be a raster that has _hs after the raster prefix. So for example if your raster prefix is Xian you need a raster file Xian.bil and a hillshade raster Xian_hs.bil

  • -PB True: This creates a basin plot. It expects there to be a raster that has _AllBasins after the raster prefix. So for example if your raster prefix is Xian you need a raster file Xian.bil and a hillshade raster Xian_AllBasins.bil. In addition you need a _BasinsInfo.csv file. This is generated with basin printing functions in some of the LSDTopoTools programs.

5.3.2. A basic hillshade using PlotBasicRasters.py

  1. First, make sure you have the LSDTT python environment activated.

    1. In linux:

      $ source activate LSDTT
    2. In a windows cmd.exe prompt:

      $ source activate LSDTT
  2. Now, go to the directory where you cloned LSDMappingTools. Unless you have altered your pythonpath you will need to be in this directory for any calls to the python routines to work.

  3. You also need to look up the location of your data.

    1. If you are in Linux the location will be something like: /LSDTopoTools/Topographic_projects/LSDTT_chi_examples or ~/LSDTopoTools/Topographic_projects/LSDTT_chi_examples.

    2. If you are in Windows the locations will be something like: c:\VagrantBoxes\LSDTopoTools\Topographic_projects\LSDTT_chi_examples

  4. So, lets start with a basic call to plot the elevation over a hillshade.

    1. I am going to assume you have used a vagrant box but you are calling PlotBasicRasters.py from windows. Your system might differ so you’ll need to update the path names.

    2. Here is the call:

      $ python PlotBasicRasters.py -dir c:\VagrantBoxes\LSDTopoTools\Topographic_projects\LSDTT_chi_examples -fname Mega_divide -drape_fname Mega_divide -PD True -dpi 100
  5. This prints a figure in the raster_plots directory. The resulting figure looks like:

    Draped elevation plot
    Figure 4. A simple draped elevation plot
    1. The -PD True options turns on the drape plotting

    2. The -drape_fname Mega_divide means that we will just drape the elevation over the hillshade.

    3. The -dpi 100 option means that the dots per inch of the figure will be 100.

  6. Why don’t we alter this figure a bit. We can change the colourbar location, or the colourbar label, for example:

    $ python PlotBasicRasters.py -dir c:\VagrantBoxes\LSDTopoTools\Topographic_projects\LSDTT_chi_examples -fname Mega_divide -drape_fname Mega_divide -PD True -drape_cbar_label "Elevation (m)" -drape_cbar_loc bottom -dpi 100

    This figure includes some additional options:

    1. -drape_cbar_label "Elevation (m)" this option lets you change the name of the colourbar label.

    2. -drape_cbar_loc bottom this option allows you to move the colourbar. The options are left, right, top, bottom, and none.

    3. drape_cmap jet The sets the colourmap. See the matplotlib documentation for all the possibilities. If you do a bit of googling you will find that in fact jet is a terrible colourbar which leads people to see patterns that aren’t there. You should consider a colourbar like cubehelix.

      The figure looks like this:

      Draped elevation plot
      Figure 5. A simple draped elevation plot, with some modifications.
  7. You may wish to play with some of the two other flags and see the results:

    1. -fmt png This sets the vigure format. Options are svg, png, pdf. Other amige formats will work, see matplotlib documentation for savefig.

    2. -size ESURF This sets the size of the figure. Or more accurately, the width of the figure. The geomorphology option is 6.25 inches wide (matplotlib uses inches as its length unit…​don’t send me nasty letters in support of the metric system). The big option is 16 inches wide. Everything else will default to the Copernicus (the publishing house for EGU journals) width of 4.92 inches.

5.3.3. Making a basemap

We made a hillshade! Great. But we don’t actually know where we are in the world. However there is an option to create a basemap to see where your raster is.

  1. To call the basemap image, you can use:

    $ python PlotBasicRasters.py -dir c:\VagrantBoxes\LSDTopoTools\Topographic_projects\LSDTT_chi_examples -fname Mega_divide -dpi 100 -BM True -bmrem 20

    The key flags here are:

    1. -BM True This flag simply turns on the basemap. The are printed into the directory basemap_plots.

    2. -bmrem 20 This option sets how wide the image is. This is a multiple of the total width (or height, if that if greater) of the base raster.

  2. The figure looks like this:

    Basemap plot
    Figure 6. A simple basemap.
  3. You can also try to modify the latitude and longitude line spacing by mydifying the flag -bmpsm 0.5. This is a multiplier of how many lat-long lines you want in relation to the width of the map. It uses the smaller of the width and height of the basemap. Try varying this between 0.2 and 3 and see what happens.

5.4. More complex plots with PlotBasicRasters.py

Reminder of basic call to PlotBasicRasters.py
  • First you need to be in the LSDTopoTools python environment. Read the section on Getting our LSDMappingTools and other tools and make sure you activate the LSDTT python environment.

  • The the components of a call are:

    • The call to the actual python script: python PlotBasicRasters.py

    • The directory of your data: -dir \My\Data\Location

    • The prefix of the data files -fname RasterPrefix

    • Then any optional flags you want. To see your choices run python PlotBasicRasters.py -h

We are now going to get a bit more complex and plot some basins and channels. The structure of the python call remain the same, we just call different flags for PlotBasicRasters.py.

5.4.1. A basic channel plot PlotBasicRasters.py

In the first example we will create a very simple channel plot.

Simply call:

$ python PlotBasicRasters.py -dir c:\VagrantBoxes\LSDTopoTools\Topographic_projects\LSDTT_chi_examples -fname Mega_divide -dpi 100 -PCh True

The figure looks like this:

Channel plot
Figure 7. A simple channel plot.

The default of this plot is to plot the channels coloured by elevation, using a blue colour scale. Like most features of PlotBasicRasters.py there are a number of flags that can modify this plot. Many of the options involve selecting basins. So we will explore basin selection next.

5.4.2. Plotting basins

Channels conduct water, sediment and nutrients downslope, but they can also communicate tectonic signals upslope. In many landscapes they set the pace of landscape evolution. Channels are orgaonised into connected networks, contained within drainage basins.

LSDTopoTools analyses frequently involve sorting and selecting drainage basins. LSDMappingTools is designed to ingest and use the drainage basin information produced by LSDTopoTools.

  1. We can start with a very basic basin plot:

    $ python PlotBasicRasters.py -dir c:\VagrantBoxes\LSDTopoTools\Topographic_projects\LSDTT_chi_examples -fname Mega_divide -dpi 100 -PB True
  2. The resulting figure looks like this:

    A simple basin
    Figure 8. A simple basin plot.
  3. The basin numbering is determined algorithmically, but you might want to rename your basins. To do this, you use the -rename_dict flag. This takes the form of a python dictionary. You have keys and values. Each key is the index of the basin (the number in the previous figure) and the value is the new name. These are separated by colons (:). To do multiple basins you separate these key:value pairs with commas. Here is an example:

    $ python PlotBasicRasters.py -dir c:\VagrantBoxes\LSDTopoTools\Topographic_projects\LSDTT_chi_examples -fname Mega_divide -dpi 100 -PB True -rename_dict 0:supa,1:dupa
    when you include the rename_dict there should either be no spaces or the entire dictionary needs to be in quotation marks.
  4. The resulting figure looks like this

    A simple basin with renamed basins
    Figure 9. A simple basin plot with renamed basins.
  5. You can also select basins by using the -basin_keys flag. If you leave this blank, it assumes you want all basins. If you include a comma separated list, it only keeps the basins you have named. The basin indices used are the original, not renamed basin indices. That is, if you are using -rename_dict you need to keep track of the original indices of the basins.

  6. An example is:

    $ python PlotBasicRasters.py -dir c:\VagrantBoxes\LSDTopoTools\Topographic_projects\LSDTT_chi_examples -fname Mega_divide -dpi 100 -PB True -rename_dict 0:supa,1:dupa -basin_keys 0,1,5,6
  7. Again, you must ensure there are no spaces in the list because if there are, the python code will assume this is a new flag and will crash. Here is what the figure looks like:

    A simple basin
    Figure 10. A basin plot with selected basins with some renaming.

5.4.3. Plotting basins and channels

  1. The basin selection algorithms work with channel plotting as well. You can do this with the -PCh flag, or alternatively you can use the -PBC flag to have some semitransparent basins under the channels.

    $ python PlotBasicRasters.py -dir c:\VagrantBoxes\LSDTopoTools\Topographic_projects\LSDTT_chi_examples -fname Mega_divide -dpi 100 -basin_keys 0,1,5,6 -PBC True
  2. The figure looks like:

    Selected channels
    Figure 11. A basin plot with selected basins with some renaming channels.
  3. You can also change the colouring of the channels using a flag -SimpleChFmt. You can choose elevation, drainage_area, source_key, or basin_key to colour your channels. This works with both the -PCh and -PBC flags:

    $ python PlotBasicRasters.py -dir c:\VagrantBoxes\LSDTopoTools\Topographic_projects\LSDTT_chi_examples -fname Mega_divide -dpi 100 -basin_keys 0,1,5,6 -PBC True -SimpleChFmt source_key
  4. The figure looks like this:

    Selected channels
    Figure 12. A basin plot with selected basins with some renaming channels.