+ "markdown": "---\ntitle: \"Get started with GRASS in Google Colab\"\nauthor: \"Veronica Andreo\"\ndate: 2024-04-12\ndate-modified: today\nformat: \n html:\n toc: true\n code-tools: true\n code-copy: true\n code-fold: false\ncategories: [Python, Google Colab, beginner]\ndescription: Learn how to analyze geospatial data with Python in Google Colab.\nengine: jupyter\nexecute: \n eval: false\njupyter: python3\n---\n\n\n# What is Colab?\n\nPerhaps you have heard of Google Colaboratory or simply Colab. This is a hosted\nJupyter Notebook service that requires no setup or configuration to use and\nprovides free access to computing resources, including GPUs and TPUs.\nColab is especially well suited to machine learning, data science, and education.\nFurthermore, it allows easy sharing of workflows which facilitates reproducibility.\n\nColab notebooks allow you to combine executable code and rich text in a single\ndocument, along with images, HTML, LaTeX and more. When you create your own\nColab notebooks, they are stored in your Google Drive account. You can easily\nshare your Colab notebooks with co-workers or friends, allowing them to comment\non your notebooks or even edit them.\n\n::: {.callout-note}\nSee Colab's FAQ for more details: <https://research.google.com/colaboratory/faq.html>\nand follow the Google Colab blog in Medium at <https://medium.com/google-colab>.\n:::\n\n# Why GRASS in Colab?\n\nSince Colab offers Jupyter notebooks in a Linux environment\n**it is really easy to install or even compile GRASS there**.\nAlso, because of the integration with Google Drive, it is a great resource to\nrun our workflows in the cloud and export the results or keep our GRASS\nprojects and code there. This clearly facilitates teaching workshops or courses\nsince attendants do not need to install or download anything on their own\nmachines.\n\nThere are a couple of things to consider when working with GRASS within\nColab though. Users will need to\n*install GRASS every time they start a new working session or notebook*.\nFurthermore, whatever files users download within Colab\n*will last only during the current session*.\nIf the runtime gets disconnected because of inactivity, downloaded data and\noutputs created within Colab, will be lost too.\nIf users instead, mount their own Google drive, download data and create their\nGRASS projects there, those will be preserved even if the runtime is\ndisconnected or the session closed.\n\n# Install GRASS in Colab\n\nStart at <https://colab.research.google.com/> and create a new notebook. Let's first print system description to know where are we. The exclamation mark is used for executing commands from the underlying operating system:\n\n::: {#f9585251 .cell execution_count=1}\n``` {.python .cell-code}\n!lsb_release -a\n```\n:::\n\n\nAt the time of writing this tutorial, Colab has Linux\n[Ubuntu 22.04.4 LTS](https://medium.com/google-colab/colab-updated-to-ubuntu-22-04-lts-709a91555b3c).\nSo we add the ppa:ubuntugis repository, update and install GRASS. It might\ntake a couple of minutes according to the resources available.\n\n::: {#607b2f86 .cell execution_count=2}\n``` {.python .cell-code}\n!add-apt-repository -y ppa:ubuntugis/ubuntugis-unstable\n!apt update\n!apt-get install -y grass-core grass-dev\n```\n:::\n\n\nCheck that GRASS is installed by asking which version is there.\n\n::: {#b9234e06 .cell execution_count=3}\n``` {.python .cell-code}\n!grass --version\n```\n:::\n\n\nTo import the `grass.script` and `grass.jupyter` modules, you need to tell\nPython where the GRASS Python package is:\n\n::: {#4c346aa3 .cell execution_count=4}\n``` {.python .cell-code}\n# Import standard Python packages we need\nimport sys\nimport subprocess\n\n# Ask GRASS where its Python packages are to be able to run it from the notebook\nsys.path.append(\n subprocess.check_output([\"grass\", \"--config\", \"python_path\"], text=True).strip()\n)\n```\n:::\n\n\n::: {#cb786a1e .cell execution_count=5}\n``` {.python .cell-code}\n# Import the GRASS packages\nimport grass.script as gs\nimport grass.jupyter as gj\n```\n:::\n\n\n:::{.callout-note}\nBy default we have access to the `/content` folder within Colab, and any data we\ncreate and download will be placed there. We can change that of course, it is just a Linux\nfile system. In any case, we should bare in mind that whatever data we download\nwithin Colab, will disappear if the runtime gets disconected because of inactivity\nor once we close the Colab session.\n:::\n\n# Create a new GRASS project\n\nTo create a new project we can use the `create_project` function from the\ngrass.script library.\nLet's, for example, create a project with the EPSG code\n 32617 (UTM zone 17N):\n\n::: {#b8d4acaa .cell execution_count=6}\n``` {.python .cell-code}\ngs.create_project(\"nc_sentinel\", epsg=\"32617\")\n```\n:::\n\n\nNow we can start GRASS in the created project:\n\n::: {#c10982c5 .cell execution_count=7}\n``` {.python .cell-code}\n# Start GRASS in default project mapset\nsession = gj.init(\"nc_sentinel\")\n```\n:::\n\n\nNow you can import data and start your analysis, following the\n[GRASS and Python tutorial, part A](fast_track_grass_and_python.qmd#a.-use-grass-tools-within-your-python-spatial-workflows).\n\n# Start GRASS with a sample dataset\n\nIf you want to learn data analysis with GRASS, instead of creating a new project from scratch,\nyou can downlaod a ready-to-use sample dataset to play with.\n\n## Download sample data\n\nLet's get the North Carolina sample dataset into Colab to show a data\ndownload workflow.\n\n::: {#ae0f5b33 .cell execution_count=8}\n``` {.python .cell-code}\n!wget -c https://grass.osgeo.org/sampledata/north_carolina/nc_basic_spm_grass7.zip -O nc.zip\n```\n:::\n\n\nWe unzip the downloaded file in /content\n\n::: {#fece99ec .cell execution_count=9}\n``` {.python .cell-code}\n!unzip nc.zip\n```\n:::\n\n\nand finally check it is indeed there:\n\n::: {#52d18cfa .cell execution_count=10}\n``` {.python .cell-code}\nimport os\n\n# List files and directories\nos.listdir()\n```\n:::\n\n\nYou should see *nc_basic_spm_grass7* sample dataset, which is a GRASS project.\n\n## Start GRASS\n\nWe have GRASS installed and a sample project to play around, so we are ready\nto start GRASS within the North Carolina project.\n\n::: {#7451955b .cell execution_count=11}\n``` {.python .cell-code}\n# Start GRASS in default project mapset\nsession = gj.init(\"nc_basic_spm_grass7\")\n```\n:::\n\n\nJust as an example, we will list the raster maps and display one of them using\nthe InteractiveMap class.\n\n::: {#e749b6d3 .cell execution_count=12}\n``` {.python .cell-code}\ngs.list_grouped(type=\"raster\")\n```\n:::\n\n\n::: {#43c514d5 .cell execution_count=13}\n``` {.python .cell-code}\nm = gj.InteractiveMap()\nm.add_raster(\"elevation\")\nm.show()\n```\n:::\n\n\nYou can continue exploring the dataset in [GRASS and Python tutorial, part B](fast_track_grass_and_python.qmd#b.-use-python-tools-within-grass-workflows).\n\n# Connect Colab with Google Drive\n\nIf we do not want to loose our GRASS projects when closing the Colab notebook,\nwe can connect Colab with our Google Drive and upload, download or create our\nprojects there. To be able to do any of that, we need to mount our drive first\n(i.e., similar to what we do with external drives).\nWe first import the `drive` library.\n\n::: {#808fd331 .cell execution_count=14}\n``` {.python .cell-code}\nfrom google.colab import drive \n```\n:::\n\n\nThen, we define the mounting point. Running the cell below triggers a dialog to\ngrant Colab access to our drive. It is possible to change accounts, too. Once\nthat is complete, we will have access to everything we have in our GDrive folders\nand we can browse the content either with commands or from the left panel in\nthe Colab notebook.\n\n::: {#7c2ec7fe .cell execution_count=15}\n``` {.python .cell-code}\ndrive.mount(\"/content/drive\")\n```\n:::\n\n\nWe can also mount our drive directly from the Colab interface as shown below:\n\n{.preview-image}\n\nOnce the GDrive is mounted, we can create a new project and start GRASS there.\nTo stay organized, GRASS projects are often saved under `grassdata` folder.\n\n::: {#f9f29a80 .cell execution_count=16}\n``` {.python .cell-code}\ngs.create_project(\"/content/drive/MyDrive/grassdata/nc_sentinel\", epsg=\"32617\")\ngs.init(\"/content/drive/MyDrive/grassdata/nc_sentinel\")\n```\n:::\n\n\nImportantly, we can then process and analyse our data so that our data\nwill remain in GDrive for the next time.\n\n**Cool, ah?! Enjoy!** {{< fa rocket >}}\n\n***\n\n:::{.smaller}\nThe development of this tutorial was funded by the US\n[National Science Foundation (NSF)](https://www.nsf.gov/),\naward [2303651](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2303651).\n:::\n\n",
0 commit comments