landlab / tutorials

Landlab tutorials

As of mid December 2019 the Landlab tutorials are no longer being maintained here. The content that is in this repository has been brought into the main landlab repository which allows the development team to better ensure that the tutorials will always run with Landlab.

Most of these Landlab tutorials can either be read as text files or run as interactive IPython notebooks (recommended!).

To run the IPython notebook tutorials locally, you can copy this landlab/tutorials repo to your local working environment (use the download ZIP button or fork/clone, whichever is most familiar to you).

Alternatively, you can also access each notebook online from https://nbviewer.jupyter.org/github/landlab/tutorials and download an individual notebook (navigate to the specific IPython notebook you want, open it, and click the download button that appears in the upper right).

After downloading/cloning, navigate into your new directory (or to the directory containing your new download) from the command line in your terminal.

Use the command $ jupyter notebook to launch Jupyter, the IPython notebook viewer (it will open locally in your browser). Then navigate to the .ipynb tutorial you want to run and click to open it.

To run the code in the notebook, place your cursor in a code cell, hold down shift, and press enter. The order in which you run the cells matters. You can even experiment with typing your own code into the cell and running that.

Here is a short IPython notebook tutorial along with a screencast (the tutorial uses an example with statistics, but you can substitute Landlab!): http://www.randalolson.com/2012/05/12/a-short-demo-on-how-to-use-ipython-notebook-as-a-research-notebook/

tutorials's Issues

clarify Part 3 example in Lithology tutorial

This is really just a suggestion, but I spent a while trying to understand the use of the rock_id keyword in lith2.run_one_step(). While it may seem repetitive, I think it will help the reader to follow if you add comments before the run_one_step() calls in Part 3. Of course, I had read in the text above that you were doing this because LinearDiffuser() may deposit material. But, by the time I got down to the code I had forgotten this and spent about 15 min in the docs sorting it out (then ultimately remembering I had seen that above). I think it will save folks a bit of time if you: 1) make an explicit statement in the text at the start of part 3 that you have to use rock_id in run_one_step any time material is deposited. 2) Insert comments above the three calls to run_one_step that remind the reader why that parameter is there, as well as why it is changing from 0 to 1 to 0. In general, clarity would probably be improved by scattering more comments throughout the tutorial code.

Is there any way to produce less channels?

I created a 500*1000 grid. After evolving over thousands of years, almost 30 channels formed. But the more rivers there are, the easier it is to river capture. So I want tu focus on just about 5 rivers. Is there any way to control the number of rivers?

Is there any way to produce less channels?

I created a 500*1000 grid. After evolving over thousands of years, almost 30 channels formed. But the more rivers there are, the easier it is to river capture. So I want tu focus on just about 5 rivers. Is there any way to control the number of rivers?

Is topographic__gradient really an input field in making_components.ipynb?

In the component making tutorial, topographic__gradient doesn’t appear to be an input field. I say that because:

1. It’s created if it’s missing.
2. Even if it isn’t missing, it automatically gets immediately overwritten during instantiation with a new set of values.

That sounds like an output field to me, not an input field. It might be ambiguous if there was some testing performed to use the values if provided but to calculate gradients if not, but that's not happening. Ergo, this is a straight-up output field as written.

Probably needs to be fixed by @gregtucker, as he wrote this and it feels a bit cheeky just to change.

Components tutorial needs to be updated in line with reverting channel profiler

See landlab/landlab#695

Unexpanded and Python script tutorials

In most of the tutorial folders we have three versions of each tutorial. Two are Jupyter notebooks that should be the same except one is unexpanded (ends in _unexpanded.ipynb) and the other expanded. The third is the notebook saved as a .py file.

I propose we get rid of the _unexpanded.ipynb and .py files and just keep a single version of the tutorial in our repository. The main reasons being it's easier to maintain one version and reduces the risk of the three files falling out of sync.

What do folks think?

Unable to import FlowAccumulator

It appears that the flow direction and accumulation tutorials are not working with the latest landlab release. The error that I get is,

