Accessing data example

docs/source/access/accessing_data.ipynb

@@ -0,0 +1,142 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Accessing Data from the MAAP"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In this example, we demonstrate how to access data from the MAAP using the `getLocalPath()` function. At this time, this procedure is the same for user-contributed data."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We import the `os` module, import the `MAAP` package, and create a new MAAP class."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# import os module\n",
+    "import os\n",
+    "\n",
+    "# import the MAAP package\n",
+    "from maap.maap import MAAP\n",
+    "\n",
+    "# create MAAP class\n",
+    "maap = MAAP()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For this example, the `site_name` additional attribute is used to search for granules that have been tagged as part of the *Mondah Forest Gabon* research site. For more information about searching for granules in MAAP, please see https://maap-project.readthedocs.io/en/latest/search/granules.html."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# assign Mondah Forest Gabon site name\n",
+    "SITENAME = 'Mondah Forest Gabon'\n",
+    "\n",
+    "# search for granules with site name\n",
+    "results = maap.searchGranule(site_name=SITENAME)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We assign a variable (in this case, `scene`) to the first result of our search from the cell above."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# grab first result\n",
+    "scene = results[0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A data directory is then set, and if the directory does not already exist, it is created. The scene from our search is then downloaded into the file system in this directory. Here, the function `getLocalPath()` is accessing the data stored on the MAAP's Simple Storage Service (S3) bucket and downloading it directly to the path provided."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'./data/Mondah_AGB_50m.tif'"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# set data directory\n",
+    "dataDir = './data'\n",
+    "\n",
+    "# check if directory exists -> if directory doesn't exist, directory is created\n",
+    "if not os.path.exists(dataDir):\n",
+    "    os.mkdir(dataDir)\n",
+    "\n",
+    "# download scene from search into data directory\n",
+    "data = scene.getLocalPath(dataDir)\n",
+    "data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we can see that the data directory has been created and the 'Mondah_AGB_50m.tif' scene is downloaded into the directory. The downloaded file remains in the data directory until the user deletes it."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "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.7.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

docs/source/index.rst

@@ -22,6 +22,13 @@ Welcome to maap-docs's documentation!
   visualization/using_pycmc.ipynb
 
 
+.. toctree::
+  :maxdepth: 2
+  :caption: Access:
+
+  access/accessing_data.ipynb
+
+
 .. toctree::
   :maxdepth: 2
   :caption: User Data: