GRASS GIS Jupyter notebooks: Difference between revisions

From GRASS-Wiki
Jump to navigation Jump to search
(→‎Windows tricks: source: https://lists.osgeo.org/pipermail/grass-user/2023-September/083436.html)
 
(23 intermediate revisions by 3 users not shown)
Line 1: Line 1:
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.
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.


You can even change the code and explore your modified script(s).
== Get started ==


== How to run GRASS GIS from Jupyter notebook ==
Read the intro in the official documentation for [https://grass.osgeo.org/grass-stable/manuals/libpython/grass.jupyter.html grass.jupyter package].


Running GRASS from Jupyter notebook requires that Jupyter notebook is installed on your system, and that you set up the [https://grass.osgeo.org/grass72/manuals/variables.html environment variables] for using GRASS. For example you can create a script called grass_jupyter.sh that contains the following lines:
== List of selected GRASS GIS Jupyter notebooks ==


<source lang="bash">
''(add yours to the list!)''


# directory where GRASS lives
'''Intro notebooks:'''
export GISBASE=/usr/local/grass-7.3.svn # Change this path to reflect your own
* [https://github.com/OSGeo/grass/blob/main/doc/notebooks Official notebooks in OSGeo/grass repo] ([https://mybinder.org/v2/gh/OSGeo/grass/main?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fjupyter_example.ipynb jupyter_example.ipynb on Binder])
* [https://github.com/ncsu-geoforall-lab/grass-gis-workshop-foss4g-2022 Unleash the power of GRASS GIS with Jupyter (FOSS4G 2022 workshop)]
* [https://github.com/ncsu-geoforall-lab/grass-gis-workshop-FOSS4G-2021 GRASS GIS: From Beginner to Power User (FOSS4G 2021 workshop)]
* [https://github.com/wenzeslaus/try-grass-in-jupyter-with-bash wenzeslaus/try-grass-in-jupyter-with-bash] (experimental)
* NSF platform: https://wholetale.org/
** GRASS GIS Introduction, by Anna Petrasova: https://dashboard.wholetale.org/run/63d832bab4a0197e9a9ecdad?tab=files


# generate GISRC
'''Workbook Collections:'''
# Defines the system wide value while in a GRASS session
* [https://github.com/wenzeslaus/geospatial-modeling-course-jupyter/tree/master/notebooks 14 Jupyter Notebooks for learning geospatial analysis and modeling with GRASS GIS] (Python and command line versions)
MYGISDBASE=$HOME/grassdata # Change this path to reflect your own
MYLOC=MyLoc # Change this location name to reflect your own
MYMAPSET=PERMANENT


# Set the global grassrc file to individual file name
'''Species Distribution Modeling:'''
MYGISRC="$HOME/.grassrc.$$"
* NSF platform: https://wholetale.org/
** Using satellite data for Species Distribution Modeling with GRASS GIS and R, by Veronica Andreo https://dashboard.wholetale.org/run/64388157b3b74e434bd8f1ac?tab=files


echo "GISDBASE: $MYGISDBASE" > "$MYGISRC"
'''Image processing/OBIA:'''
echo "LOCATION_NAME: $MYLOC" >> "$MYGISRC"
* [https://github.com/veroandreo/foss4g2022_grass4rs GRASS GIS for remote sensing data processing and analysis]
echo "MAPSET: $MYMAPSET" >> "$MYGISRC"
* [https://github.com/neteler/jupyter_sentinel2_grass_gis GRASS GIS 8 and processing of multitemporal EO data]
echo "GRASS_GUI: text" >> "$MYGISRC"
* [https://github.com/tgrippa/Opensource_OBIA_processing_chain An open-source semi-automated processing chain for urban OBIA classification]
 
'''Python and PyGRASS:'''
* [https://github.com/zarch/workshop-pygrass Workshop on PyGRASS using IPython notebook]
* [https://github.com/wenzeslaus/foss4g-2022-developing-custom-grass-tools Developing custom GRASS tools (FOSS4G 2022 workshop)]
* [https://github.com/wenzeslaus/python-grass-addon How to write a Python GRASS GIS 7 addon (FOSS4G Europe 2015 workshop)]
* [https://github.com/lucadelu/docker-stacks/tree/geospatial/geospatial-notebook Jupyter Notebook Geospatial Python Stack]
 
'''R and GRASS GIS:'''
* [https://gist.github.com/joergsteinkamp/43fb13a82aeab9b5c0dcc4433f97f1a6 Simple Opensource GIS examples with GRASS GIS and R]
 
'''Wildfire Modeling:'''
* [https://github.com/acoiman/wildfire_modeling Wildfire Modeling in Yosemite National Park]
 
== Running GRASS GIS in Jupyter Lab with docker ==
 
* JupyterGrass: GRASS GIS in Jupyter Lab
** docker-compose file and instructions: https://gist.github.com/manuelep/e56fe90399c44e02e7cb97d5ef95edbd
 
== 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:
 
<syntaxhighlight lang="bash">
pip install jupyter
</syntaxhighlight>
 
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 [https://github.com/ncsu-geoforall-lab/GIS714-assignments/blob/main/GRASS_GIS_Foundations/JupyterOnWindows_Tutorial.ipynb NCSU GIS714 Jupyter On Windows Tutorial] for installing Jupyter using pip which is linked with Python linked to GRASS GIS.


# path to GRASS settings file
=== Start Jupyter, then GRASS GIS ===
export GISRC=$MYGISRC


export LD_LIBRARY_PATH=$GISBASE/lib:$LD_LIBRARY_PATH
<syntaxhighlight lang="bash">
export PYTHONPATH=$GISBASE/etc/python:$PYTHONPATH
jupyter lab
export PATH=$GISBASE/bin:$GISBASE/scripts:$PATH
</syntaxhighlight>


# start the notebook in the notebook folder
In a notebook, start the session using the [https://grass.osgeo.org/grass-stable/manuals/libpython/grass.jupyter.html grass.jupyter package].
cd $HOME/notebooks # change this path to reflect your own path to notebooks folder


nohup jupyter notebook --ip=0.0.0.0 --port=8888 --debug &
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 [https://github.com/ncsu-geoforall-lab/GIS714-assignments/blob/main/GRASS_GIS_Foundations/JupyterOnWindows_Tutorial.ipynb NCSU GIS714 Jupyter On Windows Tutorial]. (The session in command line will be replaced by a new session in the notebook.)


</source>
=== Start GRASS GIS, then GRASS GIS ===


Add this line to your $HOME/.bashrc file:
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:


<source lang="bash">
<syntaxhighlight lang="bash">
alias grass_notebook='sh grass_jupyter.sh'
$ grass ...
</source>
GRASS > jupyter lab
</syntaxhighlight>


From terminal, in your home directory:
This can be done in one command, avoiding need for an additional step in the GRASS shell:
<source lang="bash">
source .bashrc
</source>


Now you can start your notebook typing in the terminal:
<syntaxhighlight lang="bash">
<source lang="bash">
$ grass ... --exec jupyter lab
grass_notebook
</syntaxhighlight>
</source>


=== List of selected GRASS GIS Jupyter notebooks ===
For example:


(please expand!)
<syntaxhighlight lang="bash">
$ grass ~/data/world_wgs84/coastal --exec jupyter lab
</syntaxhighlight>


* OSGeoLive-Notebooks: [https://github.com/OSGeo/OSGeoLive-Notebooks/tree/master/GSoC-2015/Introduction%20to%20GRASS%20GIS Introduction to GRASS GIS]
=== Windows tricks ===
* [https://github.com/zarch/workshop-pygrass Workshop on pygrass using IPython notebook]
 
* [https://github.com/tgrippa/Opensource_OBIA_processing_chain An open-source semi-automated processing chain for urban OBIA classification]
If you get the error
* [https://github.com/wenzeslaus/python-grass-addon How to write a Python GRASS GIS 7 addon]
 
* [https://github.com/lucadelu/docker-stacks/tree/geospatial/geospatial-notebook docker-stacks/geospatial-notebook]
<syntaxhighlight lang="python">
* [https://github.com/wenzeslaus/geospatial-modeling-course-jupyter/tree/master/notebooks 14 Jupyter Notebooks for learning geospatial analysis and modeling with GRASS GIS]
FileNotFoundError: [WinError 2] The system cannot find the file specified
</syntaxhighlight>
 
note that the executable on Windows is '''not called''' <tt>'''grass'''</tt> like on Linux but <tt>'''grass8'''</tt> or <tt>'''grass83'''</tt> (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., <tt>C:\...\grass83.bat</tt>), e.g.
 
<syntaxhighlight lang="python">
# 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()
)
</syntaxhighlight>
 
== Infrastructure ==
 
* NSF platform: https://wholetale.org/
** Using satellite data for SDM with GRASS GIS and R, by Veronica Andreo https://dashboard.wholetale.org/run/64388157b3b74e434bd8f1ac?tab=files
** GRASS GIS Introduction, by Anna Petrasova: https://dashboard.wholetale.org/run/63d832bab4a0197e9a9ecdad?tab=files
* Colab (Google)
* Binder


==== See also ====
== Tools ==


* [https://github.com/wenzeslaus/gdoc2py GRASS GIS focused converter from HTML with pre code tags to Jupyter Notebook]
* [https://github.com/wenzeslaus/gdoc2py GRASS GIS focused converter from HTML with pre code tags to Jupyter Notebook]
* RISE: Jupyter/IPython Slideshow Extension, https://rise.readthedocs.io/en/stable/


[[Category: Documentation]]
[[Category: Documentation]]
[[Category: Python]]
[[Category: Python]]
[[Category: Tutorial]]

Latest revision as of 18:51, 29 September 2023

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