SWOT Oceanography GIS Tutorial

notebooks/GIS/SWOT_Oceanography_GIS_Access.ipynb

@@ -0,0 +1,273 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![](https://img.shields.io/badge/PO.DAAC-Contribution-%20?color=grey&labelColor=blue)\n",
+    "\n",
+    "> From the PO.DAAC Cookbook, to access the GitHub version of the notebook, follow [this link](https://github.com/podaac/tutorials/blob/master/notebooks/GIS/SWOT_Oceanography_GIS_Access.ipynb).\n",
+    "\n",
+    "# Accessing L2 SWOT Oceanography Collection with GIS\n",
+    "\n",
+    "Authored by Nicholas Tarpinian, *PO.DAAC* | Celia Y Ou, *PO.DAAC*\n",
+    "\n",
+    "Versions used: *GDAL 3.10.2, QGIS 3.42.0, ArcGIS Pro 3.3.1*\n",
+    "\n",
+    "## Summary\n",
+    "\n",
+    "The following workflow lets you access L2 SWOT Oceanography collection with various Geographical Information System (GIS) Desktop softwares by transforming [SWOT_L2_LR_SSH_2.0](https://podaac.jpl.nasa.gov/dataset/SWOT_L2_LR_SSH_2.0) datasets.\n",
+    "\n",
+    "------"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Requirements\n",
+    "\n",
+    "### 1. Compute environment\n",
+    "\n",
+    "- **Local compute environment** e.g. laptop, server: this tutorial can be run on your local machine in both Windows (ArcGIS Pro, QGIS, GDAL) and Mac (QGIS, GDAL) environment.\n",
+    "\n",
+    "### 2. Installing GDAL\n",
+    "\n",
+    "Install [GDAL](https://gdal.org/) (Geospatial Data Abstraction Library) and the GDAL Command Line Interface (CLI) onto your system. The GDAL CLI is a tool that lets your perform a variety of geospatial transformations and analysis with geospatial raster and vector data. GDAL can be configured to use in your local terminal or command prompt.\n",
+    "\n",
+    "### 3. Earthdata Login\n",
+    "\n",
+    "An Earthdata Login account is required to access data, as well as discover restricted data, from the NASA Earthdata system. Thus, to access NASA data, you need Earthdata Login. Please visit https://urs.earthdata.nasa.gov to register and manage your Earthdata Login account. This account is free to create and only takes a moment to set up.\n",
+    "\n",
+    "------"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Learning Objectives:\n",
+    "- Accessing L2 SWOT Oceanography dataset through earthaccess and downloading it locally.\n",
+    "- Utilizing GDAL (Geospatial Data Abstraction Library) to convert the collection NetCDF files to GeoTIFF.\n",
+    "- Utilizing geoprocessing tools with GIS Desktop Softwares; ArcGIS Pro and QGIS.\n",
+    "- Plotting and analyzing the collection within GIS desktop softwares.\n",
+    "\n",
+    "------"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Import libraries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "import earthaccess"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Authentication with earthaccess\n",
+    "\n",
+    "In this notebook, we will be calling the authentication in the cell below."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "auth = earthaccess.login()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Search and Download using `earthaccess` for L2 SWOT Oceanography\n",
+    "\n",
+    "Each dataset has it's own unique collection concept ID. For SWOT Level 2 KaRIn Low Rate Sea Surface Height Data Product it's shortname is SWOT_L2_LR_SSH_2.0. This collection has 4 different subcollections to choose from: [Basic](https://podaac.jpl.nasa.gov/dataset/SWOT_L2_LR_SSH_Basic_2.0), [Expert](https://podaac.jpl.nasa.gov/dataset/SWOT_L2_LR_SSH_Expert_2.0), [Windwave](https://podaac.jpl.nasa.gov/dataset/SWOT_L2_LR_SSH_WindWave_2.0), and [Unsmoothed](https://podaac.jpl.nasa.gov/dataset/SWOT_L2_LR_SSH_Unsmoothed_2.0)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = earthaccess.search_data(short_name = 'SWOT_L2_LR_SSH_2.0', \n",
+    "                                  temporal = ('2025-03-01 00:00:00', '2025-03-01 23:59:59'), # can also specify by time\n",
+    "                                  granule_name = '*Basic*')  # filter by files with \"Basic\" in file name."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "earthaccess.download(results, \"../datasets/data_downloads/SWOT_Oceanography_files\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## GDAL\n",
+    "\n",
+    "We will be utilizing GDAL to create our desired layer.\n",
+    "\n",
+    "Transformation of the netcdf file must take place first by selecting an attibute of choice and convert to a geotiff.\n",
+    "- Using [gdalinfo](https://gdal.org/en/stable/programs/gdalinfo.html) to investigate the variables available.\n",
+    "- First convert the layer to a [Virtual Raster Tile (VRT)](https://gdal.org/en/stable/drivers/raster/vrt.html) which is a GDAL Virtual Format with the selected variable (ssh_karin or Sea Surface Height (SSH))\n",
+    "    - This helps extract the variable and efficently handle the NetCDF file.\n",
+    "- Creating the VRT with [gdal_translate](https://gdal.org/en/stable/programs/gdal_translate.html)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdal_translate -of VRT NETCDF:\"input_SWOT_NetCDF_file/SWOT_L2_LR_SSH_Basic_029_129_20250301T002113_20250301T011241_PIC2_01.nc\":ssh_karin \"output_path/ssh_karin.vrt\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then use [gdalwarp](https://gdal.org/en/stable/programs/gdalwarp.html) with the vrt to create a geotiff as the output.\n",
+    "\n",
+    "Including -geoloc to utilize the geolocation arrays which reads per-pixel latitude/longitude values from the dataset to properly display."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdalwarp -geoloc \"input_SWOT_VRT_file/ssh_karin.vrt\" \"output_path/ssh_karin.tif\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The geotiff output file can now be plotted within QGIS.\n",
+    "\n",
+    "<nop/> <div style=\"width: 900px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_1.png)</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## QGIS\n",
+    "\n",
+    "QGIS offers GDAL as a suite of geoprocessing tools built into the desktop software.\n",
+    "\n",
+    "You can also utilize the gdalwarp tool within QGIS.\n",
+    "\n",
+    "Using the datasource manager to add the netcdf file to the map and selecting your desired variable.\n",
+    "\n",
+    "<nop/> <div style=\"width: 300px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_2.png)</div>\n",
+    "\n",
+    "<nop/> <div style=\"width: 500px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_3.png)</div>\n",
+    "\n",
+    "<nop/> <div style=\"width: 600px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_4.png)</div>\n",
+    "\n",
+    "Then using the gdalwarp tool within QGIS to transform and plot the dataset. \n",
+    "\n",
+    "<nop/> <div style=\"width: 350px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_5.png)</div>\n",
+    "\n",
+    "<nop/> <div style=\"width: 500px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_6.png)</div>\n",
+    "\n",
+    "<nop/> <div style=\"width: 400px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_7.png)</div>\n",
+    "\n",
+    "Next we can change the symbology to a more appropriate representation of the dataset.\n",
+    "\n",
+    "Right click the layer and select properties which provides access to the symbology.\n",
+    "\n",
+    "<nop/> <div style=\"width: 400px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_8.png)</div>\n",
+    "\n",
+    "For render type change from 'Singleband grey' to 'Singleband pseudocolor' which will open up the options to different color ramps to choose from.\n",
+    "\n",
+    "<nop/> <div style=\"width: 600px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_9.png)</div>\n",
+    "\n",
+    "Also select 'clip out of range values' so that the colors only change for the dataset itself.\n",
+    "\n",
+    "<nop/> <div style=\"width: 600px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_10.png)</div>\n",
+    "\n",
+    "<nop/> <div style=\"width: 900px;\">![](../../images/SWOT_LR_GIS_Images/QGIS_ocean_11.png)</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## ArcGIS Pro\n",
+    "\n",
+    "Esri's ArcGIS Pro offers a geoproccesing tool called 'Make Multidimensional Raster Layer'. \n",
+    "\n",
+    "This tool allows you to display a NetCDF file and create multiple layers based on the variables selected.\n",
+    "\n",
+    "<nop/> <div style=\"width: 400px;\">![](../../images/SWOT_LR_GIS_Images/ArcGIS_ocean_1.png)</div>\n",
+    "\n",
+    "<nop/> <div style=\"width: 400px;\">![](../../images/SWOT_LR_GIS_Images/ArcGIS_ocean_2-2.png)</div>\n",
+    "\n",
+    "<nop/> <div style=\"width: 900px;\">![](../../images/SWOT_LR_GIS_Images/ArcGIS_ocean_3.png)</div>\n",
+    "\n",
+    "Next to calculate the values of the dataset, we will create a layer with the 'Summary Statistics' tool.\n",
+    "\n",
+    "Select the layer, then under the 'Multidimensional' tab is where you can select a variety of statisics to calculate.\n",
+    "\n",
+    "<nop/> <div style=\"width: 900px;\">![](../../images/SWOT_LR_GIS_Images/ArcGIS_ocean_4.png)</div>\n",
+    "\n",
+    "<nop/> <div style=\"width: 900px;\">![](../../images/SWOT_LR_GIS_Images/ArcGIS_ocean_5.png)</div>\n",
+    "\n",
+    "You can also export the layer to a geotiff after the 'Make Multidimensional Raster Layer' step, this will also provide the values of the collection.\n",
+    "\n",
+    "Right click the layer and go to 'Data' then 'Export Raster'. You will have the option to export as a GeoTIFF, Pixel Type, etc. \n",
+    "\n",
+    "<nop/> <div style=\"width: 400px;\">![](../../images/SWOT_LR_GIS_Images/ArcGIS_ocean_6.png)</div>\n",
+    "\n",
+    "<nop/> <div style=\"width: 300px;\">![](../../images/SWOT_LR_GIS_Images/ArcGIS_ocean_7.png)</div>\n",
+    "\n",
+    "<nop/> <div style=\"width: 900px;\">![](../../images/SWOT_LR_GIS_Images/ArcGIS_ocean_8.png)</div>"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Geospatial_310",
+   "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.10.14"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}