Tutorials/Boston Housing - XGBoost (Deploy) - Low Level.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Predicting Boston Housing Prices\n",
    "\n",
    "## Using XGBoost in SageMaker (Deploy)\n",
    "\n",
    "_Deep Learning Nanodegree Program | Deployment_\n",
    "\n",
    "---\n",
    "\n",
    "As an introduction to using SageMaker's Low Level Python API we will look at a relatively simple problem. Namely, we will use the [Boston Housing Dataset](https://www.cs.toronto.edu/~delve/data/boston/bostonDetail.html) to predict the median value of a home in the area of Boston Mass.\n",
    "\n",
    "The documentation reference for the API used in this notebook is the [SageMaker Developer's Guide](https://docs.aws.amazon.com/sagemaker/latest/dg/)\n",
    "\n",
    "## General Outline\n",
    "\n",
    "Typically, when using a notebook instance with SageMaker, you will proceed through the following steps. Of course, not every step will need to be done with each project. Also, there is quite a lot of room for variation in many of the steps, as you will see throughout these lessons.\n",
    "\n",
    "1. Download or otherwise retrieve the data.\n",
    "2. Process / Prepare the data.\n",
    "3. Upload the processed data to S3.\n",
    "4. Train a chosen model.\n",
    "5. Test the trained model (typically using a batch transform job).\n",
    "6. Deploy the trained model.\n",
    "7. Use the deployed model.\n",
    "\n",
    "In this notebook we will be skipping step 5, testing the model. We will still test the model but we will do so by first deploying it and then sending the test data to the deployed model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Make sure that we use SageMaker 1.x\n",
    "!pip install sagemaker==1.72.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 0: Setting up the notebook\n",
    "\n",
    "We begin by setting up all of the necessary bits required to run our notebook. To start that means loading all of the Python modules we will need."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "\n",
    "import os\n",
    "\n",
    "import time\n",
    "from time import gmtime, strftime\n",
    "\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "from sklearn.datasets import load_boston\n",
    "import sklearn.model_selection"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to the modules above, we need to import the various bits of SageMaker that we will be using. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sagemaker\n",
    "from sagemaker import get_execution_role\n",
    "from sagemaker.amazon.amazon_estimator import get_image_uri\n",
    "\n",
    "# This is an object that represents the SageMaker session that we are currently operating in. This\n",
    "# object contains some useful information that we will need to access later such as our region.\n",
    "session = sagemaker.Session()\n",
    "\n",
    "# This is an object that represents the IAM role that we are currently assigned. When we construct\n",
    "# and launch the training job later we will need to tell it what IAM role it should have. Since our\n",
    "# use case is relatively simple we will simply assign the training job the role we currently have.\n",
    "role = get_execution_role()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 1: Downloading the data\n",
    "\n",
    "Fortunately, this dataset can be retrieved using sklearn and so this step is relatively straightforward."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "boston = load_boston()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: Preparing and splitting the data\n",
    "\n",
    "Given that this is clean tabular data, we don't need to do any processing. However, we do need to split the rows in the dataset up into train, test and validation sets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# First we package up the input data and the target variable (the median value) as pandas dataframes. This\n",
    "# will make saving the data to a file a little easier later on.\n",
    "\n",
    "X_bos_pd = pd.DataFrame(boston.data, columns=boston.feature_names)\n",
    "Y_bos_pd = pd.DataFrame(boston.target)\n",
    "\n",
    "# We split the dataset into 2/3 training and 1/3 testing sets.\n",
    "X_train, X_test, Y_train, Y_test = sklearn.model_selection.train_test_split(X_bos_pd, Y_bos_pd, test_size=0.33)\n",
    "\n",
    "# Then we split the training set further into 2/3 training and 1/3 validation sets.\n",
    "X_train, X_val, Y_train, Y_val = sklearn.model_selection.train_test_split(X_train, Y_train, test_size=0.33)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: Uploading the training and validation files to S3\n",
    "\n",
    "When a training job is constructed using SageMaker, a container is executed which performs the training operation. This container is given access to data that is stored in S3. This means that we need to upload the data we want to use for training to S3. We can use the SageMaker API to do this and hide some of the details.\n",
    "\n",
    "### Save the data locally\n",
    "\n",
    "First we need to create the train and validation csv files which we will then upload to S3."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This is our local data directory. We need to make sure that it exists.\n",
    "data_dir = '../data/boston'\n",
    "if not os.path.exists(data_dir):\n",
    "    os.makedirs(data_dir)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We use pandas to save our train and validation data to csv files. Note that we make sure not to include header\n",
    "# information or an index as this is required by the built in algorithms provided by Amazon. Also, it is assumed\n",
    "# that the first entry in each row is the target variable.\n",
    "\n",
    "pd.concat([Y_val, X_val], axis=1).to_csv(os.path.join(data_dir, 'validation.csv'), header=False, index=False)\n",
    "pd.concat([Y_train, X_train], axis=1).to_csv(os.path.join(data_dir, 'train.csv'), header=False, index=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Upload to S3\n",
    "\n",
    "Since we are currently running inside of a SageMaker session, we can use the object which represents this session to upload our data to the 'default' S3 bucket. Note that it is good practice to provide a custom prefix (essentially an S3 folder) to make sure that you don't accidentally interfere with data uploaded from some other notebook or project."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "prefix = 'boston-xgboost-deploy-ll'\n",
    "\n",
    "val_location = session.upload_data(os.path.join(data_dir, 'validation.csv'), key_prefix=prefix)\n",
    "train_location = session.upload_data(os.path.join(data_dir, 'train.csv'), key_prefix=prefix)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 4: Train and construct the XGBoost model\n",
    "\n",
    "Now that we have the training and validation data uploaded to S3, we can construct a training job for our XGBoost model and build the model itself.\n",
    "\n",
    "### Set up the training job\n",
    "\n",
    "First, we will set up and execute a training job for our model. To do this we need to specify some information that SageMaker will use to set up and properly execute the computation. For additional documentation on constructing a training job, see the [CreateTrainingJob API](https://docs.aws.amazon.com/sagemaker/latest/dg/API_CreateTrainingJob.html) reference."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We will need to know the name of the container that we want to use for training. SageMaker provides\n",
    "# a nice utility method to construct this for us.\n",
    "container = get_image_uri(session.boto_region_name, 'xgboost')\n",
    "\n",
    "# We now specify the parameters we wish to use for our training job\n",
    "training_params = {}\n",
    "\n",
    "# We need to specify the permissions that this training job will have. For our purposes we can use\n",
    "# the same permissions that our current SageMaker session has.\n",
    "training_params['RoleArn'] = role\n",
    "\n",
    "# Here we describe the algorithm we wish to use. The most important part is the container which\n",
    "# contains the training code.\n",
    "training_params['AlgorithmSpecification'] = {\n",
    "    \"TrainingImage\": container,\n",
    "    \"TrainingInputMode\": \"File\"\n",
    "}\n",
    "\n",
    "# We also need to say where we would like the resulting model artifacst stored.\n",
    "training_params['OutputDataConfig'] = {\n",
    "    \"S3OutputPath\": \"s3://\" + session.default_bucket() + \"/\" + prefix + \"/output\"\n",
    "}\n",
    "\n",
    "# We also need to set some parameters for the training job itself. Namely we need to describe what sort of\n",
    "# compute instance we wish to use along with a stopping condition to handle the case that there is\n",
    "# some sort of error and the training script doesn't terminate.\n",
    "training_params['ResourceConfig'] = {\n",
    "    \"InstanceCount\": 1,\n",
    "    \"InstanceType\": \"ml.m4.xlarge\",\n",
    "    \"VolumeSizeInGB\": 5\n",
    "}\n",
    "    \n",
    "training_params['StoppingCondition'] = {\n",
    "    \"MaxRuntimeInSeconds\": 86400\n",
    "}\n",
    "\n",
    "# Next we set the algorithm specific hyperparameters. You may wish to change these to see what effect\n",
    "# there is on the resulting model.\n",
    "training_params['HyperParameters'] = {\n",
    "    \"max_depth\": \"5\",\n",
    "    \"eta\": \"0.2\",\n",
    "    \"gamma\": \"4\",\n",
    "    \"min_child_weight\": \"6\",\n",
    "    \"subsample\": \"0.8\",\n",
    "    \"objective\": \"reg:linear\",\n",
    "    \"early_stopping_rounds\": \"10\",\n",
    "    \"num_round\": \"200\"\n",
    "}\n",
    "\n",
    "# Now we need to tell SageMaker where the data should be retrieved from.\n",
    "training_params['InputDataConfig'] = [\n",
    "    {\n",
    "        \"ChannelName\": \"train\",\n",
    "        \"DataSource\": {\n",
    "            \"S3DataSource\": {\n",
    "                \"S3DataType\": \"S3Prefix\",\n",
    "                \"S3Uri\": train_location,\n",
    "                \"S3DataDistributionType\": \"FullyReplicated\"\n",
    "            }\n",
    "        },\n",
    "        \"ContentType\": \"csv\",\n",
    "        \"CompressionType\": \"None\"\n",
    "    },\n",
    "    {\n",
    "        \"ChannelName\": \"validation\",\n",
    "        \"DataSource\": {\n",
    "            \"S3DataSource\": {\n",
    "                \"S3DataType\": \"S3Prefix\",\n",
    "                \"S3Uri\": val_location,\n",
    "                \"S3DataDistributionType\": \"FullyReplicated\"\n",
    "            }\n",
    "        },\n",
    "        \"ContentType\": \"csv\",\n",
    "        \"CompressionType\": \"None\"\n",
    "    }\n",
    "]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Execute the training job\n",
    "\n",
    "Now that we've built the dict containing the training job parameters, we can ask SageMaker to execute the job."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# First we need to choose a training job name. This is useful for if we want to recall information about our\n",
    "# training job at a later date. Note that SageMaker requires a training job name and that the name needs to\n",
    "# be unique, which we accomplish by appending the current timestamp.\n",
    "training_job_name = \"boston-xgboost-\" + strftime(\"%Y-%m-%d-%H-%M-%S\", gmtime())\n",
    "training_params['TrainingJobName'] = training_job_name\n",
    "\n",
    "# And now we ask SageMaker to create (and execute) the training job\n",
    "training_job = session.sagemaker_client.create_training_job(**training_params)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The training job has now been created by SageMaker and is currently running. Since we need the output of the training job, we may wish to wait until it has finished. We can do so by asking SageMaker to output the logs generated by the training job and continue doing so until the training job terminates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "session.logs_for_job(training_job_name, wait=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Build the model\n",
    "\n",
    "Now that the training job has completed, we have some model artifacts which we can use to build a model. Note that here we mean SageMaker's definition of a model, which is a collection of information about a specific algorithm along with the artifacts which result from a training job."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We begin by asking SageMaker to describe for us the results of the training job. The data structure\n",
    "# returned contains a lot more information than we currently need, try checking it out yourself in\n",
    "# more detail.\n",
    "training_job_info = session.sagemaker_client.describe_training_job(TrainingJobName=training_job_name)\n",
    "\n",
    "model_artifacts = training_job_info['ModelArtifacts']['S3ModelArtifacts']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Just like when we created a training job, the model name must be unique\n",
    "model_name = training_job_name + \"-model\"\n",
    "\n",
    "# We also need to tell SageMaker which container should be used for inference and where it should\n",
    "# retrieve the model artifacts from. In our case, the xgboost container that we used for training\n",
    "# can also be used for inference.\n",
    "primary_container = {\n",
    "    \"Image\": container,\n",
    "    \"ModelDataUrl\": model_artifacts\n",
    "}\n",
    "\n",
    "# And lastly we construct the SageMaker model\n",
    "model_info = session.sagemaker_client.create_model(\n",
    "                                ModelName = model_name,\n",
    "                                ExecutionRoleArn = role,\n",
    "                                PrimaryContainer = primary_container)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 5: Test the trained model\n",
    "\n",
    "We will be skipping this step for now. We will still test our trained model but we are going to do it by using the deployed model, rather than setting up a batch transform job.\n",
    "\n",
    "## Step 6: Create and deploy the endpoint\n",
    "\n",
    "Now that we have trained and constructed a model it is time to build the associated endpoint and deploy it. As in the earlier steps, we first need to construct the appropriate configuration."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# As before, we need to give our endpoint configuration a name which should be unique\n",
    "endpoint_config_name = \"boston-xgboost-endpoint-config-\" + strftime(\"%Y-%m-%d-%H-%M-%S\", gmtime())\n",
    "\n",
    "# And then we ask SageMaker to construct the endpoint configuration\n",
    "endpoint_config_info = session.sagemaker_client.create_endpoint_config(\n",
    "                            EndpointConfigName = endpoint_config_name,\n",
    "                            ProductionVariants = [{\n",
    "                                \"InstanceType\": \"ml.m4.xlarge\",\n",
    "                                \"InitialVariantWeight\": 1,\n",
    "                                \"InitialInstanceCount\": 1,\n",
    "                                \"ModelName\": model_name,\n",
    "                                \"VariantName\": \"AllTraffic\"\n",
    "                            }])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And now that the endpoint configuration has been created we can deploy the endpoint itself.\n",
    "\n",
    "**NOTE:** When deploying a model you are asking SageMaker to launch an compute instance that will wait for data to be sent to it. As a result, this compute instance will continue to run until *you* shut it down. This is important to know since the cost of a deployed endpoint depends on how long it has been running for.\n",
    "\n",
    "In other words **If you are no longer using a deployed endpoint, shut it down!**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Again, we need a unique name for our endpoint\n",
    "endpoint_name = \"boston-xgboost-endpoint-\" + strftime(\"%Y-%m-%d-%H-%M-%S\", gmtime())\n",
    "\n",
    "# And then we can deploy our endpoint\n",
    "endpoint_info = session.sagemaker_client.create_endpoint(\n",
    "                    EndpointName = endpoint_name,\n",
    "                    EndpointConfigName = endpoint_config_name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Just like when we created a training job, SageMaker is now requisitioning and launching our endpoint. Since we can't do much until the endpoint has been completely deployed we can wait for it to finish."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "endpoint_dec = session.wait_for_endpoint(endpoint_name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 7: Use the model\n",
    "\n",
    "Now that our model is trained and deployed we can send test data to it and evaluate the results. Here, because our test data is so small, we can send it all using a single call to our endpoint. If our test dataset was larger we would need to split it up and send the data in chunks, making sure to accumulate the results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# First we need to serialize the input data. In this case we want to send the test data as a csv and\n",
    "# so we manually do this. Of course, there are many other ways to do this.\n",
    "payload = [[str(entry) for entry in row] for row in X_test.values]\n",
    "payload = '\\n'.join([','.join(row) for row in payload])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This time we use the sagemaker runtime client rather than the sagemaker client so that we can invoke\n",
    "# the endpoint that we created.\n",
    "response = session.sagemaker_runtime_client.invoke_endpoint(\n",
    "                                                EndpointName = endpoint_name,\n",
    "                                                ContentType = 'text/csv',\n",
    "                                                Body = payload)\n",
    "\n",
    "# We need to make sure that we deserialize the result of our endpoint call.\n",
    "result = response['Body'].read().decode(\"utf-8\")\n",
    "Y_pred = np.fromstring(result, sep=',')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To see how well our model works we can create a simple scatter plot between the predicted and actual values. If the model was completely accurate the resulting scatter plot would look like the line $x=y$. As we can see, our model seems to have done okay but there is room for improvement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.scatter(Y_test, Y_pred)\n",
    "plt.xlabel(\"Median Price\")\n",
    "plt.ylabel(\"Predicted Price\")\n",
    "plt.title(\"Median Price vs Predicted Price\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Delete the endpoint\n",
    "\n",
    "Since we are no longer using the deployed model we need to make sure to shut it down. Remember that you have to pay for the length of time that your endpoint is deployed so the longer it is left running, the more it costs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "session.sagemaker_client.delete_endpoint(EndpointName = endpoint_name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Optional: Clean up\n",
    "\n",
    "The default notebook instance on SageMaker doesn't have a lot of excess disk space available. As you continue to complete and execute notebooks you will eventually fill up this disk space, leading to errors which can be difficult to diagnose. Once you are completely finished using a notebook it is a good idea to remove the files that you created along the way. Of course, you can do this from the terminal or from the notebook hub if you would like. The cell below contains some commands to clean up the created files from within the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# First we will remove all of the files contained in the data_dir directory\n",
    "!rm $data_dir/*\n",
    "\n",
    "# And then we delete the directory itself\n",
    "!rmdir $data_dir"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "conda_pytorch_p36",
   "language": "python",
   "name": "conda_pytorch_p36"
  },
  "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.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}