Make Notebook adjustments

* We now use the lfw-a dataset in the notebook. This is the smallest multi-class dataset provided on the dataset website. Multiple classes are needed for the model to work. * Corrected the WML Execution Command input-dir path. We now use /output/images. * Added table of contents. * Added conda-forge as a channel in the text for environment customization. * Various grammar and spelling fixes.

Author: pvaneck

notebooks/facial-recognition.ipynb

@@ -11,33 +11,41 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "This notebook contains steps and code to demonstrate how serverless computing can provide great benefit for AI data preprocessing. We demonstrate Face Recognition deep learning over Watson Machine Learning service, while letting IBM Cloud Function to do the data preparation phase. As we will show this makes an entire process up to 50 times faster comparing to running the same code without leveraging serverless computing.\n",
+ "This notebook contains steps and code to demonstrate how serverless computing can provide great benefit for AI data preprocessing. We demonstrate face recognition using deep learning over the Watson Machine Learning service, while letting IBM Cloud Functions do the data preparation phase. As we will show this makes an entire process up to 50 times faster comparing to running the same code without leveraging serverless computing.\n",
  "\n",
- "Our notebook is based on a blog <a href=\"https://hackernoon.com/building-a-facial-recognition-pipeline-with-deep-learning-in-tensorflow-66e7645015b8\" target=\"_blank\" rel=\"noopener no referrer\">Building a Facial Recognition Pipeline with Deep Learning in Tensorflow </a> written by Cole Murray who kindly allowed us to use code and text from his blog.\n",
+ "Our notebook is based on a blog <a href=\"https://hackernoon.com/building-a-facial-recognition-pipeline-with-deep-learning-in-tensorflow-66e7645015b8\" target=\"_blank\" rel=\"noopener no referrer\">Building a Facial Recognition Pipeline with Deep Learning in Tensorflow</a> written by Cole Murray who kindly allowed us to use code and text from his blog.\n",
  "\n",
- "This notebook introduces commands for getting data, training_definition persistance to Watson Machine Learning repository, model training, deployment and scoring.\n",
+ "This notebook introduces commands for interacting with your Watson Machine Learning service such as uploading training definitions and kicking off a training session.\n",
  "\n",
- "Some familiarity with Python is helpful. This notebook uses \n",
+ "Some familiarity with Python is helpful. This notebook uses:\n",
  "\n",
  "- Python 3 \n",
  "- <a href=\"https://dataplatform.cloud.ibm.com/docs/content/analyze-data/environments-parent.html\" target=\"_blank\" rel=\"noopener no referrer\">Watson Studio environments.</a>\n",
- "- IBM Cloud Functions\n",
+ "- <a href=\"https://cloud.ibm.com/openwhisk\" target=\"_blank\" rel=\"noopener no referrer\">IBM Cloud Functions</a>\n",
  "- <a href=\"https://github.com/pywren/pywren-ibm-cloud\" target=\"_blank\" rel=\"noopener no referrer\">PyWren for IBM Cloud</a>\n",
  "\n",
  "\n",
  "\n",
  "## Learning goals\n",
  "\n",
- "In this notebook, you will learn how to:\n",
+ "In this notebook, you will learn:\n",
  "\n",
- "- Work with Watson Machine Learning experiments to train Deep Learning models (Tensorflow)\n",
- "- Save trained models in the Watson Machine Learning repository\n",
- "- Deploy a trained model online and score\n",
- "- How IBM Cloud Functions can be used for data preparation phase\n",
- "- Value of PyWren for IBM Cloud\n",
+ "- How IBM Cloud Functions can be used for the data preparation phase\n",
+ "- The value of PyWren for IBM Cloud\n",
+ "- How to work with Watson Machine Learning to train Deep Learning models (TensorFlow + scikit-learn)\n",
+ "- How to retrieve and use models trained in WML\n",
  "\n",
+ "## Contents\n",
  "\n",
