Example notebook for TopoToolbox

If you have used TopoToolbox to do something cool, we would love to feature your work on our website! Creating an example for our gallery can be a great way to share your work with the TopoToolbox community and to get started contributing to the project.

If you are using pytopotoolbox, the easiest way to do this is to create a Jupyter Notebook. This notebook shows you all the components you should have to successfully contribute an example.

Give your example a descriptive title (e.g. “Example notebook for TopoToolbox”) as a top-level heading at the beginning of your notebook. The filename (e.g. “template.ipynb”) must be unique among our example notebooks and should also be descriptive.

This example notebook lives in the docs/dev folder, but you should put yours in docs/examples. Add the filename for your example without the .ipynb extension to docs/examples.rst` to have your notebook show up in our Examples gallery.

Authors

• Will Kearney, University of Potsdam, (homepage, GitHub)

This notebook is licensed under CC-BY 4.0.

List the names and affiliations of people involved in producing your notebook. If you want to provide contact information or social media links, feel free to do so. Remember the principles of scientific authorship in deciding who to list.

Normally code in TopoToolbox is licensed under the GPL v3.0, but you may use another license for your notebook if you wish as long as it complies with the licenses of the software you are using and with any other applicable copyright laws.

Highlighted References

If you have any references you particularly want to highlight – such as a paper that you have recently published using the techniques in your example – list them here. If you have additional references that you would like to cite, you can place them here or at the end.

Audience

Potential contributors to TopoToolbox

It is a good idea to give a brief statement about who you think would get the most out of your example and what they might need to know to follow along. If you are sharing some educational materials that you have used in a course, for example, share the expected prerequisites of students in your course.

Introduction

Add an introduction to your example where you describe the problem you are trying to solve. Think about the audience that you listed above and target the level of description to those readers. Don’t spend too much time describing your problem, though. This is meant to showcase your application of TopoToolbox. Get to the code sooner rather than later!

Dependencies

You will need to import dependencies before running any code that requires those dependencies. Feel free to do so all at once at the beginning, as shown here, or only when you need particular functionality.

In addition to topotoolbox, users can be expected to have matplotlib, numpy, rasterio and scipy because TopoToolbox directly depends on those packages.

import matplotlib.pyplot as plt
import numpy as np
import rasterio as rio
from scipy.ndimage import distance_transform_edt

import topotoolbox as tt3

If you have other dependencies, you can add instructions for installing those dependencies here. Avoid using magic commands like %pip to install packages from within a notebook because users may prefer to install packages in a different manner.

Dependencies other than the ones listed above that are required to run the notebook should also be added to the docs/requirements.txt file in the pytopotoolbox repository. These are not installed by default when a user installs pytopotoolbox. Instead, they are installed when the notebooks are compiled into HTML on our continuous integration server. If the packages are not listed there, they will not be available during compilation and the build process will fail. Be judicious in what dependencies you add here. We will review them and may ask you to make changes to your code if you add too many dependencies or ones that are not essential to your example.

Your Example Here

The rest of the example is up to you! Use the code and multimedia functionality of Jupyter Notebooks to bring your example to life.

Accessing data

There are currently two easy ways to access data from within TopoToolbox, using the load_dem function to load the DEMs that we supply with the software and load_opentopography to download data from OpenTopography.

from matplotlib.colors import Normalize

dem1 = tt3.load_dem('bigtujunga')
dem1.plot_hs(cmap="terrain",norm=Normalize(vmin=-1000,vmax=3000))

<matplotlib.image.AxesImage at 0x7fe431046de0>

Users will need an API key to download data from OpenTopography. See the documentation for how users should provide API keys to TopoToolbox. An API key is available in the correct location on our continuous integration system, so your example using load_opentopography will compile without specifying one.

dem2 = tt3.load_opentopography(south=46.3, north=46.6, west=7.7,
                    east=8.1, dem_type="SRTMGL3")
dem2 = dem2.reproject(rio.CRS.from_epsg(32633), resolution=30)
dem2.plot(cmap='terrain', norm=Normalize(vmin=-1000,vmax=4000))

<matplotlib.image.AxesImage at 0x7fe43088dbe0>

If you can use data from one of these sources to show off your example, please do so: it makes it much easier for users to follow along, and we are unlikely to be able to distribute additional datasets through TopoToolbox.

If you do need external data for your example you can provide code in your notebook to download the data from a publicly accessible storage location such as a web server or an S3 bucket. If you are struggling to make necessary data available for your example, let us know, and we can work on a solution.

Contributing your notebook to TopoToolbox

Once you have developed your notebook, you can submit it to TopoToolbox by making a pull request on GitHub. More information about this process is available on the TopoToolbox website. Please get in touch if you are having trouble!

The one additional thing to be aware of when committing Jupyter Notebooks to our repository is that you will need to strip the code outputs and metadata out of the notebook before you commit the code in git. We use the nbstripout utility to help us do this. Install nbstripout with

pip install nbstripout

and then run it from the command line with

nbstripout --extra-keys="metadata.kernelspec metadata.language_info" FILE.ipynb

where FILE.ipynb is the name of your notebook. This will remove all the necessary metadata for you. After running this, use git add FILE.ipynb and git commit to stage and commit your notebook. Then push to your GitHub fork of pytopotoolbox and open a pull request to the TopoToolbox/pytopotoolbox repository.

We also have set up some pre-commit hooks that will run nbstripout for you when you try to commit your notebook to git. See that link for more information about installing the hooks.

References and Additional Information

Put any additional references, links and information you need at the end of the notebook