grass_gis_in_google_colab.qmd

---
title: "GRASS GIS in Google Colab"
author: "Veronica Andreo"
date: 2024-04-12
date-modified: today
format: 
  html:
    toc: true
    code-tools: true
    code-copy: true
    code-fold: false
categories: [GRASS GIS, Python, Jupyter, Google Colab, Intermediate]
engine: knitr
execute: 
  eval: false
---

# What is Colab?

Perhaps you have heard of Google Colaboratory or simply Colab. This is a hosted
Jupyter Notebook service that requires no setup or configuration to use and 
provides free access to computing resources, including GPUs and TPUs. 
Colab is especially well suited to machine learning, data science, and education.
Furthermore, it allows easy sharing of workflows which facilitates reproducibility.

Colab notebooks allow you to combine executable code and rich text in a single 
document, along with images, HTML, LaTeX and more. When you create your own 
Colab notebooks, they are stored in your Google Drive account. You can easily 
share your Colab notebooks with co-workers or friends, allowing them to comment
on your notebooks or even edit them. 

::: {.callout-note}
See Colab's FAQ for more details: <https://research.google.com/colaboratory/faq.html>
and follow the Google Colab blog in Medium at <https://medium.com/google-colab>.
:::

# Why GRASS GIS in Colab?

Since Colab offers Jupyter notebooks in a Linux environment 
**it is really easy to install or even compile GRASS GIS there**. 
Also, because of the integration with Google Drive, it is a great resource to 
run our workflows in the cloud and export the results or keep our GRASS 
projects and code there. This clearly facilitates teaching workshops or courses
since attendants do not need to install or download anything on their own 
machines. 

There are a couple of things to consider when working with GRASS GIS within
Colab though. Users will need to 
*install GRASS GIS every time they start a new working session or notebook*. 
Furthermore, whatever files users download within Colab 
*will last only during the current session*. 
If the runtime gets disconnected because of inactivity, downloaded data and
outputs created within Colab, will be lost too. 
If users instead, mount their own Google drive, download data and create their 
GRASS projects there, those will be preserved even if the runtime is 
disconnected or the session closed.

# Install GRASS GIS in Colab

Let's first print system description to know where are we:

```{python}
!lsb_release -a
```

At the time of writing this tutorial, Colab has Linux 
[Ubuntu 22.04.3 LTS](https://medium.com/google-colab/colab-updated-to-ubuntu-22-04-lts-709a91555b3c). 
So we add the ppa:ubuntugis repository, update and install GRASS GIS. It might 
take a couple of minutes according to the resources available.

```{python}
!add-apt-repository -y ppa:ubuntugis/ubuntugis-unstable
!apt update
!apt-get install -y grass-core grass-dev
print("INSTALLATION COMPLETE")
```

Check that GRASS GIS is installed by asking which version is there. 

```{python}
!grass --config version
```

# Set our working directory and download sample data

By default we'll have access to the `/root` folder within Colab, and any data we 
download will be placed there. We can change that of course, it is just a Linux
file system. In any case, we should bare in mind that whatever data we download 
within Colab, will disappear if the runtime gets disconected because of inactivity
or once we close the Colab session. 

Let's get the North Carolina sample dataset into Colab to exemplify a data 
download workflow. We define our folders first:

```{python}
import os

homedir = os.path.expanduser('~')
grassdata = os.path.join(homedir, "grassdata")
project = "nc_spm_08_grass7"
mapset = "PERMANENT"
```

then download the North Carolina dataset into our `homedir`.

```{python}
!wget -c https://grass.osgeo.org/sampledata/north_carolina/nc_spm_08_grass7.zip -O $homedir/nc.zip
```

We unzip the downloaded file within the grassdata folder in /root

```{python}
!unzip -o -q -d $grassdata $homedir/nc.zip
```

and finally check it is indeed there:

```{python}
# List files within grassdata
os.listdir(grassdata)
```

# Start GRASS in Colab

We have GRASS GIS installed and a sample project to play around. Let's add the 
GRASS python packages to PATH to be able to import the `grass.script` and 
`grass.jupyter` libraries.

```{python}
# Import standard Python packages we need
import sys
import subprocess

# Ask GRASS GIS where its Python packages are to be able to run it from the notebook
sys.path.append(
    subprocess.check_output(["grass", "--config", "python_path"], text=True).strip()
)
```

```{python}
# Import the GRASS GIS packages
import grass.script as gs
import grass.jupyter as gj
```

Now we are ready to start GRASS GIS within the North Carolina project.

```{python}
session = gj.init(grassdata, project, mapset)
```

Let's show the current GRASS GIS settings and check if the session actually
works:

```{python}
gs.gisenv()
```

Just as an example, we will list the raster maps and display one of them using 
the InteractiveMap class.

```{python}
gs.list_grouped(type="raster")
```

```{python}
m = gj.InteractiveMap(width = 500, tiles="OpenStreetMap")
m.add_raster("landclass96")
m.add_layer_control(position = "bottomright")
m.show()
```

# Conect Colab with Google Drive

If we do not want to loose our GRASS projects when closing the Colab notebook, 
we can connect Colab with our Google Drive and upload, download or create our 
projects there. To be able to do any of that, we need to mount our drive first
(i.e., similar to what we do with external drives). 
We first import the `drive` library.

```{python}
from google.colab import drive 
```

Then, we define the mounting point. Running the cell below triggers a dialog to 
grant Colab access to our drive. It is possible to change accounts, too. Once
that is complete, we will have access to everything we have in our GDrive folders
and we can browse the content either with commands or from the left panel in
the Colab notebook.

```{python}
drive.mount("/content/drive")
```

We can also mount our drive directly from the Colab interface as shown below: 

![](img/colab_mount_gdrive.png)

Once the GDrive is mounted, we can either create a new project and start GRASS 
GIS there as shown above or start GRASS within an existing GRASS project in 
GDrive. 
Importantly, we can then process and analyse our data and close the session
afterwards that our data will remain in GDrive for the next time.

# Create a new GRASS project in Google Drive

To create a new project we can use the `create_project` function from the 
grass.script library as shown in the 
[GRASS and Python tutorial](). 
Let's, for example, create a project with the EPSG code option:

```{python}
gs.create_project("/content/drive/MyDrive/grassdata/latlong_wgs84", epsg="4326")
```

# Start GRASS GIS in an existing project

Either if you just created the project and want to start GRASS GIS there or if 
you already have your GRASS projects in GDrive, you just need to start GRASS 
wherever the project is, as shown above, given that GRASS GIS has been 
installed in the Colab session and libraries imported.

**Cool, ah?! Enjoy!** {{< fa rocket >}}


***

:::{.smaller}
The development of this tutorial was funded by the US 
[National Science Foundation (NSF)](https://www.nsf.gov/), 
award [2303651](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2303651).
:::