<commit_before>﻿<a name="HOLTop"></a>
# Building an Intelligent Application using Cortana Analytics Machine Learning APIs #

---

<a name="Overview"></a>
## Overview ##

Machine learning uses computers to run predictive models that learn from existing data in order to forecast future behaviors, outcomes, and trends.

These forecasts or predictions from machine learning can make apps and devices smarter. Azure Machine Learning APIs are ready-to-use APIs that allow you to harness the power of machine learning without requiring you to be a data scientist.
The Recommendations API built with Microsoft Azure Machine Learning helps your customer discover items in your catalog. Customer activity in your digital store is used to recommend items and to improve conversion in your digital store.

A machine learning model is an abstraction of the question you're trying to answer or the outcome you want to predict. Models are trained and evaluated from existing data.

This module includes building an Azure ML Recommendations model, using the results generated by the model to power recommendations on the e-commerce site. You will learn about recommendations systems, natural language processing and how to leverage face and emotion detection.


<a name="Objectives"></a>
### Objectives ###
In this module, you'll see how to:

- Create an Azure Machine Learning Recommendations model
- Analyze the users’ comments using Text Analytics
- Recognize users' emotions by their faces in an image

<a name="Prerequisites"></a>
### Prerequisites ###

The following is required to complete this module:

- [Visual Studio Community 2015][1] or greater.

[1]: https://www.visualstudio.com/products/visual-studio-community-vs

<a name="Setup"></a>
### Setup ###
In order to run the exercises in this module, you'll need to set up your environment first.

1. Open Windows Explorer and go to the module's **Source** folder.
1. Right-click **Setup.cmd** and select **Run as administrator** to launch the setup process that will configure your environment and install the Visual Studio code snippets for this module.
1. If the User Account Control dialog box is shown, confirm the action to proceed.

> **Note:** Make sure you have checked all the dependencies for this module before running the setup.

<a name="CodeSnippets"></a>
### Using the Code Snippets ###

Throughout the module document, you'll be instructed to insert code blocks. For your convenience, most of this code is provided as Visual Studio Code Snippets, which you can access from within Visual Studio 2015 to avoid having to add it manually.

>**Note**: Each exercise is accompanied by a starting solution located in the **Begin** folder of the exercise that allows you to follow each exercise independently of the others. Please be aware that the code snippets that are added during an exercise are missing from these starting solutions and may not work until you have completed the exercise. Inside the source code for an exercise, you'll also find an **End** folder containing a Visual Studio solution with the code that results from completing the steps in the corresponding exercise. You can use these solutions as guidance if you need additional help as you work through this module.

---

<a name="Exercises"></a>
## Exercises ##
This module includes the following exercises:

