Tutorial for Xarray's Rasterio backend

_toc.yml

@@ -53,6 +53,7 @@ parts:
       - file: intermediate/hvplot
       - file: intermediate/datastructures-intermediate.ipynb
       - file: intermediate/BiologyDataset.ipynb
+      - file: intermediate/hierarchical_zarr_store.ipynb
       - file: intermediate/remote_data/index
         sections:
           - file: intermediate/remote_data/cmip6-cloud.ipynb
@@ -86,6 +87,7 @@ parts:
         sections:
           - file: advanced/backends/1.Backend_without_Lazy_Loading.ipynb
           - file: advanced/backends/2.Backend_with_Lazy_Loading.ipynb
+          - file: advanced/backends/rasterio_backend.ipynb
       - file: advanced/accessors/accessors.md
         sections:
           - file: advanced/accessors/01_accessor_examples.ipynb

advanced/backends/rasterio_backend.ipynb

@@ -0,0 +1,270 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Xarray's Rasterio backend\n",
+    "\n",
+    "In this lesson, we will learn how to use xarray's rasterio backend engine to open GeoTIFF rasters. By the end of the lesson, we will be able to:\n",
+    "\n",
+    ":::{admonition} Learning Goals\n",
+    "- Learn about the GeoTIFF format\n",
+    "- Lean about xarray's \"rasterio\" backend and the \"rioxarray\" accessor\n",
+    "- Learn how to read, write and plot GeoTIFF files with xarray\n",
+    "- Explore how to perform reprojection operations on rasters\n",
+    ":::\n",
+    "\n",
+    "## What are GeoTIFFs?\n",
+    "\n",
+    "GeoTIFFS (Geographic Tagged Image File Format (GeoTIFF)) are an image format based on the TIFF (Tagged Image File Format), that contain georeferencing information embedded within a raster image. Rasters in GeoTIFFs are made up of gridded pixels (or arrays) that map to a geographic region. The pixels values represent a characteristic (variable) for the geographic region it maps to.\n",
+    "\n",
+    "![Raster_Image](https://docs.qgis.org/3.44/en/_images/raster_dataset.png)\n",
+    "\n",
+    "## Rasterio and Rioxarray Backends\n",
+    "\n",
+    "[Rasterio](https://rasterio.readthedocs.io/en/stable/intro.html) is a geospatial raster library that expresses GDAL ([Geospatial Data Abstraction Library](http://gdal.org)) data model with a Python API and CLI. [Rioxarray](https://corteva.github.io/rioxarray/stable/readme.html) is a wrapper around the rasterio library, that also extends the xarray api with the *rio* accessor. When you open a GeoTIFF file with the \"rasterio\" engine it returns the data as an xarray object with access to methods from the *rio* accessor.\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "## Reading a GeoTIFF\n",
+    "\n",
+    "Xarray's \"rasterio\" backend supports reading GeoTIFFs.\n",
+    "\n",
+    "Lets read a GeoTIFF file as an `xr.DataArray` by selecting `engine='rasterio'`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import xarray as xr"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rds = xr.open_dataarray(\"../../../xarray-data/RGB.byte.tif\", engine=\"rasterio\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {},
+   "source": [
+    ":::{note} We can also read GeoTIFFs with `rioxarray` a wrapper around the `rasterio` library.\n",
+    "Both of these options return an `xr.DataArray`\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import rioxarray\n",
+    "\n",
+    "rioxarray.open_rasterio(\"../../../xarray-data/RGB.byte.tif\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "## Raster bands\n",
+    "\n",
+    "GeoTIFFS can have multiple bands each representing a range or band in the electromagnetic spectrum. Arrays stored within bands in xarray are data variables and `DataArray`'s objects in the the Xarray Data Model.\n",
+    "\n",
+    "Lets try getting the total number of bands for this GeoTIFF. Since `rioxarray` extends xarray with the *rio* accessor we can this accessor be able use many of the builtin `rasterio` methods."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rds.rio.count"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8",
+   "metadata": {},
+   "source": [
+    "## Selection by bands\n",
+    "We can also select by bands. Since there are 3 bands in this dataset we can return raster array for the first band of this `xr.DataArray` by with indexing\n",
+    "\n",
+    "Lets get the first band of this dataset and try plotting it"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rds[0].plot(cmap=\"pink\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "10",
+   "metadata": {},
+   "source": [
+    "## Georeferencing\n",
+    "With our *rio* accessor we can get the spatial bounds for out dataset and affine transformations"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "11",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rds.rio.bounds()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "12",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rds.rio.transform()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "13",
+   "metadata": {},
+   "source": [
+    ":::{note}\n",
+    "The affine transformation matrix maps pixel locations in (col, row) coordinates to (x, y) spatial positions. The product of this matrix and (0, 0), the column and row coordinates of the upper left corner of the dataset, is the spatial position of the upper left corner.\n",
+    ":"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "14",
+   "metadata": {},
+   "source": [
+    "### Coordinate Reference System (CRS)\n",
+    "We can also get the Coordinate Reference System for raster array and reproject them."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "15",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rds.rio.crs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "16",
+   "metadata": {},
+   "source": [
+    "### Reprojection\n",
+    "We can also reproject our raster from one CRS to another.\n",
+    "\n",
+    "Lets reproject our raster from \"EPSG:6326\" to \"EPSG:32612\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "17",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rds_reproj = rds.rio.reproject(\"EPSG:32612\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "18",
+   "metadata": {},
+   "source": [
+    ":::{note}\n",
+    "We have to update our CRS system to the new projection with `rio.write_crs`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "19",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rds_reproj.rio.write_crs(\"EPSG:32612\", inplace=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "20",
+   "metadata": {},
+   "source": [
+    "## Exercise"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "21",
+   "metadata": {},
+   "source": [
+    "::::{admonition} Exercise\n",
+    ":class: tip\n",
+    "\n",
+    "Can you reproject and update the CRS of second band of data to 'ESPG:3857' and plot your results?\n",
+    "\n",
+    ":::{admonition} Solution\n",
+    ":class: dropdown\n",
+    "\n",
+    "```python\n",
+    "rds[1].rio.reproject(\"EPSG:3857\").rio.write_crs(\"EPSG:3857\", inplace=True).plot()\n",
+    "```\n",
+    ":::\n",
+    "::::\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}