2 - EE 101.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "# Earth Engine 101\n",
    "This workbook is an introdution to Earth Engine analysis in an IPython Notebook, using the Python API. The content is similar to what is covered in the Introduction to the Earth Engine API workshop using the Earth Engine Javascript \"Playground\". "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "Let's get started by importing a few moduled used in this tutorial."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "from IPython.display import Image"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "## Hello, World\n",
    "To get used to using IPython Notebooks, let's print some simple output back to the notebook. Click on the box below, and then press the play (run) button from the toolbar above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "print(\"Hello, world!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "That works, but we can also first store the content in a variable, and then print out the variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "string = \"Hello, world!\"\n",
    "print(string)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "## Hello, Images\n",
    "Let's work with something more interesting... a dataset provided by Earth Engine.\n",
    "\n",
    "Assuming that this server has been setup with access to the Earth Engine Python API, we should be able to import and initialise the Earth Engine Python module (named 'ee'). If the module loads successfully, nothing will be returned when you run the following code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "import ee\n",
    "ee.Initialize()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "Next, let's locate a dataset to display. Start by going to the Earth Engine Public Data Catalog (https://earthengine.google.org/#index). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "Image('http://www.google.com/earth/outreach/images/tutorials_eeintro_05_data_catalog.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "Type in the term **SRTM** in the search box, click the search button, and then select the dataset **SRTM Digital Elevation Data Version 4** from the list of results. This will bring up a data description page for the [SRTM Digital Elevation Data 30m](https://earthengine.google.org/#detail/CGIAR%2FSRTM90_V4) dataset. The data description page provide a short description of the dataset and links to the data provider, but the key piece of information that we need for working with the dataset in Earth Engine is the **Image ID**, which for this dataset is **CGIAR/SRTM90_V4**. Let's use the Image ID to store a reference to this image dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "srtm = ee.Image(\"CGIAR/SRTM90_V4\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "And now, we can print out information about the dataset, using the .getInfo() method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "info = srtm.getInfo()\n",
    "print(info)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "What is returned by the .getInfo() command is a Python dictionary. If needed, we could parse out this information and make use of it in our analysis."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "## Add an Image to the Map\n",
    "\n",
    "IPython Notebooks can be used to display an image, using the Image module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "from IPython.display import Image\n",
    "\n",
    "Image(url=srtm.getThumbUrl())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "Ok, we can see the outlines of the continents, but there is not a lot of contrast between different elevation areas. So let's improve upon that, but adding some visualization parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "Image(url=srtm.getThumbUrl({'min':0, 'max':3000}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "By default, the **.getThumbUrl()** method returns the entire extent of the image, which in this case is global. We can also specify a region, to show a smaller area."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "point = ee.Geometry.Point(-122.0918, 37.422)\n",
    "region_bay_area = point.buffer(50000).bounds().getInfo()['coordinates']\n",
    "Image(url=srtm.getThumbUrl({'min':0, 'max':1000, 'region':region_bay_area}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "## Load and Filter an Image Collection\n",
    "So far we have been working with a single image, but there are also interesting datasets that are distributed as a series of images (such as images collected by satellite). Head back to the [Earth Engine Public Data Catalog](https://earthengine.google.org/#index), search for **landsat 8 toa**, and load up the data description page for the **USGS Landsat 8 TOA Reflectance (Orthorectified)** dataset. The ID for this Image Collection is **LANDSAT/LC8_L1T_TOA**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "# Create a reference to the image collection\n",
    "l8 = ee.ImageCollection('LANDSAT/LC8_L1T_TOA')\n",
    "# Filter the collection down to a two week period\n",
    "filtered = l8.filterDate('2013-05-01', '2013-05-15');\n",
    "# Use the mosaic reducer, to select the most recent pixel in areas of overlap\n",
    "l8_image = filtered.mosaic()\n",
    "# Define a region roughly covering California\n",
    "point = ee.Geometry.Point(-118, 37)\n",
    "region_california = point.buffer(500000).bounds().getInfo()['coordinates']\n",
    "# And finally display the image.\n",
    "Image(url=l8_image.getThumbUrl({'region':region_california}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "## Playing with Image Bands\n",
    "Using the default image visualization parameters, that doesn't look like much. So we add some visualization data, to display a true color image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "Image(url=l8_image.getThumbUrl({\n",
    "    'region':region_california,\n",
    "    'bands':'B4,B3,B2',\n",
    "    'min':0,\n",
    "    'max':0.3\n",
    "}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "And by changing the bands displayed, we can also display a *false color* image."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "Image(url=l8_image.getThumbUrl({\n",
    "    'region':region_california,\n",
    "    'bands':'B5,B4,B3',\n",
    "    'min':0,\n",
    "    'max':0.3\n",
    "}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "## Play with Reducing Image Collections\n",
    "Next expand the date range to cover an entire year, so that there are many overlapping images. We will continue to use the **.mosaic()** reducer, which retains the last (most recent) pixels in areas of image overlap. Clouds are readily apparent."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "filtered = l8.filterDate('2013-01-01', '2014-01-01')\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "### ImageCollection.mosaic Reducer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "l8_image = filtered.mosaic()\n",
    "Image(url=l8_image.getThumbUrl({\n",
    "    'region':region_california,\n",
    "    'bands':'B4,B3,B2',\n",
    "    'min':0,\n",
    "    'max':0.3\n",
    "}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "### ImageCollection.median Reducer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "l8_image = filtered.median()\n",
    "Image(url=l8_image.getThumbUrl({\n",
    "    'region':region_california,\n",
    "    'bands':'B4,B3,B2',\n",
    "    'min':0,\n",
    "    'max':0.3\n",
    "}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "### ImageCollection.min Reducer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "l8_image = filtered.min()\n",
    "Image(url=l8_image.getThumbUrl({\n",
    "    'region':region_california,\n",
    "    'bands':'B4,B3,B2',\n",
    "    'min':0,\n",
    "    'max':0.3\n",
    "}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "deletable": true,
    "editable": true
   },
   "source": [
    "### ImageCollection.max Reducer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": [
    "l8_image = filtered.max()\n",
    "Image(url=l8_image.getThumbUrl({\n",
    "    'region':region_california,\n",
    "    'bands':'B4,B3,B2',\n",
    "    'min':0,\n",
    "    'max':0.3\n",
    "}))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "deletable": true,
    "editable": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}