1. [Adding Recommendations to your app](#Exercise1)
1. [Analyzing the users’ comments using Text Analytics](#Exercise2)
1. [Recognize users' emotions by the faces in an image](#Exercise3)

Estimated time to complete this module: **60 minutes**

>**Note:** When you first start Visual Studio, you must select one of the predefined settings collections. Each predefined collection is designed to match a particular development style and determines window layouts, editor behavior, IntelliSense code snippets, and dialog box options. The procedures in this module describe the actions necessary to accomplish a given task in Visual Studio when using the **General Development Settings** collection. If you choose a different settings collection for your development environment, there may be differences in the steps that you should take into account.

<a name="Exercise1"></a>
### Exercise 1: Adding Recommendations to your app ###

Microsoft Azure Machine Learning's Recommendations supports 3 common scenarios:
- **Frequently Bought Together (FBT) Recommendations**
	In this scenario the recommendations engine will recommend items that are likely to be purchased together in the same transaction with a particular item.

- **Item to Item Recommendations**
	A common scenario that uses this capability, is "people who visited/clicked this item, also visited/clicked this other item".

- **Customer to Item Recommendations**
	Given a customer's prior activity, it is possible to recommend items that the customer may be interested in.
	For instance, given all movies watched by a customer, it is possible to recommend additional content that may be of interest to the customer.

In this exercise, you'll set up and integrate the [Recommendations API](http://gallery.cortanaanalytics.com/MachineLearningAPI/Recommendations-2) in your website.
You will start building a Recommendations model and then, use the results generated by the model to power recommendations on the e-commerce site.

<a name="Ex1Task1"></a>
#### Task 1 - Signing up for the Recommendations API ####

In this task, you'll sign up for the Recommendations API service, and create a recommendations model.

1. You should sign up for the **Recommendations API** service. Go to the **Cortana Analytics Gallery** at http://gallery.cortanaanalytics.com/ and go to the **Machine Learning APIs** section.

1. Select the **Recommendations API**. Notice the Documentation and Sample links.

1. Click **Sign Up**. This link will take you to the Data Market, where you can sign up for the service.

1. Select a plan. You may select the **free tier for 10,000 transactions/month**. This is a free plan, so it won't require any other information (credit card, etc.) You will need a Microsoft Account to sign up for the service. If you don’t have one, you can create a Microsoft Account at no additional cost.

1. After you sign up for Recommendations, you'll be given an **API Key**. You can always see this key at https://datamarket.azure.com/account. Copy this key, as you'll need it when creating your first model.

	![Azure Marketplace](Images/ex1-task1-datamarket-key.png?raw=true "Azure Marketplace")

	_Azure Marketplace_

<a name="Ex1Task2"></a>
#### Task 2 - Creating a recommendations model ####

**Note:** If you did not complete tasks 1, you may use the following account information to continue the exercise:

|Account            |   API Key 
|-------------------|-------------------
| ms<EMAIL> | rkEVmRRVZMr2qrabbjkUJ+L0xOJrpYmuCCHkaCLWSFo
| <EMAIL> | b8zlkjoEZuu3j9t3IY6dQmBI/CEzwieKmpkTGpiDYaU
| <EMAIL> | Sl9CEorkLMlygauAzH84ywYnpyA4QXPuf3GeA+dMc+c
| <EMAIL>  | wnwBVkXBtQOMIsgH6tFNr/Y3hzXbYlvtmDMXuploDRw
| <EMAIL>  | 6nEF6cb7EH7mWwxFZ09h+YQBaMjac4fnWFeYQD2YX+0
| <EMAIL> |  lHYQfBQTRbLCnQI3Cl/7cESt+59cwfw5LK03nPXq96c
| <EMAIL> | SWKry3f56rl7dhR+dO1djw7u6JO7GaHbjcPkce3TV70
| <EMAIL> | Po9vQpZo2MipUwGuNbuYXvSmBS3kI/gv13tvk5ukQFg
| <EMAIL> | QeBR3r66lg9ydt3vOdYhlGYmSddco6heuXRlj18pv6w
| <EMAIL> | wyzAlOoVkm3zSLAjnaEjiUtbZgc5bbxEcHuYdD3AWNA
| <EMAIL> | eTrjrXRCIlc88hMTuuOKxQNXg6igeqtmj+XmgPocaTc
| <EMAIL> | ca7W7d6751UQ6LJH6EISJZDpFSW8vinQM8M9SpheKLE
| <EMAIL> | 8OuwzTTdF3Xjh0JrKAR6Wqve7uv8ESo9lDR1lpZuRqM
| <EMAIL> | 36zHNj4TJD5PABWPz5+fm0xkcY1stHXwXmKAcK4V6d0
| <EMAIL> | LQDulWPordHQBOErEuM64pkHKPpzn8lAe1Lr4JRshtY
 

As mentioned, a Machine Learning Recommendations API was created using Azure Machine Learning by the data scientists at Microsoft.

Now you, as a developer can take advantage of this API and do not have to worry about the details of how to actually build a model. You can take advantage of one that is already created.

In order to build a model, the engine will need two pieces of information, a catalog file, and a usage file. Usually you would query your transactions database for this information. In this case, we have provided sample data.

You simply create a "Recommendations Model" via the API.  The model requires a few things:
- You need your password and API key in order to authenticate to the API
- You create a "project" or model in the API
- You upload 2 sets of data to that project:
	- Your product catalog
	- Your usage information - what customers have done
- The last step is to train the model.

In this task, you have two alternatives to create the recommendations model. You can either use the sample app we provide, or you can use the Recommendations web UI.

##### Alternative: using the Recommendations UI #####

You can set up your model using the [Recommendations UI (Beta)](http://recommendations.azurewebsites.net/) and following three simple steps:

1. In the [Recommendations UI](http://recommendations.azurewebsites.net/) site, provide a name for the model and then click **Add Project**.

1. Add a Catalog file: use the **catalog_small.txt** one within the **Resources** folder located at **Source / Ex1 / Begin / RecommendationsSample**.

1. Add a Usage file: use the **usage_data.txt** one within the **Resources** folder located at **Source / Ex1 / Begin / RecommendationsSample**.

1. Create a build: we created a **Recommendation** build type.

	![Recommendations UI](Images/ex1-task1-recommendations-ui.png?raw=true "Recommendations UI")

	_Recommendations UI_
	
##### Using the Console app #####

1. Open in Visual Studio the **RecommendationsSample.sln** solution located at **Source / Ex1 / Begin / RecommendationsSample** folder.

1. Open the **SampleApp.cs** file. The following tasks are going to be executed:
	- Create a Model
	- Add a catalog file
	- Add a usage file
	- Trigger a build for the Model
	- Get a recommendation based on a pair of items

1. Replace the values for the **accountEmail** and **accountKey** fields with your email and the key from the previous task.

1. Run the solution and take note of the **Model Id** that is shown when the application finishes, you'll need it for the following task.



<a name="Ex1Task3"></a>
#### Task 3 - Updating your website to get recommendations ####

In this task, you'll update the PartsUnlimited website to use the Recommendations API. To learn more, go to: https://azure.microsoft.com/en-us/documentation/articles/machine-learning-recommendation-api-documentation/

1. Open in Visual Studio the **PartsUnlimited.sln** solution located at **Source / Ex1 / Begin / PartsUnlimited** folder.

1. Open the **config.json** file located in the **PartsUnlimited** website.

1. Set the AzureMLRecommendations **AccountEmail**, **AccountKey** and **ModelId** settings with the values that you got from the previous task.

1. Now set the Azure DocumentDB **Endpoint** and **AuthKey** using the _URI_ and _Primary Key_ that you obtained while creating it in the [Creating the DocumentDB database](../Module1-IntelligentApp#task-1---creating-the-documentdb-database) module. If you do not have them, you can use these credentials:

 URL: 
 https://data-module3.documents.azure.com:443/

 Key: 
 <KEY>

1. Open the **AzureMLRecommendationEngine.cs** file located in the **Recommendations** folder.

1. Check the **GetRecommendationsAsync** method. Get recommendations of the active build of type "Recommendation" or "Fbt" based on a list of seeds (input) items. The response includes one entry per recommended item, including the Rating of the recommendation; higher number means higher confidence. This is what the product recommendation HTTP request looks like:

	````
	HTTP GET method
	<rootURI>/ItemRecommend?modelId=%27<modelId>%27&itemIds=%27<itemId>%27&numberOfResults=<int>&includeMetadata=<bool>&apiVersion=%271.0%27
	````<commit_msg>Since Client UI is first, changed wording.<commit_after>﻿<a name="HOLTop"></a>
# Building an Intelligent Application using Cortana Analytics Machine Learning APIs #

---

<a name="Overview"></a>
## Overview ##

Machine learning uses computers to run predictive models that learn from existing data in order to forecast future behaviors, outcomes, and trends.

These forecasts or predictions from machine learning can make apps and devices smarter. Azure Machine Learning APIs are ready-to-use APIs that allow you to harness the power of machine learning without requiring you to be a data scientist.
The Recommendations API built with Microsoft Azure Machine Learning helps your customer discover items in your catalog. Customer activity in your digital store is used to recommend items and to improve conversion in your digital store.

A machine learning model is an abstraction of the question you're trying to answer or the outcome you want to predict. Models are trained and evaluated from existing data.

This module includes building an Azure ML Recommendations model, using the results generated by the model to power recommendations on the e-commerce site. You will learn about recommendations systems, natural language processing and how to leverage face and emotion detection.


<a name="Objectives"></a>
### Objectives ###
In this module, you'll see how to:

- Create an Azure Machine Learning Recommendations model
- Analyze the users’ comments using Text Analytics
- Recognize users' emotions by their faces in an image

<a name="Prerequisites"></a>
### Prerequisites ###

The following is required to complete this module:

- [Visual Studio Community 2015][1] or greater.

[1]: https://www.visualstudio.com/products/visual-studio-community-vs

<a name="Setup"></a>
### Setup ###
In order to run the exercises in this module, you'll need to set up your environment first.

1. Open Windows Explorer and go to the module's **Source** folder.
1. Right-click **Setup.cmd** and select **Run as administrator** to launch the setup process that will configure your environment and install the Visual Studio code snippets for this module.
1. If the User Account Control dialog box is shown, confirm the action to proceed.

> **Note:** Make sure you have checked all the dependencies for this module before running the setup.

<a name="CodeSnippets"></a>
### Using the Code Snippets ###

Throughout the module document, you'll be instructed to insert code blocks. For your convenience, most of this code is provided as Visual Studio Code Snippets, which you can access from within Visual Studio 2015 to avoid having to add it manually.

>**Note**: Each exercise is accompanied by a starting solution located in the **Begin** folder of the exercise that allows you to follow each exercise independently of the others. Please be aware that the code snippets that are added during an exercise are missing from these starting solutions and may not work until you have completed the exercise. Inside the source code for an exercise, you'll also find an **End** folder containing a Visual Studio solution with the code that results from completing the steps in the corresponding exercise. You can use these solutions as guidance if you need additional help as you work through this module.

---

<a name="Exercises"></a>
## Exercises ##
This module includes the following exercises:

1. [Adding Recommendations to your app](#Exercise1)
1. [Analyzing the users’ comments using Text Analytics](#Exercise2)
1. [Recognize users' emotions by the faces in an image](#Exercise3)

Estimated time to complete this module: **60 minutes**

>**Note:** When you first start Visual Studio, you must select one of the predefined settings collections. Each predefined collection is designed to match a particular development style and determines window layouts, editor behavior, IntelliSense code snippets, and dialog box options. The procedures in this module describe the actions necessary to accomplish a given task in Visual Studio when using the **General Development Settings** collection. If you choose a different settings collection for your development environment, there may be differences in the steps that you should take into account.

<a name="Exercise1"></a>
### Exercise 1: Adding Recommendations to your app ###

Microsoft Azure Machine Learning's Recommendations supports 3 common scenarios:
- **Frequently Bought Together (FBT) Recommendations**
	In this scenario the recommendations engine will recommend items that are likely to be purchased together in the same transaction with a particular item.

- **Item to Item Recommendations**
	A common scenario that uses this capability, is "people who visited/clicked this item, also visited/clicked this other item".

- **Customer to Item Recommendations**
	Given a customer's prior activity, it is possible to recommend items that the customer may be interested in.
	For instance, given all movies watched by a customer, it is possible to recommend additional content that may be of interest to the customer.

In this exercise, you'll set up and integrate the [Recommendations API](http://gallery.cortanaanalytics.com/MachineLearningAPI/Recommendations-2) in your website.
You will start building a Recommendations model and then, use the results generated by the model to power recommendations on the e-commerce site.

<a name="Ex1Task1"></a>
#### Task 1 - Signing up for the Recommendations API ####

In this task, you'll sign up for the Recommendations API service, and create a recommendations model.

1. You should sign up for the **Recommendations API** service. Go to the **Cortana Analytics Gallery** at http://gallery.cortanaanalytics.com/ and go to the **Machine Learning APIs** section.

1. Select the **Recommendations API**. Notice the Documentation and Sample links.

1. Click **Sign Up**. This link will take you to the Data Market, where you can sign up for the service.

1. Select a plan. You may select the **free tier for 10,000 transactions/month**. This is a free plan, so it won't require any other information (credit card, etc.) You will need a Microsoft Account to sign up for the service. If you don’t have one, you can create a Microsoft Account at no additional cost.

1. After you sign up for Recommendations, you'll be given an **API Key**. You can always see this key at https://datamarket.azure.com/account. Copy this key, as you'll need it when creating your first model.

	![Azure Marketplace](Images/ex1-task1-datamarket-key.png?raw=true "Azure Marketplace")

	_Azure Marketplace_

<a name="Ex1Task2"></a>
#### Task 2 - Creating a recommendations model ####

**Note:** If you did not complete tasks 1, you may use the following account information to continue the exercise:

|Account            |   API Key 
|-------------------|-------------------
| <EMAIL> | rkEVmRRVZMr2qrabbjkUJ+L0xOJrpYmuCCHkaCLWSFo
| <EMAIL> | b8zlkjoEZuu3j9t3IY6dQmBI/CEzwieKmpkTGpiDYaU
| <EMAIL> | Sl9CEorkLMlygauAzH84ywYnpyA4QXPuf3GeA+dMc+c
| <EMAIL>  | wnwBVkXBtQOMIsgH6tFNr/Y3hzXbYlvtmDMXuploDRw
| <EMAIL>  | 6nEF6cb7EH7mWwxFZ09h+YQBaMjac4fnWFeYQD2YX+0
| <EMAIL> |  lHYQfBQTRbLCnQI3Cl/7cESt+59cwfw5LK03nPXq96c
| <EMAIL> | SWKry3f56rl7dhR+dO1djw7u6JO7GaHbjcPkce3TV70
| <EMAIL> | Po9vQpZo2MipUwGuNbuYXvSmBS3kI/gv13tvk5ukQFg
| <EMAIL> | QeBR3r66lg9ydt3vOdYhlGYmSddco6heuXRlj18pv6w
| <EMAIL> | wyzAlOoVkm3zSLAjnaEjiUtbZgc5bbxEcHuYdD3AWNA
| <EMAIL> | eTrjrXRCIlc88hMTuuOKxQNXg6igeqtmj+XmgPocaTc
| <EMAIL> | ca7W7d6751UQ6LJH6EISJZDpFSW8vinQM8M9SpheKLE
| <EMAIL> | 8OuwzTTdF3Xjh0JrKAR6Wqve7uv8ESo9lDR1lpZuRqM
| <EMAIL> | 36zHNj4TJD5PABWPz5+fm0xkcY1stHXwXmKAcK4V6d0
| <EMAIL> | LQDulWPordHQBOErEuM64pkHKPpzn8lAe1Lr4JRshtY
 

As mentioned, a Machine Learning Recommendations API was created using Azure Machine Learning by the data scientists at Microsoft.

Now you, as a developer can take advantage of this API and do not have to worry about the details of how to actually build a model. You can take advantage of one that is already created.

In order to build a model, the engine will need two pieces of information, a catalog file, and a usage file. Usually you would query your transactions database for this information. In this case, we have provided sample data.

You simply create a "Recommendations Model" via the API.  The model requires a few things:
- You need your password and API key in order to authenticate to the API
- You create a "project" or model in the API
- You upload 2 sets of data to that project:
	- Your product catalog
	- Your usage information - what customers have done
- The last step is to train the model.

In this task, you have two alternatives to create the recommendations model. You can either use the sample app we provide, or you can use the Recommendations web UI.

##### Using the Recommendations UI #####

You can set up your model using the [Recommendations UI (Beta)](http://recommendations.azurewebsites.net/) and following three simple steps:

1. In the [Recommendations UI](http://recommendations.azurewebsites.net/) site, provide a name for the model and then click **Add Project**.

1. Add a Catalog file: use the **catalog_small.txt** one within the **Resources** folder located at **Source / Ex1 / Begin / RecommendationsSample**.

1. Add a Usage file: use the **usage_data.txt** one within the **Resources** folder located at **Source / Ex1 / Begin / RecommendationsSample**.

1. Create a build: we created a **Recommendation** build type.

	![Recommendations UI](Images/ex1-task1-recommendations-ui.png?raw=true "Recommendations UI")

	_Recommendations UI_
	
##### Alternative: Using the sample app #####

1. Open in Visual Studio the **RecommendationsSample.sln** solution located at **Source / Ex1 / Begin / RecommendationsSample** folder.

1. Open the **SampleApp.cs** file. The following tasks are going to be executed:
	- Create a Model
	- Add a catalog file
	- Add a usage file
	- Trigger a build for the Model
	- Get a recommendation based on a pair of items

1. Replace the values for the **accountEmail** and **accountKey** fields with your email and the key from the previous task.

1. Run the solution and take note of the **Model Id** that is shown when the application finishes, you'll need it for the following task.


<a name="Ex1Task3"></a>
#### Task 3 - Updating your website to get recommendations ####

In this task, you'll update the PartsUnlimited website to use the Recommendations API. To learn more, go to: https://azure.microsoft.com/en-us/documentation/articles/machine-learning-recommendation-api-documentation/

1. Open in Visual Studio the **PartsUnlimited.sln** solution located at **Source / Ex1 / Begin / PartsUnlimited** folder.

1. Open the **config.json** file located in the **PartsUnlimited** website.

1. Set the AzureMLRecommendations **AccountEmail**, **AccountKey** and **ModelId** settings with the values that you got from the previous task.

1. Now set the Azure DocumentDB **Endpoint** and **AuthKey** using the _URI_ and _Primary Key_ that you obtained while creating it in the [Creating the DocumentDB database](../Module1-IntelligentApp#task-1---creating-the-documentdb-database) module. If you do not have them, you can use these credentials:

 URL: 
 https://data-module3.documents.azure.com:443/

 Key: 
 <KEY>

1. Open the **AzureMLRecommendationEngine.cs** file located in the **Recommendations** folder.

1. Check the **GetRecommendationsAsync** method. Get recommendations of the active build of type "Recommendation" or "Fbt" based on a list of seeds (input) items. The response includes one entry per recommended item, including the Rating of the recommendation; higher number means higher confidence. This is what the product recommendation HTTP request looks like:

	````
	HTTP GET method
	<rootURI>/ItemRecommend?modelId=%27<modelId>%27&itemIds=%27<itemId>%27&numberOfResults=<int>&includeMetadata=<bool>&apiVersion=%271.0%27
	````
{'fraction_non_alphanumeric': 0.07821370001261511, 'fraction_numerical': 0.015642740002523022, 'mean_word_length': 4.756959573953038, 'pattern_counts': {'":': 0, '<': 89, '<?xml version=': 0, '>': 95, 'https://': 8, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '501185', 'n_tokens_mistral': 6911, 'n_tokens_neox': 6454, 'n_words': 3128}