>>> from landlab.components import FlowAccumulator 
ImportError: cannot import name FlowAccumulator

I think the problem is probably just that the tutorials under flow_direction_and_accumulation were written for the development version of landlab that's in master - not the latest release (v1.0.3). I propose we move these tutorials to a new branch (and remove them from master) until we have a new release that fixes this problem.

All the tutorials on the master branch should work with the latest released version of landlab. (at least that's what I remember us agreeing to)

Or we could do something like we do with landlab and have a release branch with tags that point to the version of landlab that the tutorials work with and have master work with the development version of landlab. But that that's another issue.

user warning in flexure tutorial

at step 3 get this user warning:

/Users/jennyknuth/anaconda/lib/python2.7/site-packages/matplotlib/init.py:1350: UserWarning: This call to matplotlib.use() has no effect
because the backend has already been chosen;
matplotlib.use() must be called before pylab, matplotlib.pyplot,
or matplotlib.backends is imported for the first time.

warnings.warn(_use_error_msg)

DataRecord Tutorial error raised by xarray module when passing axis to Dataset through the calc_aggregate_value method

In the DataRecord Tutorial, an error is raised in cell 16, when running:

mean_size = dr_2.calc_aggregate_value(func=np.mean,
data_variable='boulder_size')

Error message from the xarray module:
passing 'axis' to Dataset reduce methods is ambiguous. Please use 'dim' instead.

Update animation tutorial

The animation tutorial seems to be producing blank output in some cases. I recommend modifying it to use MPL's FuncAnimation, which I've had good luck with recently.

Tests fail but Travis Reports a pass

For example this build: https://travis-ci.org/landlab/tutorials/jobs/430344073

New notebooks break the CI tests

@ChristinaB - your merge for PR #40 broke the tutorials continuous integration. One of the reasons for this is that the notebooks rely on geopandas but nowhere is the dependency described (e.g. in a requirements.txt file). Since the builds fail on that line, its hard to tell if that is the only place there is a problem or if there are others (e.g. if these notebooks take a long time to run, the tests will time out and fail).

I've assigned @saisiddu only because I can't seem to assign @ChristinaB

Binder: dask module absent, which make lithology_and_litholayers nbk fail

When I try to run the landlab notebook lithology_and_litholayers
(https://hub.gke2.mybinder.org/user/landlab-landlab-2wyz3sai/notebooks/notebooks/tutorials/lithology/lithology_and_litholayers.ipynb) on binder, an error is raised:

ModuleNotFoundError Traceback (most recent call last)
/tmp/ipykernel_640/3503426862.py in
5 import numpy as np
6 import xarray as xr
----> 7 import dask
8
9 import matplotlib

ModuleNotFoundError: No module named 'dask'

.travis.yml has a duplicate mkdir -p $MPLCONFIGDIR

This occurred because @mcflugen and I were working on fixing the .travis.yml file at the same time and our changes were not in conflict with one another.

Tutorial teaches creating blank grid fields

But this seems not to be the preferred approach in polished Landlab components. The tutorial should reflect whichever approach (create a blank field, throw an error, whatever) is preferred.

Travis test fails

The travis tests seem to be generating

ImportError: no module named landlab

@mcflugen any ideas?

v2_dev ci

@mcflugen I'm having an issue with checking out the landlab/landlab/v2_dev branch...

See for example: https://travis-ci.org/landlab/tutorials/jobs/609818281#L389

Any recommendations?

Until I get this branch functioning... I'm just pushing directly to it. So feel free to do that if you see an easy fix.

wrong link to Lithology docs

In the Lithology and LithoLayers tutorial the link to the full Litholayers documentation is incorrect. It points to layers.litholayers. I think it should be components.litholayers.

Update all tutorial's to point to tutorial page on RTFD instead of the wiki

As part of the LL2.0 update of the tutorials (to occur after @gregtucker 's marathon updating of the tutorials 🏃 !), we will need to remove the references to the wiki

Most of them contain the following text:

For more Landlab tutorials, click here: https://github.com/landlab/landlab/wiki/Tutorials

and this points to the wiki. This URL will need to change to the url on RTFD for the tutorials.

We will also want to make sure that all links between notebooks are relative (e.g., don't reference binder, or nbviewer, or local...) which will mean they will work everywhere.

Similar to @gregtucker 's current 1.x best practices improvements, this can be a pre 2.0 improvement.

MatplotlibDeprecationWarning on gca() in the FlowDirector and FlowAccumulator nbks

The function surf_plot() in the three notebooks compare_FlowDirectors, the_FlowAccumulator, the_FlowDirectors, instantiate the axes of a figure by the call
ax = fig.gca(projection='3d').

This call raises the following warning:
/srv/conda/envs/notebook/lib/python3.7/site-packages/ipykernel_launcher.py:26: MatplotlibDeprecationWarning: Calling gca() with keyword arguments was deprecated in Matplotlib 3.4. Starting two minor releases later, gca() will take no keyword arguments. The gca() function should only be used to get the current axes, or if no axes exist, create new axes with default keyword arguments. To create a new axes with non-default arguments, use plt.axes() or plt.subplot().

Component tutorial needs to be updated with FlowAccumulator instead of FlowRouter

also, the Landlab logo goes missing if you copy the notebook (unlike the fault scarp tutorial)

Running tests locally

I don't appear to be able to run the tests locally using the unix script (or the python script come to that, as the error below indicates). The shell script throws:

Traceback (most recent call last):
Traceback (most recent call last):
  File "./run_notebook.py", line 14, in <module>
  File "./run_notebook.py", line 14, in <module>
    from scripting.unix import system, check_output
    from scripting.unix import system, check_output
ImportError: ImportErrorNo module named scripting.unix: 
No module named scripting.unix

I tried conda install scripting, but it claimed such a package doesn't exist.

What's up here? I should note I'm running zsh, not bash, if that's relevant.

future warning in component tutorial

https://nbviewer.jupyter.org/github/landlab/tutorials/blob/master/component_tutorial/component_tutorial.ipynb

at step 12, get the following warning:
//anaconda/lib/python2.7/site-packages/matplotlib/collections.py:590: FutureWarning: elementwise comparison failed; returning scalar instead, but in the future will perform elementwise comparison
if self._edgecolors == str('face'):

Update tutorials for Landlab 2.0

Prior to the release of Landlab 2.0, we need to:

• update tutorial notebooks for current (1.x) usage where needed
• update tutorials to work with 2.0 where needed
• verify each tutorial (either it will work with 2.0 or has a version ready for 2.0)

Link to `landlab-fault-scarp.py` is broken

The link to landlab-fault-scarp.py in this tutorial is broken and needs to be removed or replaced. Line 401.

Minor inconvenience but if anybody knows where this file went (I tried searching the landlab repos), do throw it into this tutorial to fix this.

Better tests for next

Rather than testing PRs that want to merge into next against the conda install (which we should expect to break). We should test these PRs against the developer version master branch.

Adding a note to install landlab_dev wiki

I recently did a re-install of anaconda and the landlab development code as per the instructions on:
https://github.com/landlab/landlab/wiki/Installing-Landlab-from-source-code-(%22developer-install%22)

It took a hint from @kbarnhart, though, to realize that I needed to run conda install spyder (and then spyder) while in the landlab_dev environment in order run an instance of spyder that can access landlab. It might be nice to include a more generalized note about this on the landlab source code wiki page.

Thought from B. Campforts during LL paper review

A very small suggestion would be to add a link to the coupled_params_storms.txt file in the ‘Getting to know the Landlab component library’ tutorial on https://nbviewer.jupyter.org/github/landlab/tutorials/blob/master/component_tutorial/component_tutorial.ipynb, similar to the link given for the coupled_params.txt file.

CI broken

Around the time 3.8 was released, everything started breaking.

I'm on vacation, so I'm not going to deal with this, but the issue serves to put a pin in it.

travis test fails

Some test are failing for #18. The error looks like: python[version='>=3.6,<3.7.0a0'].

@mcflugen, is this a similar issue that was resolved in landlab/landlab#633?