Cryo 84

notebooks/SMAP/01_download_smap_data.ipynb

@@ -0,0 +1,244 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "e86eaecf-a612-4dbb-8bdc-5b5dfddf65b9",
+   "metadata": {},
+   "source": [
+    "<center>\n",
+    "<img src='./img/nsidc_logo.png'/>\n",
+    "\n",
+    "# **1.0 Access SMAP data with Python**\n",
+    "\n",
+    "</center>\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4101ae06-3984-435c-abcc-f6346d15069b",
+   "metadata": {},
+   "source": [
+    "## **1. Tutorial Introduction/Overview**\n",
+    "\n",
+    "We will use the `earthaccess` library to authenticate with our Earthdata Login credentials and to search for and bulk download SMAP data. For this tutorial we wil use SPL3SMP version 008 as an example, but the same method can be applied to any other SMAP data sets archived at NSIDC. \n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dd6c0128-efe4-4fab-8721-55fc366e3c7e",
+   "metadata": {},
+   "source": [
+    "### **Credits**\n",
+    "\n",
+    "This tutorial is based on the notebooks originally provided to NSIDC by Adam Purdy. Jennifer Roebuck of NSIDC updated the tutorials to include the latest version of SMAP data and use `earthaccess` for authentication, seatching for and downloading the data in order to incorporate it into the NSIDC-Data-Tutorials repo. \n",
+    "\n",
+    "For questions regarding the notebook, or to report problems, please create a new issue in the [NSIDC-Data-Tutorials repo](https://github.com/nsidc/NSIDC-Data-Tutorials/issues)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a57c664e-76f9-416e-ae03-75dce51b3cb7",
+   "metadata": {},
+   "source": [
+    "### **Learning Goals**\n",
+    "\n",
+    "After completing this notebook you will be able to use the `earthaccess` library to:\n",
+    "1. Authenticate with your Earthdata Login credentials.\n",
+    "2. Search for SMAP data.\n",
+    "3. Bulk download SMAP data."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "015703a9-f02a-42f4-8ff0-3b002bf4f2f5",
+   "metadata": {},
+   "source": [
+    "### **Prerequisites**\n",
+    "\n",
+    "1. An Earthdata Login is required for data access. If you don't have one, you can register for one [here](https://urs.earthdata.nasa.gov/).\n",
+    "2. A .netrc file, that contains your Earthdata Login credentials, in your home directory. The current recommended practice for authentication is to create a .netrc file in your home directory following these [instructions](https://nsidc.org/data/user-resources/help-center/programmatic-data-access-guide).\n",
+    "3. The nsidc-tutorials environment is set up and activated. This [README](https://github.com/nsidc/NSIDC-Data-Tutorials/blob/main/README.md) has setup instructions.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c45f3276-1172-4bfb-8389-e9d3cbbe88f4",
+   "metadata": {},
+   "source": [
+    "### **Time requirement**\n",
+    "\n",
+    "Allow 5 to 10 minutes to complete this tutorial."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "53b77eb5-d5ed-4ddd-8fb1-6c69618d7852",
+   "metadata": {},
+   "source": [
+    "## **2. Tutorial steps**"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7820a737-33f0-4470-b9a4-03c5c4f0354c",
+   "metadata": {},
+   "source": [
+    "### **Import libraries**\n",
+    "We need just two libraries, `os` for creating the directory to store the downloaded data in and `earthaccess` to authenticate, search for and download the data. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "059690ab-7dff-45c9-816a-6060a191f550",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#Import libraries \n",
+    "\n",
+    "import os # needed to create the directory to store the downloaded data\n",
+    "import earthaccess # used for authentication and searching for downloading the data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1966ffa6-a5f2-4520-a8dc-f37678a2cf7a",
+   "metadata": {},
+   "source": [
+    "### **Authenticate**\n",
+    "\n",
+    "The first step is to authenticate using our Earthdata Login credentials. The `login` method will automatically search for these credentials as environment variables or in a `.netrc` files, and if those aren't available it will prompt us to enter our username and password. We use a `.netrc` strategy. A `.netrc` file is a text file located in our home directory that contains login information for remote machines. If we don't have a `.netrc` file, `login` can create one for us:\n",
+    "```\n",
+    "earthaccess.login(strategy='interactive',persist=True)\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d47aa955-3d91-4418-85f9-5772f400f712",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "auth = earthaccess.login()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "95e2532d-219b-4b9d-b5b9-b43c95b1aa7d",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "### **Search for SPL3SMP data using spatial and temporal filters**\n",
+    "We will use the `search_data` method from the `earthaccess` library and the following variabes to search for granules within the SPL3SMP data set:\n",
+    "* `short_name` - this is the data set ID e.g. SPL3SMP. It can be found in the data set title on the data set landing page.\n",
+    "* `version` - data set version number, also included in the data set title.\n",
+    "* `cloud_hosted` - NSIDC is in the process of migrating data sets to the cloud. The data set we are interested is currently still archived on-premises so we will set this to False.\n",
+    "* `temporal` - set a temporal filter by specifying a start and end date in the format YYYY-MM-DD. In this tutorial we will look for data for the month of March 2017.\n",
+    "\n",
+    "It will output the number of granules that meet the search criteria."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d66e54ff-71dc-422c-9e8a-5b154fa0dbf7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#Search for SPL3SMP files \n",
+    "\n",
+    "results = earthaccess.search_data(\n",
+    "    short_name = 'SPL3SMP',\n",
+    "    version = '008',\n",
+    "    cloud_hosted = False,\n",
+    "    temporal = ('2017-03-01','2017-03-31')\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c7307f44-93cd-49b0-aa11-ae85aca29722",
+   "metadata": {},
+   "source": [
+    "### **Download the data** \n",
+    "Now that we have found the granules that meet our search criteria, we can download them using the `download` method from `earthaccess`. First, we will create a new directory to save the files in."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "80d938ed-4fe6-4bff-b71a-cce39e7a9bd4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "this_dir = os.getcwd()\n",
+    "DATA_DIR = os.path.join(this_dir, 'data/L3_SM_P')\n",
+    "\n",
+    "if not os.path.exists(DATA_DIR):\n",
+    "    os.makedirs(DATA_DIR)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0c0fc789-ac80-474a-9928-8d9d4564ceac",
+   "metadata": {},
+   "source": [
+    "Now we will download the SPL3SMP data for March 2017."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "467ece65-932a-46e1-9f4c-1b47b628266b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "smap_files = earthaccess.download(results,DATA_DIR)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "910b2ef6-3e14-475e-b689-77bda4c1814e",
+   "metadata": {},
+   "source": [
+    "## **3. Learning outcomes recap (optional)**\n",
+    "\n",
+    "1. Authenticate with your Earthdata Login credentials.\n",
+    "2. Search for SMAP data.\n",
+    "3. Bulk download SMAP data.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3b6b4172-7ba8-451d-9051-912aea174adf",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "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.9.15"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}