sagemaker-python-sdk/tensorflow_iris_dnn_classifier_using_estimators/tensorflow_iris_dnn_classifier_using_estimators.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Creating, training, and serving using SageMaker Estimators\n",
    "\n",
    "The **SageMaker Python SDK** helps you deploy your models for training and hosting in optimized, production ready containers in SageMaker. The SageMaker Python SDK is easy to use, modular, extensible and compatible with TensorFlow and MXNet. This tutorial focuses on **TensorFlow** and shows how we can train and host a TensorFlow DNNClassifier estimator in SageMaker using the Python SDK.\n",
    "\n",
    "\n",
    "TensorFlow's high-level machine learning API (tf.estimator) makes it easy to\n",
    "configure, train, and evaluate a variety of machine learning models.\n",
    "\n",
    "\n",
    "In this tutorial, you'll use tf.estimator to construct a\n",
    "[neural network](https://en.wikipedia.org/wiki/Artificial_neural_network)\n",
    "classifier and train it on the\n",
    "[Iris data set](https://en.wikipedia.org/wiki/Iris_flower_data_set) to\n",
    "predict flower species based on sepal/petal geometry. You'll write code to\n",
    "perform the following five steps:\n",
    "\n",
    "1.  Deploy a TensorFlow container in SageMaker\n",
    "2.  Load CSVs containing Iris training/test data from a S3 bucket into a TensorFlow `Dataset`\n",
    "3.  Construct a `tf.estimator.DNNClassifier` neural network classifier\n",
    "4.  Train the model using the training data\n",
    "5.  Host the model in an endpoint\n",
    "6.  Classify new samples invoking the endpoint\n",
    "\n",
    "This tutorial is a simplified version of TensorFlow's [get_started/estimator](https://www.tensorflow.org/get_started/estimator#fit_the_dnnclassifier_to_the_iris_training_data) tutorial **but using SageMaker and the SageMaker Python SDK** to simplify training and hosting."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The Iris dataset\n",
    "\n",
    "The [Iris data set](https://en.wikipedia.org/wiki/Iris_flower_data_set) contains\n",
    "150 rows of data, comprising 50 samples from each of three related Iris species:\n",
    "*Iris setosa*, *Iris virginica*, and *Iris versicolor*.\n",
    "\n",
    "![Petal geometry compared for three iris species: Iris setosa, Iris virginica, and Iris versicolor](https://www.tensorflow.org/images/iris_three_species.jpg) **From left to right,\n",
    "[*Iris setosa*](https://commons.wikimedia.org/w/index.php?curid=170298) (by\n",
    "[Radomil](https://commons.wikimedia.org/wiki/User:Radomil), CC BY-SA 3.0),\n",
    "[*Iris versicolor*](https://commons.wikimedia.org/w/index.php?curid=248095) (by\n",
    "[Dlanglois](https://commons.wikimedia.org/wiki/User:Dlanglois), CC BY-SA 3.0),\n",
    "and [*Iris virginica*](https://www.flickr.com/photos/33397993@N05/3352169862)\n",
    "(by [Frank Mayfield](https://www.flickr.com/photos/33397993@N05), CC BY-SA\n",
    "2.0).**\n",
    "\n",
    "Each row contains the following data for each flower sample:\n",
    "[sepal](https://en.wikipedia.org/wiki/Sepal) length, sepal width,\n",
    "[petal](https://en.wikipedia.org/wiki/Petal) length, petal width, and flower\n",
    "species. Flower species are represented as integers, with 0 denoting *Iris\n",
    "setosa*, 1 denoting *Iris versicolor*, and 2 denoting *Iris virginica*.\n",
    "\n",
    "Sepal Length | Sepal Width | Petal Length | Petal Width | Species\n",
    ":----------- | :---------- | :----------- | :---------- | :-------\n",
    "5.1          | 3.5         | 1.4          | 0.2         | 0\n",
    "4.9          | 3.0         | 1.4          | 0.2         | 0\n",
    "4.7          | 3.2         | 1.3          | 0.2         | 0\n",
    "&hellip;     | &hellip;    | &hellip;     | &hellip;    | &hellip;\n",
    "7.0          | 3.2         | 4.7          | 1.4         | 1\n",
    "6.4          | 3.2         | 4.5          | 1.5         | 1\n",
    "6.9          | 3.1         | 4.9          | 1.5         | 1\n",
    "&hellip;     | &hellip;    | &hellip;     | &hellip;    | &hellip;\n",
    "6.5          | 3.0         | 5.2          | 2.0         | 2\n",
    "6.2          | 3.4         | 5.4          | 2.3         | 2\n",
    "5.9          | 3.0         | 5.1          | 1.8         | 2\n",
    "\n",
    "For this tutorial, the Iris data has been randomized and split into two separate\n",
    "CSVs:\n",
    "\n",
    "*   A training set of 120 samples\n",
    "    iris_training.csv\n",
    "*   A test set of 30 samples\n",
    "    iris_test.csv\n",
    "\n",
    "These files are provided in the SageMaker sample data bucket:\n",
    "**s3://sagemaker-sample-data-{region}/tensorflow/iris**. Copies of the bucket exist in each SageMaker region. When we access the data, we'll replace {region} with the AWS region the notebook is running in."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Let us first initialize variables"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "isConfigCell": true
   },
   "outputs": [],
   "source": [
    "from sagemaker import get_execution_role\n",
    "from sagemaker.session import Session\n",
    "\n",
    "# S3 bucket for saving code and model artifacts.\n",
    "# Feel free to specify a different bucket here if you wish.\n",
    "bucket = Session().default_bucket()\n",
    "\n",
    "# Location to save your custom code in tar.gz format.\n",
    "custom_code_upload_location = 's3://{}/customcode/tensorflow_iris'.format(bucket)\n",
    "\n",
    "# Location where results of model training are saved.\n",
    "model_artifacts_location = 's3://{}/artifacts'.format(bucket)\n",
    "\n",
    "#IAM execution role that gives SageMaker access to resources in your AWS account.\n",
    "role = get_execution_role()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# tf.estimator"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The tf.estimator framework makes it easy to construct and train machine learning models via its high-level Estimator API. Estimator offers classes you can instantiate to quickly configure common model types such as regressors and classifiers:\n",
    "\n",
    "\n",
    "*   **```tf.estimator.LinearClassifier```**:\n",
    "    Constructs a linear classification model.\n",
    "*   **```tf.estimator.LinearRegressor```**:\n",
    "    Constructs a linear regression model.\n",
    "*   **```tf.estimator.DNNClassifier```**:\n",
    "    Construct a neural network classification model.\n",
    "*   **```tf.estimator.DNNRegressor```**:\n",
    "    Construct a neural network regression model.\n",
    "*   **```tf.estimator.DNNLinearCombinedClassifier```**:\n",
    "    Construct a neural network and linear combined classification model.\n",
    "*   **```tf.estimator.DNNRegressor```**:\n",
    "    Construct a neural network and linear combined regression model.\n",
    "    \n",
    "More information about estimators can be found [here](https://www.tensorflow.org/extend/estimators)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Construct a deep neural network classifier"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Complete neural network source code \n",
    "\n",
    "Here is the full code for the neural network classifier:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cat \"iris_dnn_classifier.py\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With few lines of code, using SageMaker and TensorFlow, you can create a deep neural network model, ready for training and hosting. Let's give a deeper look at the code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using a tf.estimator in SageMaker\n",
    "Using a TensorFlow estimator in SageMaker is very easy, you can create one with few lines of code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def estimator(model_path, hyperparameters):\n",
    "    feature_columns = [tf.feature_column.numeric_column(INPUT_TENSOR_NAME, shape=[4])]\n",
    "    return tf.estimator.DNNClassifier(feature_columns=feature_columns,\n",
    "                                      hidden_units=[10, 20, 10],\n",
    "                                      n_classes=3,\n",
    "                                      model_dir=model_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The code above first defines the model's feature columns, which specify the data\n",
    "type for the features in the data set. All the feature data is continuous, so\n",
    "`tf.feature_column.numeric_column` is the appropriate function to use to\n",
    "construct the feature columns. There are four features in the data set (sepal\n",
    "width, sepal height, petal width, and petal height), so accordingly `shape`\n",
    "must be set to `[4]` to hold all the data.\n",
    "\n",
    "Then, the code creates a `DNNClassifier` model using the following arguments:\n",
    "\n",
    "*   `feature_columns=feature_columns`. The set of feature columns defined above.\n",
    "*   `hidden_units=[10, 20, 10]`. Three\n",
    "    [hidden layers](http://stats.stackexchange.com/questions/181/how-to-choose-the-number-of-hidden-layers-and-nodes-in-a-feedforward-neural-netw),\n",
    "    containing 10, 20, and 10 neurons, respectively.\n",
    "*   `n_classes=3`. Three target classes, representing the three Iris species.\n",
    "*   `model_dir=model_path`. The directory in which TensorFlow will save\n",
    "    checkpoint data during model training. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Describe the training input pipeline\n",
    "\n",
    "The `tf.estimator` API uses input functions, which create the TensorFlow\n",
    "operations that generate data for the model.\n",
    "We can use `tf.estimator.inputs.numpy_input_fn` to produce the input pipeline:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def train_input_fn(training_dir, hyperparameters):\n",
    "    training_set = tf.contrib.learn.datasets.base.load_csv_with_header(\n",
    "        filename=os.path.join(training_dir, 'iris_training.csv'),\n",
    "        target_dtype=np.int,\n",
    "        features_dtype=np.float32)\n",
    "\n",
    "    return tf.estimator.inputs.numpy_input_fn(\n",
    "        x={INPUT_TENSOR_NAME: np.array(training_set.data)},\n",
    "        y=np.array(training_set.target),\n",
    "        num_epochs=None,\n",
    "        shuffle=True)()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Describe the serving input pipeline:\n",
    "\n",
    "After traininng your model, SageMaker will host it in a TensorFlow serving. You need to describe a serving input function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def serving_input_fn(hyperparameters):\n",
    "    feature_spec = {INPUT_TENSOR_NAME: tf.FixedLenFeature(dtype=tf.float32, shape=[4])}\n",
    "    return tf.estimator.export.build_parsing_serving_input_receiver_fn(feature_spec)()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we are ready to submit the script for training."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Train a Model on Amazon SageMaker using TensorFlow custom code\n",
    "\n",
    "We can use the SDK to run our local training script on SageMaker infrastructure.\n",
    "\n",
    "1. Pass the path to the iris_dnn_classifier.py file, which contains the functions for defining your estimator, to the sagemaker.TensorFlow init method.\n",
    "2. Pass the S3 location that we uploaded our data to previously to the fit() method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from sagemaker.tensorflow import TensorFlow\n",
    "\n",
    "iris_estimator = TensorFlow(entry_point='iris_dnn_classifier.py',\n",
    "                            role=role,\n",
    "                            framework_version='1.12.0',\n",
    "                            output_path=model_artifacts_location,\n",
    "                            code_location=custom_code_upload_location,\n",
    "                            train_instance_count=1,\n",
    "                            train_instance_type='ml.c4.xlarge',\n",
    "                            training_steps=1000,\n",
    "                            evaluation_steps=100)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%time\n",
    "import boto3\n",
    "\n",
    "# use the region-specific sample data bucket\n",
    "region = boto3.Session().region_name\n",
    "train_data_location = 's3://sagemaker-sample-data-{}/tensorflow/iris'.format(region)\n",
    "\n",
    "iris_estimator.fit(train_data_location)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Deploy the trained Model  \n",
    "\n",
    "The deploy() method creates an endpoint which serves prediction requests in real-time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "%%time\n",
    "iris_predictor = iris_estimator.deploy(initial_instance_count=1,\n",
    "                                       instance_type='ml.m4.xlarge')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#  Invoke the Endpoint to get inferences"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "scrolled": true
   },
   "source": [
    "Invoking prediction:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "iris_predictor.predict([6.4, 3.2, 4.5, 1.5]) #expected label to be 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# (Optional) Delete the Endpoint\n",
    "\n",
    "After you have finished with this example, remember to delete the prediction endpoint to release the instance(s) associated with it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(iris_predictor.endpoint)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sagemaker\n",
    "\n",
    "sagemaker.Session().delete_endpoint(iris_predictor.endpoint)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "conda_tensorflow_p27",
   "language": "python",
   "name": "conda_tensorflow_p27"
  },
  "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.15"
  },
  "notice": "Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.  Licensed under the Apache License, Version 2.0 (the \"License\"). You may not use this file except in compliance with the License. A copy of the License is located at http://aws.amazon.com/apache2.0/ or in the \"license\" file accompanying this file. This file is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License."
 },
 "nbformat": 4,
 "nbformat_minor": 1
}