new version

Some new functions and features in TopoToolbox

Posted on

Let me highlight some functions that I have added recently. I think that some of these new features come unnoticed.

First, there is the function nal2nal. Obviously, this function handles “nals” which are node-attribute lists. Node-attribute lists are column vectors where each element provides some value (e.g. elevation or distance) for every node in the stream network. Thus, nals are directly linked to the network topology of a particular instance of STREAMobj. But what happens if you want to use a nal of one stream network and map it to another one. Well, that can be done with nal2nal.

Here is an example that uses nal2nal. We map chi-values measured along an entire river network to its first-order streams.

DEM = GRIDobj('srtm_bigtujunga30m_utm11.tif');
FD = FLOWobj(DEM);
S = STREAMobj(FD,'minarea',1000);
S = klargestconncomps(S);

A = flowacc(FD);
c = chitransform(S,A);
S2 = modify(S,'streamorder',1);
c2 = nal2nal(S2,S,c,0);
hold on
h = colorbar;
h.Label.String ='\chi';
chi values of first-order streams

Another new function is mapfromnal. The function maps values measured at each node of the stream network to its upstream hillslope pixels. I showed an example in my previous post on chi inferiority.

Then, there is stackedplotdz. This function takes a STREAMobj and several node attribute lists and plots them on top of each other. If you have MATLAB 2018b, then the function comes with additional functionalities provided by the function stackedplot.

DEM = GRIDobj('srtm_bigtujunga30m_utm11.tif');
FD = FLOWobj(DEM);
S = STREAMobj(FD,'minarea',1000);
S = klargestconncomps(S);
S = trunk(S);
z = getnal(S,DEM);
zs = crs(S,DEM,'tau',0.1,'K',10,'split',false);
g = gradient(S,zs);
k = ksn(S,zs,flowacc(FD));
stackedplotdz(S,{z zs g k},…
'ylabels',{'Elevation' 'smoothed elevation' 'gradient' 'ksn'});
Multiple variables plotted on top of each other using stackedplotdz

Finally, I have created a new repository for some example DEMs. Maybe I have seen Big Tujunga too often now. The repository contains relatively small DEMs (about 30 Mb, github doesn’t allow much larger files) that I will use for demonstration purposes in the future. Until now, there are only two DEMs, but their number will increase in the future. The repository can be accessed via the function readexample that you’ll find the IOtools directory.

DEM = readexample('taiwan');

How do you keep up to date with new releases of TopoToolbox? Do you use git? If not, I’d recommend it.


TopoToolbox documentation integrated in MATLAB help browser

Posted on Updated on

TopoToolbox version 2.3 will have a better documentation. With the latest commits to our github repository, you are now able to take a glance at our work-in-progress. Just download it, follow the instruction in the readme file, and then type


in the command window. MATLAB’s documentation browser will pop up and the landing page will have a new entry in the section Supplemental Software. The link will bring you to the TopoToolbox documentation.

The MATLAB documentation landing page

The documentation features a Getting Started section, numerous guides, and a function reference (which is, however, not linking to the individual help functions).

The TopoToolbox documentation

Moreover, you can now search the documentation which will hopefully make it much easier to find the right tools.

Search the documentation for the term ‘ksn’.

The documentation is not yet complete. We are still working on including the help sections of each function into the documentation, which will make the functionality even more accessible and browsable.

**** addendum January 15, 2018 ****

After permanently setting the paths, you might need to restart MATLAB in order to be able to view the documentation in the help browser.

TopoToolbox 2.2 released

Posted on


The last weeks had been quite busy to finish version 2.2 which was available as a prerelease for a long while. TopoToolbox users who keep their software constantly updated (for example by using GIT) won’t see much changes.  For those that do not keep pace with the frequent commits to our repository, we encourage them to do so now. There are a lot of new functions and modifications. Benjamin Campforts added TTLEM, the TopoToolbox Landscape Evolution Model. The scope of functions for working with river networks (STREAMobj) has tremendously increased with new plotting functions, low-level chi analysis tools, and tools for geometric modifications. We added new functions to hydrologically correct and smooth river networks and values measured along them (e.g. constrained regularized smoothing (CRS)). TopoToolbox now supports multiple flow directions and there are several new functions for working with grids (GRIDobj). In addition, we consolidated the help sections in each function and increased compatibility with older MATLAB versions. Please see the readme-file for a complete overview of changes.

With version 2.2, we offer TopoToolbox as a MATLAB® toolbox file (mltbx-file). This file will make installation very easy. Simply download it, double-click, and follow the instructions.

Dirk and I met this morning in the train (here we are!) …

Dirk (left) and I taking a selfie…

… and discussed possible directions for a next version. The number of functions has increased a lot which entails the threat that TopoToolbox might become confusing and even deterrent in particular for new users. Simply adding new functionalities is thus not the way forward. Instead, we decided that a new version should have a better documentation that should be integrated in MATLABs documentation browser. To quote John D’Errico, a long-time and excellent contributor of MATLAB code: Your job as a programmer does not stop when you write the last line of code. If you think so, then you should be fired. You should document your code. Provide help. Otherwise, that code is just a bunch of random bits, useful to nobody else in the world.

With this in mind, let’s go for 2.3.

Putting together version 2.2

Posted on Updated on

Vigilant readers of the readme file of TopoToolbox may have noticed that the most recent version is 2.2 pre with pre indicating a prerelease. Since version 2.1, a lot has been added including TTLEM, plotsegmentgeometry as well as many other functions and modifications. Now it is time to put all together and finish version 2.2, and Dirk Scherler and I will do so after the summer break. Specifically, we will scan the functions and documentation for possible flaws, bugs, and inconsistencies. We know there are some problems with backward compatibility and out-of-date user guides.

However, there may be more issues and that is where you help is required. Do you know of any bugs or problems in TopoToolbox? If yes, please let us know via comments to this blog post. Make sure, however, that you are using the latest version. Your help is very appreciated.