diff --git a/people-and-planet-ai/README.md b/people-and-planet-ai/README.md
index d8faf5a579a..fb77962fda6 100644
--- a/people-and-planet-ai/README.md
+++ b/people-and-planet-ai/README.md
@@ -40,3 +40,20 @@ location data.
[Dataflow]: https://cloud.google.com/dataflow
[Keras]: https://keras.io
[Vertex AI]: https://cloud.google.com/vertex-ai
+
+## 🏭 [Coal Plant Predictions -- _geospatial-classification_](geospatial-classification)
+
+[](https://colab.research.google.com/github/GoogleCloudPlatform/python-docs-samples/blob/main/people-and-planet-ai/geospatial-classification/README.ipynb)
+
+This model uses satellite data to predict if a coal plant is turned on and producing carbon emissions. The satellite data comes from [Google Earth Engine.](https://earthengine.google.com/)
+
+* **Model**: 1D Fully Convolutional Network in [TensorFlow]
+* **Creating datasets**: [Sentinel-2] satellite data from [Earth Engine]
+* **Training the model**: [TensorFlow] in [Vertex AI]
+* **Getting predictions**: [TensorFlow] in [Cloud Run]
+
+[Cloud Run]: https://cloud.google.com/run
+[Sentinel-2]: https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2
+[Earth Engine]: https://earthengine.google.com/
+[TensorFlow]: https://www.tensorflow.org/
+[Vertex AI]: https://cloud.google.com/vertex-ai
diff --git a/people-and-planet-ai/geospatial-classification/README.ipynb b/people-and-planet-ai/geospatial-classification/README.ipynb
new file mode 100644
index 00000000000..fd11b264a27
--- /dev/null
+++ b/people-and-planet-ai/geospatial-classification/README.ipynb
@@ -0,0 +1,1437 @@
+{
+ "cells": [
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "77c0f36a",
+ "metadata": {
+ "id": "77c0f36a",
+ "cellView": "form"
+ },
+ "outputs": [],
+ "source": [
+ "#@title ###### Licensed to the Apache Software Foundation (ASF), Version 2.0 (the \"License\")\n",
+ "\n",
+ "# Licensed to the Apache Software Foundation (ASF) under one\n",
+ "# or more contributor license agreements. See the NOTICE file\n",
+ "# distributed with this work for additional information\n",
+ "# regarding copyright ownership. The ASF licenses this file\n",
+ "# to you under the Apache License, Version 2.0 (the\n",
+ "# \"License\"); you may not use this file except in compliance\n",
+ "# with the License. You may obtain a copy of the License at\n",
+ "#\n",
+ "# http://www.apache.org/licenses/LICENSE-2.0\n",
+ "#\n",
+ "# Unless required by applicable law or agreed to in writing,\n",
+ "# software distributed under the License is distributed on an\n",
+ "# \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n",
+ "# KIND, either express or implied. See the License for the\n",
+ "# specific language governing permissions and limitations\n",
+ "# under the License."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3683a5f8",
+ "metadata": {
+ "id": "3683a5f8"
+ },
+ "source": [
+ "# 🏭 Coal Plant ON/OFF: Predictions\n",
+ "\n",
+ "* **Time estimate**: 1 hour\n",
+ "* **Cost estimate**: Around $**1**.00 USD\n",
+ "\n",
+ "This is an **interactive** notebook that contains **all** of the **code** necessary to train an ML model from satellite images for geospatial classification of whether a coal plant is on/off. \n",
+ "\n",
+ "This is a first step **introductory example** of how these **satellite images** can be used to detect **carbon pollution** from power plants.\n",
+ "\n",
+ "--------------------------------------------\n",
+ "\n",
+ "\n",
+ "💚 This is one of many **machine learning how-to samples** inspired from **real climate solutions** aired on the [People and Planet AI 🎥 series](https://www.youtube.com/playlist?list=PLIivdWyY5sqI-llB35Dcb187ZG155Rs_7)."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "922968ad",
+ "metadata": {
+ "id": "922968ad"
+ },
+ "source": [
+ "# 🚏 Overview\n",
+ "\n",
+ "This notebook leverages geospatial data from [Google Earth Engine](https://earthengine.google.com/), and labeled data provided by the organization [Climate TRACE](https://www.climatetrace.org/). By combining these two data sources, you'll build and train a model that predicts whether or not a power plant is turned on and producing emissions."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "8f15adff",
+ "metadata": {
+ "id": "8f15adff"
+ },
+ "source": [
+ "### 🛰️ Data _(inputs)_\n",
+ "\n",
+ "The data in this example consists of images from a satellite called [Sentinel-2](https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2#description), a wide-swath, **high-resolution**, multi-spectral imaging mission for land monitoring studies.\n",
+ "\n",
+ "When working with satellite data, each input image has the **dimensions** `[width, height, bands]`. **Bands** are measurements from specific satellite instruments for different ranges of the **electromagnetic spectrum**. For example, Sentinel-2 contains [🌈 13 spectral bands](https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S2#bands). If you're familiar with image classification problems, you can think of the bands as similar to an image's RGB (red, green, blue) channels. However, when working with satellite data we generally have **more than just 3** channels.\n",
+ "\n",
+ "\n",
+ "\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "d15be296",
+ "metadata": {
+ "id": "d15be296"
+ },
+ "source": [
+ "### 🏷️ Labels _(outputs)_\n",
+ "\n",
+ "For each patch of pixels (an image of a power plant) that we give to the model, it performs **binary classification**, which indicates whether the power plant is on or off.\n",
+ "\n",
+ "In this example, the **output** is a single number between *0 (Off) and 1 (On)*, representing the **probability** of that power plant being ON."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4dce50bc",
+ "metadata": {
+ "id": "4dce50bc"
+ },
+ "source": [
+ "### Model _(function)_\n",
+ "\n",
+ "**TL;DR**\n",
+ "*The model will receive a patch of pixels, in the center is the power plant tower. We take 16 pixels as padding creating a 33x33 patch. The model returns a classification of ON/OFF*\n",
+ "\n",
+ "In this example, we have a CSV file of labels. Each row in this file represents a power plant at a specific lat/lon and timestamp. At training time we'll prepare a dataset where each input image is a single pixel that we have a label for. We will then add padding around that image. These padded pixels will not get predictions, but will help our model to make better predictions for the center point that we have a label for.\n",
+ "\n",
+ "For example, with a padding of 16, each 1 pixel input point would become a 33x33 image after the padding is added.\n",
+ "\n",
+ "\n",
+ "\n",
+ "The model in this sample is trained for image patches where a power plant is located in the center, and the dimensions must be 33x33 pixels where each pixel has a constant number of bands."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "3547aec6",
+ "metadata": {
+ "id": "3547aec6"
+ },
+ "source": [
+ "## 🚴♀️ Steps summary\n",
+ "\n",
+ "Here's a quick summary of what you’ll go through:\n",
+ "\n",
+ "1. **Get the training data** _(~15 minutes to complete, no cost for using Earth Engine)_:\n",
+ " Extract satellite images from [Earth Engine](https://earthengine.google.com/), combine it with the data that was labeled and contains lat/long coordinates from [Climate TRACE](https://climatetrace.org) in a CSV, and export to\n",
+ " [Cloud Storage](https://cloud.google.com/storage).\n",
+ "\n",
+ "\n",
+ "2. **Run a custom training job** _(~15 minutes to complete, [costs ~ $1](https://cloud.google.com/vertex-ai/pricing#custom-trained_models))_:\n",
+ " Using [Tensorflow](https://www.tensorflow.org/) on [Vertex AI Training](https://cloud.google.com/vertex-ai/docs/training/custom-training) using a [pre-built training container](https://cloud.google.com/vertex-ai/docs/training/pre-built-containers).\n",
+ "\n",
+ "\n",
+ "3. **Deploy a web service to host the trained model** _(~7 minutes to complete, [costs a few cents to build the image](https://cloud.google.com/build/pricing), and [deployment cost covered by free tier](https://cloud.google.com/run/pricing))_:\n",
+ " On\n",
+ " [Cloud Run](https://cloud.google.com/run)\n",
+ " and get predictions using the model.\n",
+ "\n",
+ "\n",
+ "4. **Get Predictions** _(a few seconds per prediction, [costs covered by free tier](https://cloud.google.com/run/pricing))_:\n",
+ " Use the web service to get predictions for new data.\n",
+ "\n",
+ "\n",
+ "5. **Visualize predictions** _(~5 minutes to complete)_ :\n",
+ " Visualize the predictions on a map.\n",
+ "\n",
+ "\n",
+ "6. (Optional) **Delete the project** to avoid ongoing costs."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "46b21577",
+ "metadata": {
+ "id": "46b21577"
+ },
+ "source": [
+ "## 🙈 Using this interactive notebook\n",
+ "\n",
+ "Click the **run** icons ▶️ of each section within this notebook. \n",
+ "\n",
+ "This notebook code lets you train and deploy an ML model from end-to-end. When you run a code cell, the code runs in the notebook's runtime, so you're not making any changes to your personal computer.\n",
+ "\n",
+ "> 🛎️ **To avoid any errors**, wait for each section to finish in their order before clicking the next “run” icon.\n",
+ "\n",
+ "This sample must be connected to a **Google Cloud project**, but nothing else is needed other than your Google Cloud project.\n",
+ "You can use an existing project and the cost will be around **$1.00**. Alternatively, you can create a new Cloud project with cloud credits for free."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "f0033a40",
+ "metadata": {
+ "id": "f0033a40"
+ },
+ "source": [
+ "## ✨ Before you begin, you need to…\n",
+ "\n",
+ "1. Decide on creating a new\n",
+ " [free project](https://cloud.google.com/free/docs/gcp-free-tier)\n",
+ " _(recommended)_ or using an existing one.\n",
+ " Then **copy the project ID** and paste it in the `google_cloud_project` field in the \"Entering project details” section below.\n",
+ "\n",
+ " > 💡 If you _don't plan to keep the resources_ that you create via this sample, we recommend creating a new project instead of selecting an existing project.\n",
+ " > After you finish these steps, you can delete the project, removing all the resources associated in bulk.\n",
+ "\n",
+ "1. Make sure that **billing is enabled** for your Google Cloud project,\n",
+ " [_click here_](https://cloud.google.com/billing/docs/how-to/modify-project)\n",
+ " to learn how to confirm that billing is enabled.\n",
+ "\n",
+ "1. Have an **Earth Engine** account (it's FREE) or create a new one.\n",
+ " To create an account, fill out the [registration form here.](https://signup.earthengine.google.com/#!/). Please note this can take from 0-24 hours...but it's worth it! Come back to this sample after you have this."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "156ab72c",
+ "metadata": {
+ "id": "156ab72c"
+ },
+ "source": [
+ "### ⛏️ Preparing the project environment\n",
+ "\n",
+ "Click the run ▶️ icons in order for the cells to download and install the necessary code, libraries, and resources for this solution.\n",
+ "\n",
+ "> 💡 You can _optionally_ view the entire\n",
+ "> [code in GitHub](https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/people-and-planet-ai/geospatial-classification)."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "fa34fdd8",
+ "metadata": {
+ "id": "fa34fdd8"
+ },
+ "source": [
+ "### ↘️ Get the code"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "c2848f6d",
+ "metadata": {
+ "id": "c2848f6d"
+ },
+ "outputs": [],
+ "source": [
+ "# Get the sample source code.\n",
+ "\n",
+ "!git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git ~/python-docs-samples\n",
+ "%cd ~/python-docs-samples/people-and-planet-ai/geospatial-classification"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "source": [
+ "You will need to restart the runtime (Runtime -> Restart Runtime) after executing this cell."
+ ],
+ "metadata": {
+ "id": "0-SFNGO63asJ"
+ },
+ "id": "0-SFNGO63asJ"
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "bb8c6ede",
+ "metadata": {
+ "id": "bb8c6ede"
+ },
+ "outputs": [],
+ "source": [
+ "!pip install -r requirements.txt -c constraints.txt"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "980b439f-03bb-427f-ae61-4d6d5f066d15",
+ "metadata": {
+ "id": "980b439f-03bb-427f-ae61-4d6d5f066d15"
+ },
+ "source": [
+ "### ✏️ Enter your Cloud project's details. Ensure you provide a regional bucket!"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "246702e7",
+ "metadata": {
+ "id": "246702e7",
+ "cellView": "form"
+ },
+ "outputs": [],
+ "source": [
+ "#@title My Google Cloud resources\n",
+ "project = '' #@param {type:\"string\"}\n",
+ "bucket = '' #@param {type:\"string\"}\n",
+ "region = 'us-central1' #@param {type:\"string\"}\n",
+ "\n",
+ "# Validate the inputs.\n",
+ "if not project:\n",
+ " raise ValueError(f\"Please provide a value for 'project'\")\n",
+ "if not bucket:\n",
+ " raise ValueError(f\"Please provide a value for 'bucket'\")\n",
+ "if not region:\n",
+ " raise ValueError(f\"Please provide a value for 'region'\")\n",
+ "\n",
+ "# Authenticate\n",
+ "from google.colab import auth\n",
+ "\n",
+ "auth.authenticate_user()\n",
+ "print('Authenticated')\n",
+ "\n",
+ "!gcloud config set project {project}\n",
+ "\n",
+ "%cd ~/python-docs-samples/people-and-planet-ai/geospatial-classification"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4ec73dd9",
+ "metadata": {
+ "id": "4ec73dd9"
+ },
+ "source": [
+ "### 🗺️ Authenticate to Earth Engine\n",
+ "\n",
+ "In order to use the Earth Engine API, you'll **need** to have an **Earth Engine account**.\n",
+ "\n",
+ "To create an account, fill out the [registration form here.](https://signup.earthengine.google.com/#!/)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "4cb4cd13",
+ "metadata": {
+ "id": "4cb4cd13"
+ },
+ "outputs": [],
+ "source": [
+ "import ee\n",
+ "import google.auth\n",
+ "\n",
+ "credentials, _ = google.auth.default()\n",
+ "ee.Initialize(credentials, project=project)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "980b0418",
+ "metadata": {
+ "id": "980b0418"
+ },
+ "source": [
+ "# 1. 🛰️ Get the training data\n",
+ "\n",
+ "The training data in this sample comes from **two places**: \n",
+ "\n",
+ "1. The satellite images will be extracted from *Earth Engine*.\n",
+ "\n",
+ "2. The **labels** are provided in a *CSV file* that indicates whether a *coal plant* is turned *on or off* at a **particular timestamp**. \n",
+ "\n",
+ "For each row in the CSV file, we need to extract the corresponding Sentinel image taken at that specific latitude/longitude and timestamp. We'll **export** this image data, along with the corresponding label (on/off), to Cloud Storage."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "94f60a82",
+ "metadata": {
+ "id": "94f60a82"
+ },
+ "outputs": [],
+ "source": [
+ "# Define constants\n",
+ "\n",
+ "LABEL = 'is_powered_on'\n",
+ "IMAGE_COLLECTION = \"COPERNICUS/S2\"\n",
+ "BANDS = ['B1', 'B2', 'B3', 'B4', 'B5', 'B6', 'B7', 'B8', 'B8A', 'B9', 'B10', 'B11', 'B12']\n",
+ "SCALE = 10\n",
+ "PATCH_SIZE = 16"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "beba81d1",
+ "metadata": {
+ "id": "beba81d1"
+ },
+ "source": [
+ "### 🏷️ Import labels\n",
+ "\n",
+ "First, we **import** the **CSV** file that contains the labels."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "42190dcf",
+ "metadata": {
+ "id": "42190dcf"
+ },
+ "outputs": [],
+ "source": [
+ "import pandas as pd\n",
+ "import numpy as np\n",
+ "\n",
+ "labels_dataframe = pd.read_csv('labeled_geospatial_data.csv')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "1cdb7d16-a9c7-4be8-b403-ccb10dcad261",
+ "metadata": {
+ "id": "1cdb7d16-a9c7-4be8-b403-ccb10dcad261"
+ },
+ "source": [
+ "Each row in this dataframe represents a power plant at a particular timestamp. \n",
+ "\n",
+ "The \"is_powered_on\" column indicates whether or not the coal plant was turned **on (1)** or **off (0)** at that timestamp."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "fe94b4d3",
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/",
+ "height": 206
+ },
+ "id": "fe94b4d3",
+ "outputId": "d9c2d364-e4a7-46ad-fa8d-ed2e9d8af3e9"
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "
\n",
+ " "
+ ],
+ "text/plain": [
+ " timestamp lat lon is_powered_on\n",
+ "0 2020-07-03 16:32:41.397000+00:00 39.11613 -84.80529 1\n",
+ "1 2018-06-09 16:25:19.280000+00:00 39.11613 -84.80529 1\n",
+ "2 2017-11-24 16:36:14.460000+00:00 39.11613 -84.80529 0\n",
+ "3 2019-11-01 16:32:42.327000+00:00 39.11613 -84.80529 0\n",
+ "4 2020-05-09 16:32:43.614000+00:00 39.11613 -84.80529 1"
+ ]
+ },
+ "execution_count": 5,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "labels_dataframe.head()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e58c0029",
+ "metadata": {
+ "id": "e58c0029"
+ },
+ "source": [
+ "### 🎛️ Create train/validation splits"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "1cf438ec",
+ "metadata": {
+ "id": "1cf438ec"
+ },
+ "source": [
+ "Before we can train an ML model, we need to split this data into training and validation datasets. We will do this by creating two new dataframes with a 70/30 training validation split."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "e8c5887c",
+ "metadata": {
+ "id": "e8c5887c"
+ },
+ "outputs": [],
+ "source": [
+ "TRAIN_VALIDATION_SPLIT = 0.7\n",
+ "\n",
+ "train_dataframe = labels_dataframe.sample(frac=TRAIN_VALIDATION_SPLIT,random_state=200) #random state is a seed value\n",
+ "validation_dataframe = labels_dataframe.drop(train_dataframe.index).sample(frac=1.0)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "96967303",
+ "metadata": {
+ "id": "96967303"
+ },
+ "source": [
+ "### Merge 🏷️ labels + 🛰️ Sentinel image data"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "fa236af4",
+ "metadata": {
+ "id": "fa236af4"
+ },
+ "source": [
+ "In Earth Engine, an [`ImageCollection`](https://developers.google.com/earth-engine/guides/ic_creating) is a stack or sequence of images. An [`Image`](https://developers.google.com/earth-engine/guides/image_overview) is composed of one or more bands and each band has its own name, data type, scale, mask and projection. The [`Sentinel-2`](https://developers.google.com/earth-engine/guides/ic_creating) dataset is represented as an `ImageCollection`, where each image in the collection is of a specific geographic location at a particular time.\n",
+ "\n",
+ "In the cell below, we write a function to extract the Sentinel image taken at the specific latitude/longitude and timestamp for each row of our dataframe.\n",
+ "\n",
+ "We will store all of this information as an Earth Engine [`Feature Collection`](https://developers.google.com/earth-engine/apidocs/ee-featurecollection). In Earth Engine, a [`Feature`](https://developers.google.com/earth-engine/guides/features) is an object with a _geometry property_ storing a [`Geometry`](https://developers.google.com/earth-engine/guides/geometries) object, and a _properties property_ storing a dictionary of other properties. Groups of related `Features` can be combined into a `FeatureCollection` to enable additional operations on the entire set such as filtering, sorting, and rendering. \n",
+ "\n",
+ "We first filter the Sentinel-2 `ImageCollection` at the start/end dates for a particular row in our dataframe.\n",
+ "\n",
+ "Then, using the [`neighorboodToArray`](https://developers.google.com/earth-engine/api_docs#eeimageneighborhoodtoarray) method we create a `FeatureCollection` that contains the satellite data for each band at the latitude and longitude of interest as well as a 16 pixel padding around that point.\n",
+ "\n",
+ "In the image below you can think of the purple box representing the lat/lon where the power plant is located. And around this pixel, we add the padding.\n",
+ "\n",
+ ""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "3a8b42dd",
+ "metadata": {
+ "id": "3a8b42dd"
+ },
+ "outputs": [],
+ "source": [
+ "from datetime import datetime, timedelta\n",
+ "\n",
+ "def labeled_feature(row):\n",
+ " start = datetime.fromisoformat(row.timestamp)\n",
+ " end = start + timedelta(days=1)\n",
+ " image = (\n",
+ " ee.ImageCollection(IMAGE_COLLECTION)\n",
+ " .filterDate(start.strftime(\"%Y-%m-%d\"), end.strftime(\"%Y-%m-%d\"))\n",
+ " .select(BANDS)\n",
+ " .mosaic()\n",
+ " )\n",
+ " point = ee.Feature(\n",
+ " ee.Geometry.Point([row.lon, row.lat]),\n",
+ " {LABEL: row.is_powered_on},\n",
+ " )\n",
+ " return (\n",
+ " image.neighborhoodToArray(ee.Kernel.square(PATCH_SIZE))\n",
+ " .sampleRegions(ee.FeatureCollection([point]), scale=SCALE)\n",
+ " .first()\n",
+ " )"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "23a1ad4e",
+ "metadata": {
+ "id": "23a1ad4e"
+ },
+ "outputs": [],
+ "source": [
+ "train_features = [labeled_feature(row) for row in train_dataframe.itertuples()]\n",
+ "validation_features = [labeled_feature(row) for row in validation_dataframe.itertuples()]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "21267b05-38cc-4f14-ab09-197baef26713",
+ "metadata": {
+ "id": "21267b05-38cc-4f14-ab09-197baef26713"
+ },
+ "source": [
+ "To get a better sense of what's going on, let's look at the properties for the first `Feature` in the `train_features` list. You can see that it contains a property for the label `is_powered_on`, and 13 additional properies, one for each spectral band."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "994b9f9a",
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "994b9f9a",
+ "outputId": "3dc76f9b-f447-469e-c9ab-26297c0edc6c"
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['system:index',\n",
+ " 'is_powered_on',\n",
+ " 'B10',\n",
+ " 'B11',\n",
+ " 'B12',\n",
+ " 'B8A',\n",
+ " 'B1',\n",
+ " 'B2',\n",
+ " 'B3',\n",
+ " 'B4',\n",
+ " 'B5',\n",
+ " 'B6',\n",
+ " 'B7',\n",
+ " 'B8',\n",
+ " 'B9']"
+ ]
+ },
+ "execution_count": 9,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "ee.FeatureCollection(train_features[0]).propertyNames().getInfo()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "8c79c514-ad63-4b85-8da2-ab8967fe8d5a",
+ "metadata": {
+ "id": "8c79c514-ad63-4b85-8da2-ab8967fe8d5a"
+ },
+ "source": [
+ "The data contained in each band property is an array of shape 33x33.\n",
+ "\n",
+ "For example, here is the data for band B1 in the first element in our list expressed as a numpy array."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "a70c127e-7c45-4eab-914d-17a0c3a9e42c",
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "a70c127e-7c45-4eab-914d-17a0c3a9e42c",
+ "outputId": "04d79e2b-cfe4-4760-a33c-b073bd07c82e"
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "[[1390 1390 1390 ... 1650 1650 1650]\n",
+ " [1390 1390 1390 ... 1650 1650 1650]\n",
+ " [1307 1307 1307 ... 1655 1655 1655]\n",
+ " ...\n",
+ " [1395 1395 1395 ... 1369 1369 1387]\n",
+ " [1395 1395 1395 ... 1369 1369 1387]\n",
+ " [1350 1350 1350 ... 1436 1436 1460]]\n",
+ "shape: (33, 33)\n"
+ ]
+ }
+ ],
+ "source": [
+ "example_feature = np.array(train_features[0].get('B1').getInfo())\n",
+ "print(example_feature)\n",
+ "print('shape: ' + str(example_feature.shape))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "c02607c8",
+ "metadata": {
+ "id": "c02607c8"
+ },
+ "source": [
+ "### 💾 Export data"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "10c87eb9",
+ "metadata": {
+ "id": "10c87eb9"
+ },
+ "source": [
+ "Lastly, we'll export the data to a Cloud Storage bucket. We'll export the data as [TFRecords](https://www.tensorflow.org/tutorials/load_data/tfrecord).\n",
+ "\n",
+ "Later when we run the training job, we'll parse these TFRecords and feed them to the model."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "53f2d867",
+ "metadata": {
+ "id": "53f2d867"
+ },
+ "outputs": [],
+ "source": [
+ "# Export data\n",
+ "\n",
+ "training_task = ee.batch.Export.table.toCloudStorage(\n",
+ " collection=ee.FeatureCollection(train_features),\n",
+ " description=\"Training image export\",\n",
+ " bucket=bucket,\n",
+ " fileNamePrefix=\"geospatial_training\",\n",
+ " selectors=BANDS + [LABEL],\n",
+ " fileFormat=\"TFRecord\",\n",
+ ")\n",
+ "\n",
+ "training_task.start()\n",
+ "\n",
+ "validation_task = ee.batch.Export.table.toCloudStorage(\n",
+ " collection=ee.FeatureCollection(validation_features),\n",
+ " description=\"Validation image export\",\n",
+ " bucket=bucket,\n",
+ " fileNamePrefix=\"geospatial_validation\",\n",
+ " selectors= BANDS + [LABEL],\n",
+ " fileFormat='TFRecord')\n",
+ "\n",
+ "validation_task.start()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "dadeab16",
+ "metadata": {
+ "id": "dadeab16"
+ },
+ "source": [
+ "This export will take around 10 minutes. You can monitor the progress with the following command:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "4d111251",
+ "metadata": {
+ "id": "4d111251"
+ },
+ "outputs": [],
+ "source": [
+ "from pprint import pprint\n",
+ "\n",
+ "pprint(ee.batch.Task.list())"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "02b1b9dd",
+ "metadata": {
+ "id": "02b1b9dd"
+ },
+ "source": [
+ "# 2. 👟 Run a custom training job\n",
+ "\n",
+ "Once the export jobs have finished, we're **ready to use** that data to train a model on Vertex AI Training.\n",
+ "\n",
+ "The complete training code can be found in the `task.py` file.\n",
+ "\n",
+ "To run our custom training job on Vertex AI Training, we'll use the [pre-built containers](https://cloud.google.com/vertex-ai/docs/training/pre-built-containers) provided by Vertex AI to run our training script.\n",
+ "\n",
+ "We'll also make use of a GPU. Our model training will only take a couple of minutes, so using a GPU isn't really necessary. But for demonstration purposes (since adding a GPU is simple!) we will make sure we use a container image that is GPU compatible, and then add the `accelerator_type` and `accelerator_count` parameters to `job.run`. TensorFlow will make use of a single GPU out of the box without any extra code changes."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "a4b99054-b843-485e-9cf0-c9f8ae739d1c",
+ "metadata": {
+ "id": "a4b99054-b843-485e-9cf0-c9f8ae739d1c"
+ },
+ "outputs": [],
+ "source": [
+ "from google.cloud import aiplatform\n",
+ "\n",
+ "aiplatform.init(project=project, staging_bucket=bucket)\n",
+ "\n",
+ "job = aiplatform.CustomTrainingJob(\n",
+ " display_name=\"geospatial_model_training\",\n",
+ " script_path=\"task.py\",\n",
+ " container_uri=\"us-docker.pkg.dev/vertex-ai/training/tf-gpu.2-7:latest\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "a4baff79-0347-4452-afaa-9c042472f837",
+ "metadata": {
+ "id": "a4baff79-0347-4452-afaa-9c042472f837"
+ },
+ "source": [
+ "The job will take around 10 minutes to run."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5893ce1d-cdbe-43fa-98cc-221a7a2530d3",
+ "metadata": {
+ "id": "5893ce1d-cdbe-43fa-98cc-221a7a2530d3"
+ },
+ "outputs": [],
+ "source": [
+ "model = job.run(accelerator_type='NVIDIA_TESLA_K80', accelerator_count=1, args=[f'--bucket={bucket}'])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "c75499ed",
+ "metadata": {
+ "id": "c75499ed"
+ },
+ "source": [
+ "# 3. 💻 Deploy a web service to host the trained model"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "86cbab39",
+ "metadata": {
+ "id": "86cbab39"
+ },
+ "source": [
+ "Next, we use\n",
+ "[Cloud Run](https://cloud.google.com/run)\n",
+ "to deploy a web service that exposes a\n",
+ "[REST API](https://en.wikipedia.org/wiki/Representational_state_transfer) to\n",
+ "get predictions from our trained model.\n",
+ "\n",
+ "We'll deploy our service to Cloud Run [directly from source code](https://cloud.google.com/run/docs/deploying-source-code) so we don't need to build the container image first. Behind the scenes, this command uses Google Cloud buildpacks and Cloud Build to automatically build a container image from our source code in the `serving_app` directory. To run the web service, we configure Cloud Run to launch\n",
+ "[`gunicorn`](https://gunicorn.org)\n",
+ "on this container image. \n",
+ "\n",
+ "Since calls to this web service could launch potentially expensive jobs in our project, we configure it to _only_ accept authenticated calls."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9978056f-4467-4dda-85a5-84655ade9a11",
+ "metadata": {
+ "id": "9978056f-4467-4dda-85a5-84655ade9a11"
+ },
+ "source": [
+ "## 🐣 Deploy app"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "13c299f1-e108-46bd-8b12-06af56a88444",
+ "metadata": {
+ "id": "13c299f1-e108-46bd-8b12-06af56a88444"
+ },
+ "outputs": [],
+ "source": [
+ "# Deploy the web service to Cloud Run.\n",
+ "# https://cloud.google.com/sdk/gcloud/reference/run/deploy\n",
+ "!gcloud run deploy \"geospatial-service\" \\\n",
+ " --source=serving_app \\\n",
+ " --command=\"gunicorn\" \\\n",
+ " --args=\"--threads=8,--timeout=0,main:app\" \\\n",
+ " --region=\"us-central1\" \\\n",
+ " --memory=\"1G\" \\\n",
+ " --no-allow-unauthenticated \\"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "5a32d4bf-4345-43f7-9371-aa151ad4f521",
+ "metadata": {
+ "id": "5a32d4bf-4345-43f7-9371-aa151ad4f521"
+ },
+ "source": [
+ "Now we need the web service URL to make calls to the REST API we just exposed. We can use `gcloud run services describe` to get the web service URL.\n",
+ "\n",
+ "Since we only accept authorized calls in our web service, we also need to authenticate each call.\n",
+ "`gcloud` is already authenticated, so we can use `gcloud auth print-identity-token` to get quick access.\n",
+ "\n",
+ "> ℹ️ For more information on how to do authenticated calls in Cloud Run, see the\n",
+ "> [Authentication overview](https://cloud.google.com/run/docs/authenticating/overview) page."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "53f5e5e3-d5dd-4cb7-bb38-5b2e3b439ecd",
+ "metadata": {
+ "id": "53f5e5e3-d5dd-4cb7-bb38-5b2e3b439ecd"
+ },
+ "outputs": [],
+ "source": [
+ "import subprocess\n",
+ "\n",
+ "# Get the web service URL.\n",
+ "# https://cloud.google.com/sdk/gcloud/reference/run/services/describe\n",
+ "service_url = subprocess.run(\n",
+ " [ 'gcloud', 'run', 'services', 'describe', 'geospatial-service',\n",
+ " f'--region={region}',\n",
+ " f'--format=get(status.url)',\n",
+ " ],\n",
+ " capture_output=True,\n",
+ ").stdout.decode('utf-8').strip()\n",
+ "print(f\"service_url: {service_url}\")\n",
+ "\n",
+ "# Get an identity token for authorized calls to our web service.\n",
+ "# https://cloud.google.com/sdk/gcloud/reference/auth/print-identity-token\n",
+ "identity_token = subprocess.run(\n",
+ " ['gcloud', 'auth', 'print-identity-token'],\n",
+ " capture_output=True,\n",
+ ").stdout.decode('utf-8').strip()\n",
+ "print(f\"identity_token: {identity_token}\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "aa2c4dfe-b55d-4f80-a7eb-9ee86542ce59",
+ "metadata": {
+ "id": "aa2c4dfe-b55d-4f80-a7eb-9ee86542ce59"
+ },
+ "source": [
+ "Finally, we can test that everything is working.\n",
+ "\n",
+ "We included a `ping` method in our web service just to *make sure everything is working* as expected.\n",
+ "It simply returns back the arguments we passed to the call, as well as a response saying that the call was successful.\n",
+ "\n",
+ "> 🛎️ This is a convenient way to make sure the web service is reachable, the authentication is working as expected, and the request arguments are passed correctly.\n",
+ "\n",
+ "We can use Python's\n",
+ "[`requests`](https://docs.python-requests.org)\n",
+ "library.\n",
+ "The web service was built to always accept [JSON](https://www.w3schools.com/whatis/whatis_json.asp)-encoded requests, and returns JSON-encoded responses.\n",
+ "\n",
+ "For a **request to be successful**, it **must**:\n",
+ "\n",
+ "* Be an [`HTTP POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request\n",
+ "* Contain the following **headers**:\n",
+ " * `Authorization: Bearer IDENTITY_TOKEN`\n",
+ " * `Content-Type: application/json`\n",
+ "* The data must be **valid JSON**, if *no arguments* are needed we can pass `{}` as an **empty object**.\n",
+ "\n",
+ "For **ease of use**, `requests.post` has a\n",
+ "[`json` parameter](https://docs.python-requests.org/en/master/user/quickstart/#more-complicated-post-requests)\n",
+ "that **automatically attaches the header** `Content-Type: application/json` and encodes our data into a JSON string."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "9025db3b-d409-46cf-9ce2-6f0209dfbea3",
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "9025db3b-d409-46cf-9ce2-6f0209dfbea3",
+ "outputId": "977aa6d1-59f6-4dbf-80c7-c9725d43dddc"
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "{'args': 'Hello world!', 'response': 'Your request was successful! 🎉'}"
+ ]
+ },
+ "execution_count": 21,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "import requests\n",
+ "\n",
+ "requests.post(\n",
+ " url=f'{service_url}/ping',\n",
+ " headers={'Authorization': f'Bearer {identity_token}'},\n",
+ " json={'x': 42, 'message': 'Hello world!'},\n",
+ ").json()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "45d64a22-887a-4469-9ba3-668ec23f8667",
+ "metadata": {
+ "id": "45d64a22-887a-4469-9ba3-668ec23f8667"
+ },
+ "source": [
+ "# 4.🔮 Get Predictions"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "462b7bf1-cf07-4a93-9cf3-0f9f31c13fa9",
+ "metadata": {
+ "id": "462b7bf1-cf07-4a93-9cf3-0f9f31c13fa9"
+ },
+ "source": [
+ "Now that we know our app is up and running, we can use it to make predictions.\n",
+ "\n",
+ "Let's start by making a prediction for a particular coal plant. To do this we will need to extract the Sentinel data from Earth Engine and send it in the body of the post requst to the prediction service.\n",
+ "\n",
+ "We'll start with a plant located at the coordinates -84.80529, 39.11613, and then extract the satellite data from October 2021."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "9e477289-398c-4bcb-ab23-aee65ac92388",
+ "metadata": {
+ "id": "9e477289-398c-4bcb-ab23-aee65ac92388"
+ },
+ "outputs": [],
+ "source": [
+ "# Extract image data\n",
+ "\n",
+ "import json\n",
+ "\n",
+ "def get_prediction_data(lon, lat, start, end):\n",
+ " \"\"\"Extracts Sentinel image as json at specific lat/lon and timestamp.\"\"\"\n",
+ "\n",
+ " location = ee.Feature(ee.Geometry.Point([lon, lat]))\n",
+ " image = (\n",
+ " ee.ImageCollection(IMAGE_COLLECTION)\n",
+ " .filterDate(start, end)\n",
+ " .select(BANDS)\n",
+ " .mosaic()\n",
+ " )\n",
+ "\n",
+ " feature = image.neighborhoodToArray(ee.Kernel.square(PATCH_SIZE)).sampleRegions(\n",
+ " collection=ee.FeatureCollection([location]), scale=SCALE\n",
+ " )\n",
+ "\n",
+ " return feature.getInfo()[\"features\"][0][\"properties\"]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4a718e67",
+ "metadata": {
+ "id": "4a718e67"
+ },
+ "source": [
+ "When we call the `get_prediction_data` function we need to pass in the start and end dates. \n",
+ "\n",
+ "Sentinel-2 takes pictures every 10 days. At training time, we knew the exact date of the Sentinel-2 image, as this was provided in the labels CSV file. However, for user supplied images for prediction we don't know the specific date the image was taken. To address this, we'll extract data for the entire month of October and then use the `mosaic` function in Earth Engine which will grab the earliest image in that range, stitch together images at the seams, and discard the rest."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "86d53ea1-b09e-4afb-8d04-60b73ec59c7c",
+ "metadata": {
+ "id": "86d53ea1-b09e-4afb-8d04-60b73ec59c7c"
+ },
+ "outputs": [],
+ "source": [
+ "prediction_data = get_prediction_data(-84.80529, 39.11613, '2021-10-01', '2021-10-31')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9d93aaa8",
+ "metadata": {
+ "id": "9d93aaa8"
+ },
+ "source": [
+ "The prediction service **expects two things** the **input data** for the prediction as well as the Cloud Storage **path** where the model is stored."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5c01631e-5607-45c8-a42e-354fb38a87e1",
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/"
+ },
+ "id": "5c01631e-5607-45c8-a42e-354fb38a87e1",
+ "outputId": "92fd906e-af86-4e1c-f60c-35e84a9831fe"
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "{'predictions': [[[[1.0]]]]}"
+ ]
+ },
+ "execution_count": 24,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "requests.post(\n",
+ " url=f'{service_url}/predict',\n",
+ " headers={'Authorization': f'Bearer {identity_token}'},\n",
+ " json={'data': prediction_data, 'bucket': bucket},\n",
+ ").json()['predictions']"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "2222aaf9",
+ "metadata": {
+ "id": "2222aaf9"
+ },
+ "source": [
+ "# 4. 🗺️ Visualize predictions"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e70fd0a5-a1ae-4cac-91cc-342809d9fb3b",
+ "metadata": {
+ "id": "e70fd0a5-a1ae-4cac-91cc-342809d9fb3b"
+ },
+ "source": [
+ "Let's visualize the results of a coal plant in Spain. First, we get predictions for the four towers at this power plant."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "8f6dc24d",
+ "metadata": {
+ "id": "8f6dc24d"
+ },
+ "outputs": [],
+ "source": [
+ "def get_prediction(lon, lat, start, end):\n",
+ " prediction_data = get_prediction_data(lon, lat, start, end)\n",
+ " result = requests.post(\n",
+ " url=f'{service_url}/predict',\n",
+ " headers={'Authorization': f'Bearer {identity_token}'},\n",
+ " json={'data': prediction_data, 'bucket': bucket},).json()\n",
+ " return result['predictions']['predictions'][0][0][0][0]"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "9fc56972-47bb-4b37-b447-400cbea5e90a",
+ "metadata": {
+ "id": "9fc56972-47bb-4b37-b447-400cbea5e90a"
+ },
+ "outputs": [],
+ "source": [
+ "lons = [-7.86444, -7.86376, -7.85755, -7.85587]\n",
+ "lats = [43.43717, 43.43827, 43.44075, 43.44114]"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5230f05e",
+ "metadata": {
+ "id": "5230f05e"
+ },
+ "outputs": [],
+ "source": [
+ "plant_predictions = [get_prediction(lon , lat, '2021-10-01', '2021-10-31') for lon, lat in zip(lons, lats)]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "be593a27-71b1-4ea1-8c2e-100a0a82ccdd",
+ "metadata": {
+ "id": "be593a27-71b1-4ea1-8c2e-100a0a82ccdd"
+ },
+ "source": [
+ "Next, we can **plot** these points on a map. **Blue** means our model predicts that the towers are **\"off\"**, and **red** means our model predicts that the towers are **\"on\"** and producing carbon pollution."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "15ba038b-49c9-40bf-8d87-af7d253d270d",
+ "metadata": {
+ "colab": {
+ "base_uri": "https://localhost:8080/",
+ "height": 771
+ },
+ "id": "15ba038b-49c9-40bf-8d87-af7d253d270d",
+ "outputId": "76e05dd2-3bae-433f-9f34-4df229f7620e"
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "
Make this Notebook Trusted to load map: File -> Trust Notebook