- "## Contents\n"
+ "1. [Set up related IBM Cloud Services](#setup)\n",
+ "2. [Dependencies installation](#dependencies-install)\n",
+ "3. [Configuration](#configuration)\n",
+ "4. [Preprocessing Data using Dlib and Docker](#preprocessing)\n",
+ "5. [Setup for WML](#wml-setup)\n",
+ "6. [Create the training definitions](#training-definitions)\n",
+ "7. [Train the model](#train)\n",
+ "8. [Work with the Trained Model](#work)\n",
+ "9. [Summary](#summary)\n"
  ]
  },
  {
@@ -87,25 +95,28 @@
  "metadata": {},
  "source": [
  "### 1.3 Create IBM Cloud Functions account\n",
- "Setup IBM Cloud Functions account as described here. Please follow all the steps and make sure you can run \"Hello World\" example based on Python code. This will assure your Cloud Functions service is running"
+ "Setup IBM Cloud Functions account as described here. Please follow all the steps and make sure you can run the \"Hello World\" example based on Python code. This will assure your Cloud Functions service is running."
  ]
  },
  {
  "cell_type": "markdown",
  "metadata": {},
  "source": [
+ "<a id=\"dependencies-install\"></a>\n",
  "## <span style=\"color:blue\"> 2. Dependencies installation </span>"
  ]
  },
  {
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "Install the needed libraries for the Face Recognition. \n",
- "\"dlib\" dependency need to be installed via new environment. Create new environment based on Python 3.5 and add dependency in the customizaion section, as follows\n",
+ "Install the needed libraries for the face recognition preprocessing.\n",
+ "The \"dlib\" dependency needs to be installed via new environment. Create a new environment based on Python 3.5 and add the dependency in the customization section as follows:\n",
  "\n",
+ " channels:\n",
+ " - conda-forge\n",
  " dependencies:\n",
- "  - dlib"
+ " - dlib"
  ]
  },
  {
@@ -139,8 +150,9 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
+ "<a id=\"configuration\"></a>\n",
  "## <span style=\"color:blue\">3. Configuration </span>\n",
- "This section explains how to configure services"
+ "This section explains how to configure the needed services."
  ]
  },
  {
@@ -149,7 +161,7 @@
  "source": [
  "### 3.1 Setup a bucket in IBM Cloud Object Storage\n",
  "\n",
- "You need an IBM COS bucket, which you will use to store the input data. If you don't have any existing bucket, please navigate to IBM COS Dashboard UI and create new bucket in the region you prefer. Make sure you copy the correct endpoint for the bucket\n",
+ "You need an IBM COS bucket which you will use to store the input data. If you don't know of any of your existing buckets or would like like to create a new one, please navigate to your <a href=\"https://cloud.ibm.com/resources\" target=\"_blank\" rel=\"noopener no referrer\">cloud resource list</a>, then find and select your storage instance. From here, you will be able to view all your buckets and can create a new bucket in the region you prefer. Make sure you copy the correct endpoint for the bucket from the `Endpoint` tab of this COS service dashboard.\n",
  "\n",
  "**Note:** The bucket names must be unique."
  ]
@@ -179,9 +191,9 @@
  "metadata": {},
  "source": [
  "### 3.2 COS Connection\n",
- "You need obtain both credentials to the Cloud Functions and COS.\n",
+ "Now connect to the Cloud Object Storage service by first obtaining your credentials.\n",
  "\n",
- "You can find COS credentials in your COS instance dashboard under the Service credentials tab.\n",
+ "You can find COS credentials in your COS instance dashboard under the `Service credentials` tab.\n",
  "Note: the HMAC key, described in set up the environment is included in these credentials.\n",
  "\n"
  ]
@@ -207,15 +219,6 @@
  "}"
  ]
  },
- {
- "cell_type": "markdown",
- "metadata": {},
- "source": [
- "Define the endpoint.\n",
- "\n",
- "To do this, go to the **Endpoint** tab in the COS instance's dashboard to get the endpoint information, then enter it in the cell below:"
- ]
- },
  {
  "cell_type": "markdown",
  "metadata": {},
@@ -237,7 +240,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "Install the boto library. This library allows Python developers to manage Cloud Object Storage (COS)."
+ "Install the boto library if necessary. This library allows Python developers to manage IBM Cloud Object Storage (COS). However, most environments on Watson Studio have this preinstalled."
  ]
  },
  {
@@ -253,7 +256,7 @@
  "metadata": {},
  "outputs": [],
  "source": [
- "# Run the command if ibm_boto3 is not installed.\n",
+ "# Uncomment and run the following command if ibm_boto3 is not installed.\n",
  "# !pip install ibm-cos-sdk"
  ]
  },
@@ -263,7 +266,7 @@
  "metadata": {},
  "outputs": [],
  "source": [
- "# Install the boto library.\n",
+ "# Import the boto library.\n",
  "import ibm_boto3\n",
  "from ibm_botocore.client import Config"
  ]
