01_Welcome_to_the_fast_lane.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6fb8304a-2c18-46b3-83de-cb3e78bdb1ab",
   "metadata": {},
   "source": [
    "# GRASS GIS 101: Hop into the Fast Lane with Notebooks!\n",
    "\n",
    "Welcome to Jupyter Notebooks! In these notebooks, we'll repeat some of the same workflows we did in the GUI but using code. Then, we'll take it a step further and create our own custom GRASS script!\n",
    "\n",
    "In this first part, we will:\n",
    "1. [learn the basics of operating in a notebook environment](#1.-The-Notebook-environment)\n",
    "2. [Start GRASS GIS and create a new project](#2.-Import-Libraries)\n",
    "3. [Import and visualize data](#4.-Importing-data)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c4f7a41-6e63-41f2-ba4c-4aed11f0b7f7",
   "metadata": {},
   "source": [
    "***\n",
    "\n",
    "## 1. The Notebook environment"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d012ffa-eff5-4363-9d04-326f6a641fa0",
   "metadata": {},
   "source": [
    "By default all cells are running Python:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d5ef74a1-144c-4718-ac76-23a6e9233a20",
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "v = sys.version_info\n",
    "print(f\"We are using Python {v.major}.{v.minor}.{v.micro}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "762f1362-e1ea-4653-bfab-93a5d233e841",
   "metadata": {},
   "source": [
    "We can also use `!` to run individual lines in the terminal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cfc219e0-f429-4849-b709-df1ca34aee24",
   "metadata": {},
   "outputs": [],
   "source": [
    "!echo Howdy"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a758d3df-794f-43ac-bdee-4df0e85febee",
   "metadata": {},
   "source": [
    "Here are some useful keyboard shortcuts in notebooks:\n",
    "\n",
    "* `shift - enter` execute cell\n",
    "* `alt - enter` execute cell and insert new below\n",
    "* `esc` exit cursor/edit mode and enter command mode\n",
    "* `a` add cell above\n",
    "* `b` add cell below\n",
    "* `dd` delete cell\n",
    "* `x` cut selected cells\n",
    "* `c` copy selected cells\n",
    "* `v` paste cells below\n",
    "* `m` change cell to Markdown\n",
    "* `y` change cell to Code\n",
    "\n",
    "Try a few below!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "74098eae-357b-4051-85c4-6ac761e5a8b3",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "1ef3d9ac-63da-4685-9b8f-3aeab3b9b0d6",
   "metadata": {},
   "source": [
    "Markdown cells (such as this one) don't execute code but they **can** contain _nice_ formatting.\n",
    "\n",
    "They can also include `code` snippets:\n",
    "\n",
    "```\n",
    "def hello(name):\n",
    "    print(f\"hello {name}\")\n",
    "```\n",
    "\n",
    "# And Titles\n",
    "## Headings\n",
    "### Subheadings\n",
    "#### and Sub-subheadings\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "... and HTML formatting\n",
    "</div>\n",
    "\n",
    "\n",
    "... and even LaTex!\n",
    "\n",
    "$\n",
    "f(x) = \\int_{-\\infty}^{\\infty} e^{-x^2} dx\n",
    "$"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "445c5df7-03ab-4131-afc1-84523be90ef4",
   "metadata": {
    "tags": []
   },
   "source": [
    "***\n",
    "\n",
    "## 2. Import Libraries"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0a0421d-1a48-46aa-ab94-113b11427335",
   "metadata": {},
   "source": [
    "Import Python standard library and IPython packages we need."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "07dec1d8-f0b5-4d18-929b-807cca8da955",
   "metadata": {},
   "outputs": [],
   "source": [
    "import subprocess\n",
    "import sys\n",
    "from pathlib import Path"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5631f063-f1bd-49ec-9c5c-6b4f04230db8",
   "metadata": {},
   "source": [
    "We're going to import the GRASS GIS python API (`grass.script`) and the GRASS GIS Jupyter package (`grass.jupyter`). But first, we need to find the path to those packages using the `--config python_path` command. We use `subprocess.check_output` to find the path and `sys.path.append` to add it to the path."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ea26e84b-2ece-4996-b0d7-092a7e8dad6c",
   "metadata": {},
   "outputs": [],
   "source": [
    "sys.path.append(\n",
    "    subprocess.check_output([\"grass\", \"--config\", \"python_path\"], text=True, shell=False).strip()\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cced3fc7-5c8a-4679-9f6a-de7f6de4eadf",
   "metadata": {},
   "source": [
    "And now we can import the GRASS python packages!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b14d276f-f3b3-49bc-86d7-841b061440e5",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import the GRASS GIS packages we need.\n",
    "import grass.script as gs\n",
    "import grass.jupyter as gj"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8cf09cc7-77f1-4cd4-a73d-25b7999f37df",
   "metadata": {},
   "source": [
    "**We'll have to repeat the commands above every time we want to start a GRASS session in a notebook.**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "724657b8-6722-41f8-a1bf-4ba423fa2d0a",
   "metadata": {},
   "source": [
    "***\n",
    "## 3. Create a new project and start GRASS session"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2a3f9313-1b0e-4ddd-a0ef-f328acd8d1ee",
   "metadata": {},
   "outputs": [],
   "source": [
    "gs.create_project(\"NC_Sentinel\", epsg=3358, overwrite=True) # Warning! Overwrite=True will delete any all existing data in the project! Use carefully..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "10ba54ab-09c3-4949-9d8a-c0444f8ec965",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Start GRASS Session\n",
    "session = gj.init(\"./NC_Sentinel/PERMANENT\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "035cbf1a-d92e-498e-8d9f-83421aa4f0a3",
   "metadata": {},
   "source": [
    "We've launched GRASS GIS now! We can access GRASS GIS commands using the command line interface (with the `!` line magic):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "50235b02-016e-48ca-9801-87bef0a41043",
   "metadata": {},
   "outputs": [],
   "source": [
    "!g.version"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "07fb3bc6-69ca-4708-87ea-70aa9209785d",
   "metadata": {},
   "outputs": [],
   "source": [
    "!g.region -p"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e3e924c9-168d-4bd5-9b06-ecb8f9ee3743",
   "metadata": {},
   "outputs": [],
   "source": [
    "!r.univar --help"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b8a344c9-dea0-431b-9c16-467c9d46553f",
   "metadata": {},
   "source": [
    "***\n",
    "## 4. Importing data"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69ef5c20-cb1c-4790-b59a-d72e73b94abe",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "Download <a href=\"https://grass.osgeo.org/sampledata/north_carolina/nc_sentinel_utm17n.zip\">these Sentinel-2 images</a>. Put the unzipped download in this directory.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b67eeb78-b6fb-4204-9d39-2ef3392aa23f",
   "metadata": {},
   "source": [
    "Since we have several files to import, we can make a Python for-loop to import them all."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "312dffbc-4b97-41b0-9142-d38bf76413aa",
   "metadata": {},
   "outputs": [],
   "source": [
    "files = sorted(Path('./nc_sentinel_utm17n/S2A_MSIL2A_20220304T160151_N0400_R097_T17SQV_20220304T215812.SAFE/GRANULE/L2A_T17SQV_A034986_20220304T160221/IMG_DATA/R10m').glob('*.jp2'))\n",
    "files"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "547b1cc0-86c8-4c33-8b98-9e7e28800e8c",
   "metadata": {},
   "outputs": [],
   "source": [
    "for file in files[1:]:\n",
    "    name = str(file)[-11:-4]\n",
    "    print(\"importing \" + name)\n",
    "    gs.run_command(\"r.import\", input=file, output=name, resolution=\"value\", resolution_value=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5ab9ba15-267a-49c7-a7ce-ce184b931e1c",
   "metadata": {},
   "source": [
    "Each of these rasters corresponds to a Sentinel-2 band.\n",
    "\n",
    "| Raster | Band |\n",
    "|------------|-----------|\n",
    "| B02_10m | Blue |\n",
    "| B03_10m | Green |\n",
    "| B04_10m | Red |\n",
    "| B08_10m | NIR |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eb40c982-3db5-4a08-8671-88e6a7984bfa",
   "metadata": {},
   "source": [
    "Let's look at the available data in our location:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1c7ab525-5d2a-438e-aaff-5148152396b3",
   "metadata": {},
   "outputs": [],
   "source": [
    "!g.list type=raster,vector -m -t"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f0e0535a-9dc2-4f98-9022-85e8b4da3ab6",
   "metadata": {},
   "outputs": [],
   "source": [
    "!r.info map=B02_10m"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c11cad04-225a-4c27-bed1-4127677e0c66",
   "metadata": {},
   "outputs": [],
   "source": [
    "!g.region raster=B02_10m -p"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e9e8b74-7470-402e-bb2c-9a85f24bc16e",
   "metadata": {
    "tags": []
   },
   "source": [
    "***\n",
    "## 5. Data Visualization with `grass.jupyter`\n",
    "\n",
    "`grass.jupyter.Map()` creates and displays GRASS maps as PNG images. `gj.Map()` accepts any GRASS display module as a method by replacing the \".\" with \"\\_\" in the module name. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "43488aa9-320e-47bc-8a5c-6e42e278aa9a",
   "metadata": {},
   "outputs": [],
   "source": [
    "example = gj.Map()\n",
    "example.d_rast(map=\"B02_10m\") # d.rast map=B02_10m\n",
    "example.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59e489aa-17e0-4b5f-8d15-1638bc22ee52",
   "metadata": {},
   "outputs": [],
   "source": [
    "interactive_example = gj.InteractiveMap(width=800)\n",
    "interactive_example.add_raster(\"B02_10m\")\n",
    "interactive_example.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e3f8a3dc-7a91-4be8-a613-0cc36e769dab",
   "metadata": {},
   "outputs": [],
   "source": [
    "interactive_example.add_layer_control()\n",
    "interactive_example.show()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}