GRASS GIS Jupyter notebooks

From GRASS-Wiki
Jump to navigation Jump to search

A Jupyter Notebook is a web application that allows you to create and share documents that contain scripts and code, equations, visualizations and explanatory text, combined.

Get started

Read the intro in the official documentation for grass.jupyter package.

List of selected GRASS GIS Jupyter notebooks

(add yours to the list!)

Intro notebooks:

Workbook Collections:

Species Distribution Modeling:

Image processing/OBIA:

Python and PyGRASS:

R and GRASS GIS:

Wildfire Modeling:

Running GRASS GIS in Jupyter Lab with docker

Running GRASS GIS in a Jupyter notebook locally

Both Jupyter and GRASS GIS have so called environments or sessions which need to be combined. Existing online environments with example notebooks are usually prepared to run right away, but locally, one must prepare the necessary software setup.

Software requirements

You need to have a working GRASS GIS installation.

You need to have a working Jupyter installation. If you are using pip, you can install Jupyter using:

pip install jupyter

GRASS GIS and the Python you used to install Jupyter need to know about each other.

On Linux, this will be usually true and no special steps are needed. GRASS GIS just uses the system Python and you presumably use pip which uses system Python too.

On Windows, install Jupyter using the Python which is available in GRASS session. There is no system Python on Windows, so, e.g., installing Jupyter in conda and standalone GRASS GIS results in two different and disconnected Python installations. See this NCSU GIS714 Jupyter On Windows Tutorial for installing Jupyter using pip which is linked with Python linked to GRASS GIS.

Start Jupyter, then GRASS GIS

jupyter lab

In a notebook, start the session using the grass.jupyter package.

On Windows, due to a lack of system Python shared among all applications, it is easiest to start GRASS GIS (to get a command line with Python) and start Jupyter from there, see the NCSU GIS714 Jupyter On Windows Tutorial. (The session in command line will be replaced by a new session in the notebook.)

Start GRASS GIS, then GRASS GIS

If the above does not work for you or you want your notebooks to not deal with GRASS session at all, start GRASS shell and then start Jupyter from there, for example:

$ grass ...
GRASS > jupyter lab

This can be done in one command, avoiding need for an additional step in the GRASS shell:

$ grass ... --exec jupyter lab

For example:

$ grass ~/data/world_wgs84/coastal --exec jupyter lab

Windows tricks

If you get the error

FileNotFoundError: [WinError 2] The system cannot find the file specified

note that the executable on Windows is not called grass like on Linux but grass8 or grass83 (to avoid a strange Python import error). That should do the trick. If not, try simply providing a full path yourself including the extension (e.g., C:\...\grass83.bat), e.g.

# Ask GRASS GIS where its Python packages are.
sys.path.append(
    subprocess.check_output(["C:\GRASS GIS 8.3/grass83.bat", "--config", "python_path"], text=True).strip()
)

Infrastructure

Tools