@@ -296,23 +299,14 @@
  "source": [
  "### 3.3 Verify you can access your COS Bucket\n",
  "\n",
- "If you fail to access your bucket, make sure you use correct bucket name and endpoint URL for the region where bucket was created"
+ "If you fail to access your bucket, make sure you use the correct bucket name and endpoint URL for the region where the bucket was created. If you see no errors after running the following cell, you are good to go."
  ]
  },
  {
  "cell_type": "code",
- "execution_count": 9,
- "metadata": {},
- "outputs": [
- {
- "name": "stdout",
- "output_type": "stream",
- "text": [
- "Error. Bucket can not be empty. Please create bucket in COS Dashboard UI and update 'BUCKET'\n",
- "Error. Please create ibm_boto3 instance\n"
- ]
- }
- ],
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
  "source": [
  "try: BUCKET\n",
  "except NameError: BUCKET = None\n",
@@ -327,7 +321,7 @@
  " print(\"Error. Please create ibm_boto3 instance\")\n",
  "\n",
  "if cos and not cos.Bucket(BUCKET) in cos.buckets.all():\n",
- " print (\"Bucket not found. Please make sure cos_endpoint target the region of the bucket\")"
+ " print (\"Error. Bucket not found. Please make sure cos_endpoint targets the region of the bucket\")"
  ]
  },
  {
@@ -341,7 +335,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "Obtain api key and endpoint to the IBM Cloud Functions service. Navigate the \"API Key\" menu and copy namespace, host and key. Make sure to add \"https://\" to the host"
+ "Obtain the API key and endpoint to the <a href=\"https://cloud.ibm.com/openwhisk\" target=\"_blank\" rel=\"noopener no referrer\">IBM Cloud Functions service</a>. Navigate to `Getting Started` > `API Key` from the side menu and copy the values for \"Current Namespace\", \"Host\" and \"Key\" into the config below. Make sure to add \"https://\" to the host when adding it as the endpoint."
  ]
  },
  {
@@ -365,7 +359,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "PyWren engine requires it's server side component to be deployed in advance. This step creates a new IBM Cloud Function function with PyWren server side runtime. This action will be used internally by PyWren during execution phases."
+ "The PyWren engine requires its server side component to be deployed in advance. This step creates a new IBM Cloud Functions function with the PyWren server side runtime. This action will be used internally by PyWren during execution phases."
  ]
  },
  {
@@ -382,6 +376,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
+ "<a id=\"preprocessing\"></a>\n",
  "## <span style=\"color:blue\">4. Preprocessing Data using Dlib and Docker</span>"
  ]
  },
@@ -391,7 +386,7 @@
  "source": [
  "### 4.1 Upload input data into IBM Cloud Object Storage\n",
  "\n",
- "Your COS Bucket should contain raw dataset of images by following structure:\n",
+ "Your COS Bucket should contain the raw dataset of images with the following structure:\n",
  "\n",
  " Directory Structure\n",
  " ├── Tyra_Banks\n",
@@ -401,17 +396,17 @@
  " │ ├── Tyron_Garner_0001.jpg\n",
  " │ └── Tyron_Garner_0002.jpg\n",
  " \n",
- "If you don't have any images, we will demonstrate how to use the [LFW](http://vis-www.cs.umass.edu/lfw/) (Labeled Faces in the Wild) dataset as training data. Below are instructions how you can upload this dataset into your private COS bucket. \n",
+ "If you don't have any images, we will demonstrate how to use the [LFW](http://vis-www.cs.umass.edu/lfw/) (Labeled Faces in the Wild) dataset as training data. Below are instructions how you can upload this dataset into your private COS bucket.\n",
  "\n",
- "**You should run this only once. If images were already created in the previos run you can skip this section**"
+ "**You should run this only once. If images were already created in any previous run, you can skip this section.**"
  ]
  },
  {
  "cell_type": "markdown",
  "metadata": {},
  "source": [
  "The following step copies images from Labeled Faces in the Wild into your COS bucket.\n",
- "We demonstrate with small data set of 6MB. If you wish to use entire data set, then use \n",
+ "We demonstrate with small data set of about 14MB. If you wish to use entire data set, then use \n",
  "\n",
  " url = \"http://vis-www.cs.umass.edu/lfw/lfw.tgz\""
  ]
@@ -456,9 +451,9 @@
  "\n",
  " for p in procs:\n",
  " p.join()\n",
- " \n",
  "\n",
- "url = \"http://vis-www.cs.umass.edu/lfw/lfw-bush.tgz\"\n",
+ "\n",
+ "url = \"http://vis-www.cs.umass.edu/lfw/lfw-a.tgz\"\n",
  "extractFromStream(url, cos, \"images\")\n"
  ]
  },
