2017_11_09_a.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exercises due by EOD 2017.11.09"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## goal"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "in this homework assignment we will focus on `aws lambda` functions and available triggers (specifically: cloudwatch scheduled events and `api` gateway calls)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## method of delivery"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "as mentioned in our first lecture, the method of delivery may change from assignment to assignment. we will include this section in every assignment to provide an overview of how we expect homework results to be submitted, and to provide background notes or explanations for \"new\" delivery concepts or methods."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "this week you will be submitting the results of your homework via upload to two different `s3` buckets. the first is one I created for you and will be used for question 1, and the second is the same homework bucket you have been using now for several weeks.\n",
    "\n",
    "summary:\n",
    "\n",
    "| exercise | deliverable                                 | method of delivery                                  |\n",
    "|----------|---------------------------------------------|-----------------------------------------------------|\n",
    "| 1        | daily alarm clock messages posted to `s3`   | upload to our `s3` bucket: `2017.fall.gu511.{GUID}` |\n",
    "| 2        | a url endpoint of a `lambda` function `api` | upload to your personal `s3` hw bucket              |"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# exercise 1: the world's worst alarm clock in `lambda`\n",
    "\n",
    "in previous lectures and homework, we used the linux `cron` program to schedule a recurring job to print \"wake up\" messages to our `s3` buckets. let's do that again, but this time utilizing serverless `lambda` functions and `CloudWatch` events.\n",
    "\n",
    "\n",
    "## 1.1: create the `lambda` function\n",
    "\n",
    "Create a `lambda` function with the following properties\n",
    "\n",
    "1. the trigger is a `CloudWatch` event executing the function every week day at 5 AM\n",
    "2. the runtime is `python 3.6` or above\n",
    "3. the code is simply copy-pasted from [`alarm_clock.py`](https://s3.amazonaws.com/shared.rzl.gu511.com/alarm_clock.py)\n",
    "\n",
    "\n",
    "## 1.2: test the `lambda` function\n",
    "\n",
    "test the function you just created with the following `json` event:\n",
    "\n",
    "```json\n",
    "{\n",
    "    \"message\": \"wake up!!!\",\n",
    "    \"bucket\": YOUR_BUCKET_NAME_HERE\n",
    "}\n",
    "```\n",
    "\n",
    "in the above, please replace `YOUR_BUCKET_NAME_HERE` with the name of the \"alarm clock bucket\" you used for the previous `alarm_clock.py` exercises (we set up a `cron` job to post to this bucket, you submitted a `what_i_ran.sh` file with this bucket hard-coded in it, and you sent us the name of that hw bucket along with the rest of that assignment).\n",
    "\n",
    "use this test to make sure that the function works and that it creates a file in the \"alarm clock\" bucket.\n",
    "\n",
    "*hint: it probably won't work until you...*\n",
    "\n",
    "\n",
    "## 1.3: fix permissions\n",
    "\n",
    "when you created your `lambda` function, you probably also created a new isolated `iam role` for this `lambda` function. when the event is received and the `lambda` function launches, the code is executed from within that `role`. this means that `iam role` needs permission to add items to that particular `s3` bucket.\n",
    "\n",
    "using the `s3` web console, navigate to the \"Permissions\" tab of the \"alarm clock\" bucket. on the permissions page, click the \"Bucket Policy\" button and add the following bucket policy `json` block to the policy editor (obviously, replace the `ALL_CAPS_WORDS` below with the appropriate value for your `lambda` function `iam role` and `s3` bucket):\n",
    "\n",
    "```json\n",
    "{\n",
    "    \"Sid\": \"LambdaPutObject\",\n",
    "    \"Action\": \"s3:PutObject\",\n",
    "    \"Effect\": \"Allow\",\n",
    "    \"Principal\": {\n",
    "        \"AWS\": [\n",
    "            \"arn:aws:iam::YOUR_AWS_ACCOUNT_NUM:role/service-role/YOUR_LAMBDA_FUNCTION_ROLE_NAME\"\n",
    "        ]\n",
    "    },\n",
    "    \"Resource\": \"arn:aws:s3:::YOUR_BUCKET_NAME/*\"\n",
    "}\n",
    "```\n",
    "\n",
    "for example, mine was\n",
    "\n",
    "```json\n",
    "{\n",
    "    \"Sid\": \"LambdaPutObject\",\n",
    "    \"Action\": \"s3:PutObject\",\n",
    "    \"Effect\": \"Allow\",\n",
    "    \"Principal\": {\n",
    "        \"AWS\": [\n",
    "            \"arn:aws:iam::336188965589:role/service-role/gu511_lambda_basic_execution\"\n",
    "        ]\n",
    "    },\n",
    "    \"Resource\": \"arn:aws:s3:::gu511.lamberty.io/*\"\n",
    "}\n",
    "```\n",
    "\n",
    "\n",
    "## 1.4: test again\n",
    "\n",
    "back on the `lambda` function's summary page, try testing the custom `json` event from above again. this time it should work -- if not, head to stack overflow and start debugging!\n",
    "\n",
    "\n",
    "## 1.5: fixing the cloudwatch event\n",
    "\n",
    "at this point, you should have\n",
    "\n",
    "1. a `lambda` function which expects and `event` object with a `message` and `bucket` element\n",
    "2. a `CloudWatch` trigger on that `lambda` function\n",
    "3. a `CloudWatch` rule which will yield an `event` every morning at the scheduled time\n",
    "\n",
    "there is one problem here -- the `event` that the `CloudWatch` rule you created will yield does not have `message` or `bucket` elements (our test version did, but that was hard-coded). let's fix that\n",
    "\n",
    "1. navigate to the `aws CloudWatch` service via the web console\n",
    "2. open the `CloudWatch event rule` you created for your `lambda` function\n",
    "    1. the *target* (your `lambda` function from above) should appear on the left\n",
    "3. click on your *target*'s \"Configure Input\" dropdown\n",
    "4. change the input type to \"Constant (JSON text)\"\n",
    "5. make the `json` text be `{\"message\": \"wake up!!!\", \"bucket\": YOUR_BUCKET_NAME_HERE}`\n",
    "\n",
    "\n",
    "## 1.6: wake me up before you go go\n",
    "\n",
    "at this point, you have a working alarm clock. good for you. but what about me?\n",
    "\n",
    "my alarm hasn't been working, so I need some help. I've created an `s3` bucket for each of you on *my* `aws` account, and your bucket name is\n",
    "\n",
    "```\n",
    "2017.fall.gu511.{GUID}\n",
    "```\n",
    "\n",
    "where `{GUID}` is replace by your Georgetown ID. for example, my GU ID is `rzl5`, and my bucket name would be `2017.fall.gu511.rzl5`.\n",
    "\n",
    "alter the `CloudWatch` event rule above to post wake up messages to this new bucket.\n",
    "\n",
    "\n",
    "##### there is no direct submission for this assignment -- we will verify work by seeing daily files added to the `2017.fall.gu511.{GUID}` buckets at 5AM EST"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# exercise 2: deploying a model as a `REST api`\n",
    "\n",
    "in this assignment we will take a trained and packaged random forest model and deploy it as a lambda function behind a RESTful `api`.\n",
    "\n",
    "\n",
    "## 2.1: reading background info\n",
    "\n",
    "### the model\n",
    "\n",
    "in a previous homework assignment we filled in the details on an exploratory notebook `ds_pipeline_template.ipynb`, and the end result of this process was a trained model for classifying someone's income based on a number of features. the solutions to that notebook are available in the neighboring `ds_pipeline_template_answers.ipynb` file.\n",
    "\n",
    "the end result of that notebook and modeling process is a recursive feature selector object (where the base is a random forest) and a subsequent trained random forest model. it is possible to conver all of that work (pre-processing, feature selection, and modelling) into specific `scikit-learn` transformers, and to have one unified process for both model *training* and future record *scoring*.\n",
    "\n",
    "I have made some changes to that overall process to do just that: streamline everything under the `scikit-learn` transformer `api` (all the preprocessing steps and the modelling steps). those changes are encapsulated in the neighboring `salarymodel/ds_pipeline_template_sklearn_only.ipynb`, which creates two objects:\n",
    "\n",
    "1. `preprocessor`: a pipeline which can be used to take records which matches the format of [the csv](http://archive.ics.uci.edu/ml/machine-learning-databases/adult/adult.data) for the [adult salary dataset](http://archive.ics.uci.edu/ml/datasets/Adult) and convert them into fully processed `numpy` arrays\n",
    "2. `modeller`: a feature selection and modelling pipeline that will take per-processed `numpy` records (like those created by the above) and predict the probability that a person earns more or less than 50K USD for their salary.\n",
    "\n",
    "\n",
    "### the deployment package\n",
    "\n",
    "while amazon provides users with basic `python` runtimes, non-base modules have to be included with the package. I have packaged up these extra libraries (`numpy`, `scipy`, `scikit-learn`) and pickled `scikit-learn pipeline`s along with the code required to create a `lambda` function.\n",
    "\n",
    "the `zip` archive which is `lambda`-function-ready is publicly available [on my `s3` bucket](https://s3.amazonaws.com/shared.rzl.gu511.com/salarymodel/salarymodel.zip). getting this `zip` file to a size that was acceptable while also not breaking the `scipy` binary executable and linkable `.so` files.\n",
    "\n",
    "\n",
    "## 2.2: creating the `lambda` function\n",
    "\n",
    "let's put that `zip` archive to work. create a new `lambda` function from scratch with the following properties (assume the default is acceptable unless otherwise noted):\n",
    "\n",
    "1. name it `salary_model`\n",
    "2. create a new role `salary_model_role`\n",
    "3. the runtime should be `python 3.6`\n",
    "4. the code entry type should be upload from `s3`\n",
    "5. the `s3` code url is https://s3.amazonaws.com/shared.rzl.gu511.com/salarymodel/salarymodel.zip\n",
    "6. the handler should be `salarymodel.handler`\n",
    "7. the memory value (see \"Basic Settings\") should be 256 MB\n",
    "8. the timeout should be set to 10 seconds\n",
    "\n",
    "\n",
    "## 2.3: testing this `lambda` function\n",
    "\n",
    "create a `lambda` test event `salarytest` with the following `json` event body:\n",
    "\n",
    "```json\n",
    "{\n",
    "    \"httpMethod\": \"GET\",\n",
    "    \"queryStringParameters\": {\n",
    "        \"age\": 52,\n",
    "        \"capital_gain\": 15024,\n",
    "        \"capital_loss\": 0,\n",
    "        \"education\": \"HS-grad\",\n",
    "        \"hours_per_week\": 40,\n",
    "        \"marital_status\": \"Married-civ-spouse\",\n",
    "        \"native_country\": \"United-States\",\n",
    "        \"occupation\": \"Exec-managerial\",\n",
    "        \"race\": \"White\",\n",
    "        \"relationship\": \"Wife\",\n",
    "        \"sex\": \"Female\",\n",
    "        \"workclass\": \"Self-emp-inc\"\n",
    "    }\n",
    "}\n",
    "```\n",
    "\n",
    "this test should *succeed* and return the following:\n",
    "\n",
    "```json\n",
    "{\n",
    "  \"statusCode\": \"200\",\n",
    "  \"body\": {\"score\": {\"<=50k\": 0.03, \">50k\": 0.97}}\",\n",
    "  \"headers\": {\n",
    "    \"Content-Type\": \"application/json\"\n",
    "  }\n",
    "}\n",
    "```\n",
    "\n",
    "verify that your test succeeds before moving on\n",
    "\n",
    "\n",
    "## 2.3: setting up an `api` gateway trigger\n",
    "\n",
    "big picture, we want users to be able to hit a single `api` endpoint and have this pre-trained model classify that record and respond to them. to do this, we will give our `lambda` function an `api` gateway trigger.\n",
    "\n",
    "on the `lambda` function's \"triggers\" tab, add a trigger with type \"API Gateway\" with the following properties:\n",
    "\n",
    "+ the name should be `salary_model`\n",
    "+ the security settings should be `Open`\n",
    "\n",
    "\n",
    "## 2.4: testing the `api` gateway\n",
    "\n",
    "in creating the trigger above, you will have created an `api` gateway object. we already tested our `lambda` function with a direct event; now let's go test our triggering gateway endpoint directly\n",
    "\n",
    "+ navigate to your new `api_gateway` element\n",
    "+ click on the \"Test\" box to try the following three tests (the query strings are multi-line for formatting only, put the contents on one line):\n",
    "\n",
    "| request type | query string | expected behavior |\n",
    "|-|-|-|\n",
    "| `GET` | `age=52&capital_gain=15024&capital_loss=0&education=HS-grad`<br>`&hours_per_week=40&marital_status=Married-civ-spouse`<br>`&native_country=United-States&occupation=Exec-managerial`<br>`&race=White&relationship=Wife&sex=Female&workclass=Self-emp-inc` | `{\"score\": {\"<=50k\": 0.03, \">50k\": 0.97}}` |\n",
    "| `GET`  | leave empty | `\"you must provide input record parameters\"` |\n",
    "| `POST` | leave empty | `\"Unsupported method \\\"POST\\\"\"` |\n",
    "\n",
    "make sure you pass all three tests before moving on.\n",
    "\n",
    "\n",
    "## 2.5: deploying the `api`\n",
    "\n",
    "at this point you have a successfully tested `api` which you can interact with via the web console (as we just did). to make it available to the outside world, you have to *deploy* it. let's do that now.\n",
    "\n",
    "+ navigate back to the main `salary_model api` gateway page\n",
    "+ *deploy* the `salary_model api` by clicking the \"Actions\" dropdown menu and selecting \"Deploy API\" and selecting the \"prod\" deployment stage.\n",
    "+ on the \"prod\" stage, navigate to your `/salary_model GET` endpoint\n",
    "+ find the url of this endpoint\n",
    "    + it should be https://dztalctwd6.execute-api.us-east-1.amazonaws.com/prod/salary_model\n",
    "    \n",
    "going forward, we will refer to the url above as simply `url`.\n",
    "\n",
    "make sure that you have an `api` which looks like the example above (ending in `/prod/salary_model`) before moving on.\n",
    "\n",
    "\n",
    "## 2.6: performing an `http GET` test\n",
    "\n",
    "if you replace `FILL_IN_YOUR_URL_HERE` with the url from 2.5, the following code *should* work -- verify that it does!\n",
    "\n",
    "```python\n",
    "import requests\n",
    "\n",
    "url = FILL_IN_YOUR_URL_HERE\n",
    "\n",
    "resp = requests.get(\n",
    "    url=url\n",
    "    params={\n",
    "        \"age\": 52,\n",
    "        \"capital_gain\": 15024,\n",
    "        \"capital_loss\": 0,\n",
    "        \"education\": \"HS-grad\",\n",
    "        \"hours_per_week\": 40,\n",
    "        \"marital_status\": \"Married-civ-spouse\",\n",
    "        \"native_country\": \"United-States\",\n",
    "        \"occupation\": \"Exec-managerial\",\n",
    "        \"race\": \"White\",\n",
    "        \"relationship\": \"Wife\",\n",
    "        \"sex\": \"Female\",\n",
    "        \"workclass\": \"Self-emp-inc\"\n",
    "    }\n",
    ")\n",
    "\n",
    "j = resp.json()\n",
    "print(j)\n",
    "\n",
    "assert j['score']['<=50k'] == 0.03\n",
    "assert j['score']['>50k'] == 0.97\n",
    "```\n",
    "\n",
    "\n",
    "## 2.7: sharing your url\n",
    "\n",
    "put the full url (`https://***********.execute-api.us-east-1.amazonaws.com/prod/salary_model`) into a raw text file called `salary_model_url.txt`.\n",
    "\n",
    "##### upload `salary_model_url.txt` to your `s3` homework bucket (the one you've used for the previous few homework assignments."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}