@@ -476,10 +471,12 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "### 4.2 Data preprocessing with serveless\n",
+ "### 4.2 Data preprocessing with serverless\n",
+ "\n",
+ "Below, you’ll preprocess the images before passing them into the FaceNet model. Image pre-processing in a facial recognition context typically solves a few problems. These problems range from lighting differences, occlusion, alignment, and segmentation. Below, you’ll address segmentation and alignment.\n",
  "\n",
- "Below, you’ll pre-process the images before passing them into the FaceNet model. Image pre-processing in a facial recognition context typically solves a few problems. These problems range from lighting differences, occlusion, alignment, segmentation. Below, you’ll address segmentation and alignment.\n",
  "First, you’ll solve the segmentation problem by finding the largest face in an image. This is useful as our training data does not have to be cropped for a face ahead of time.\n",
+ "\n",
  "Second, you’ll solve alignment. In photographs, it is common for a face to not be perfectly center aligned with the image. To standardize input, you’ll apply a transform to center all images based on the location of eyes and bottom lip.\n"
  ]
  },
@@ -491,7 +488,7 @@
  "\n",
  "Upload dlib’s face landmark predictor into your COS bucket. You’ll use this face landmark predictor to find the location of the inner eyes and bottom lips of a face in an image. These coordinates will be used to center align the image.\n",
  "\n",
- "**You should run this only once. If preictor was already created in the previos run you can skip this section**\n"
+ "**You should run this only once. If the predictor was already created in a previous run, you can skip this section.**\n"
  ]
  },
  {
@@ -640,7 +637,7 @@
  "\n",
  "Using Dlib, you detected the largest face in an image and aligned the center of the face by the inner eyes and bottom lip. This alignment is a method for standardizing each image for use as feature input.\n",
  "\n",
- "Verify that images were processed with dlib"
+ "Verify that images were processed with dlib:"
  ]
  },
  {
@@ -658,6 +655,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
+ "<a id=\"wml-setup\"></a>\n",
  "## <span style=\"color:blue\">5. Setup for WML</span>\n",
  "\n",
  "Now that we've preprocessed the data, we’ll generate vector embeddings of each identity. These embeddings can then be used as input to a classification, regression, or clustering task. We will use TensorFlow to create the embeddings and then scikit-learn to create the classifier with these embeddings. However, before we do all this, some preliminary setup is needed.\n",
@@ -915,7 +913,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "<a id=\"model\"></a>\n",
+ "<a id=\"training-definitions\"></a>\n",
  "## <span style=\"color:blue\">6. Create the training definitions</span>\n",
  "\n",
  "With us now connected to our WML service instance, we can now create the training definitions.\n",
@@ -959,7 +957,7 @@
  " client.repository.DefinitionMetaNames.EXECUTION_COMMAND: \" \\\n",
  " python3 train_classifier.py \\\n",
  " --model-path $DATA_DIR/pretrained-model/20180402-114759.pb \\\n",
- " --input-dir $DATA_DIR/processed-images \\\n",
+ " --input-dir $DATA_DIR/output/images \\\n",
  " --output-path $RESULT_DIR/output-classifier.pkl \\\n",
  " --num-epochs 3\"\n",
  "}"
@@ -991,7 +989,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "The files in this zip file can be viewed in the GitHub <a href=\"https://github.com/IBM/data-pre-processing-with-pywren/tree/master/data/code\" target=\"_blank\" rel=\"noopener noreferrer\">repository</a>"
+ "The files in this zip file can be viewed in the GitHub <a href=\"https://github.com/IBM/data-pre-processing-with-pywren/tree/master/data/code\" target=\"_blank\" rel=\"noopener noreferrer\">repository</a>."
  ]
  },
  {
@@ -1384,7 +1382,7 @@
  "cell_type": "markdown",
  "metadata": {},
  "source": [
- "In this notebook, we used PyWren with IBM Cloud Functions to increase preprocessing performance and stored the resulting images in an IBM Cloud Object Storage bucket. From here, we used this bucket along with IBM Watson Machine Learning to create embeddings of each identity using a pretrained TensorFlow FaceNet model, and then create a custom face classifer. "
+ "In this notebook, we used PyWren with IBM Cloud Functions to increase preprocessing performance and stored the resulting images in an IBM Cloud Object Storage bucket. From here, we used this bucket along with IBM Watson Machine Learning to create embeddings of each identity using a pretrained TensorFlow FaceNet model, and then created a custom face classifer. "
  ]
  },
  {
@@ -1412,7 +1410,7 @@
  "source": [
  "### Authors\n",
  "\n",
- "**Gil Vernik?**\n",
+ "**Gil Vernik**\n",
  "\n",
  "**Paul Van Eck**"
  ]