update samples from Release-130 as a part of SDK release

contrib/RAPIDS/README.md

@@ -0,0 +1,305 @@
+## How to use the RAPIDS on AzureML materials
+### Setting up requirements
+The material requires the use of the Azure ML SDK and of the Jupyter Notebook Server to run the interactive execution. Please refer to instructions to [setup the environment.](https://docs.microsoft.com/en-us/azure/machine-learning/service/how-to-configure-environment#local "Local Computer Set Up") Follow the instructions under **Local Computer**, make sure to run the last step: <span style="font-family: Courier New;">pip install \<new package\></span> with <span style="font-family: Courier New;">new package = progressbar2  (pip install progressbar2)</span>
+  
+After following the directions, the user should end up setting a conda environment (<span style="font-family: Courier New;">myenv</span>)that can be activated in an Anaconda prompt
+
+The user would also require an Azure Subscription with a Machine Learning Services quota on the desired region for 24 nodes or more (to be able to select a vmSize with 4 GPUs as it is used on the Notebook) on the desired VM family ([NC\_v3](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#ncv3-series),  [NC\_v2](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#ncv2-series), [ND](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#nd-series) or [ND_v2](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#ndv2-series-preview)), the specific vmSize to be used within the chosen family would also need to be whitelisted for Machine Learning Services usage.  
+
+&nbsp;  
+### Getting and running the material 
+Clone the AzureML Notebooks repository in GitHub by running the following command on a local_directory: 
+
+* C:\local_directory>git clone https://github.com/Azure/MachineLearningNotebooks.git
+
+On a conda prompt navigate to the local directory, activate the conda environment (<span style="font-family: Courier New;">myenv</span>), where the Azure ML SDK was installed and launch Jupyter Notebook. 
+
+* (<span style="font-family: Courier New;">myenv</span>) C:\local_directory>jupyter notebook
+
+From the resulting browser at http://localhost:8888/tree, navigate to the master notebook: 
+
+* http://localhost:8888/tree/MachineLearningNotebooks/contrib/RAPIDS/azure-ml-with-nvidia-rapids.ipynb
+
+&nbsp;  
+The following notebook will appear:  
+
+![](imgs/NotebookHome.png)
+
+&nbsp;  
+### Master Jupyter Notebook
+The notebook can be executed interactively step by step, by pressing the Run button (In a red circle in the above image.)
+
+The first couple of functional steps import the necessary AzureML libraries.  If you experience any errors please refer back to the [setup the environment.](https://docs.microsoft.com/en-us/azure/machine-learning/service/how-to-configure-environment#local "Local Computer Set Up") instructions.
+
+&nbsp;  
+#### Setting up a Workspace
+The following step gathers the information necessary to set up a workspace to execute the RAPIDS script. This needs to be done only once, or not at all if you already have a workspace you can use set up on the Azure Portal:
+
+![](imgs/WorkSpaceSetUp.png)
+
+
+It is important to be sure to set the correct values for the subscription\_id, resource\_group, workspace\_name, and region before executing the step. An example is:
+
+    subscription_id = os.environ.get("SUBSCRIPTION_ID", "1358e503-xxxx-4043-xxxx-65b83xxxx32d")
+    resource_group = os.environ.get("RESOURCE_GROUP", "AML-Rapids-Testing")
+    workspace_name = os.environ.get("WORKSPACE_NAME", "AML_Rapids_Tester")
+    workspace_region = os.environ.get("WORKSPACE_REGION", "West US 2")
+
+&nbsp;  
+The resource\_group and workspace_name could take any value, the region should match the region for which the subscription has the required Machine Learning Services node quota.
+
+The first time the code is executed it will redirect to the Azure Portal to validate subscription credentials. After the workspace is created, its related information is stored on a local file so that this step can be subsequently skipped. The immediate step will just load the saved workspace
+
+![](imgs/saved_workspace.png)
+
+Once a workspace has been created the user could skip its creation and just jump to this step. The configuration file resides in:
+
+* C:\local_directory\\MachineLearningNotebooks\contrib\RAPIDS\aml_config\config.json
+
+&nbsp;  
+#### Creating an AML Compute Target 
+Following step, creates an AML Compute Target 
+
+![](imgs/target_creation.png)
+
+Parameter vm\_size on function call AmlCompute.provisioning\_configuration() has to be a member of the VM families ([NC\_v3](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#ncv3-series),  [NC\_v2](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#ncv2-series), [ND](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#nd-series) or [ND_v2](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#ndv2-series-preview)) that are the ones provided with P40 or V100 GPUs, that are the ones supported by RAPIDS. In this particular case an Standard\_NC24s\_V2 was used.
+
+&nbsp;  
+If the output of running the step has an error of the form:
+
+![](imgs/targeterror1.png)
+
+It is an indication that even though the subscription has a node quota for VMs for that family, it does not have a node quota for Machine Learning Services for that family. 
+You will need to request an increase node quota for that family in that region for **Machine Learning Services**.
+
+&nbsp;  
+Another possible error is the following: 
+
+![](imgs/targeterror2.png)
+
+Which indicates that specified vmSize has not been whitelisted for usage on Machine Learning Services and a request to do so should be filled.
+
+The successful creation of the compute target would have an output like the following:
+
+![](imgs/targetsuccess.png)
+&nbsp;  
+#### RAPIDS script uploading and viewing
+The next step copies the RAPIDS script process_data.py, which is a slightly modified implementation of the [RAPIDS E2E example](https://github.com/rapidsai/notebooks/blob/master/mortgage/E2E.ipynb), into a script processing folder and it presents its contents to the user. (The script is discussed in the next section in detail). 
+If the user wants to use a different RAPIDS script, the references to the  <span style="font-family: Courier New;">process_data.py</span> script have to be changed
+
+![](imgs/scriptuploading.png)
+&nbsp;  
+#### Data Uploading
+The RAPIDS script loads and extracts features from the Fannie Mae’s Mortgage Dataset to train an XGBoost prediction model. The script uses two years of data
+
+The next few steps download and decompress the data and is made available to the  script as an [Azure Machine Learning Datastore](https://docs.microsoft.com/en-us/azure/machine-learning/service/how-to-access-data).
+
+&nbsp;  
+The following functions are used to download and decompress the input data
+
+
+![](imgs/dcf1.png)
+![](imgs/dcf2.png)
+![](imgs/dcf3.png)
+![](imgs/dcf4.png)
+
+&nbsp;  
+The next step uses those functions to download locally file: 
+http://rapidsai-data.s3-website.us-east-2.amazonaws.com/notebook-mortgage-data/mortgage_2000-2001.tgz'
+And to decompress it, into local folder path = .\mortgage_2000-2001
+The step takes several minutes, the intermediate outputs provide progress indicators.
+
+![](imgs/downamddecom.png)
+
+&nbsp;  
+The decompressed data should have the following structure:
+* .\mortgage_2000-2001\acq\Acquisition_<year>Q<num>.txt 
+* .\mortgage_2000-2001\perf\Performance_<year>Q<num>.txt 
+* .\mortgage_2000-2001\names.csv
+
+The data is divided in partitions that roughly correspond to yearly quarters. RAPIDS includes support for multi-node, multi-GPU deployments, enabling scaling up and out on much larger dataset sizes. The user will be able to verify that the number of partitions that the script is able to process increases with the number of GPUs used. The RAPIDS script is implemented for single-machine scenarios. An example supporting multiple nodes will be published later. 
+
+&nbsp;  
+The next step upload the data into the [Azure Machine Learning Datastore](https://docs.microsoft.com/en-us/azure/machine-learning/service/how-to-access-data) under reference <span style="font-family: Courier New;">fileroot = mortgage_2000-2001</span>
+
+The step takes several minutes to load the data, the output provides a progress indicator.
+
+![](imgs/datastore.png)
+
+Once the data has been loaded into the Azure Machine LEarning Data Store, in subsequent run, the user can comment out the ds.upload line and just make reference to the <span style="font-family: Courier New;">mortgage_2000-2001</blog> data store reference  
+
+&nbsp;  
+#### Setting up required libraries and environment to run RAPIDS code
+There are two options to setup the environment to run RAPIDS code. The following steps shows how to ues a prebuilt conda environment. A recommended alternative is to specify a base Docker image and package dependencies. You can find sample code for that in the notebook.
+
+![](imgs/install2.png)
+
+&nbsp;  
+#### Wrapper function to submit the RAPIDS script as an Azure Machine Learning experiment
+
+The next step consists of the definition of a wrapper function to be used when the user attempts to run the RAPIDS script with different arguments. It takes as arguments: <span style="font-family: Times New Roman;">*cpu\_training*</span>;  a flag that indicates if the run is meant to be processed with CPU-only, <span style="font-family: Times New Roman;">*gpu\_count*</span>; the number of GPUs to be used if they are meant to be used and part_count: the number of data partitions to be used
+
+![](imgs/wrapper.png)
+
+&nbsp;  
+The core of the function resides in configuring the run by the instantiation of a ScriptRunConfig object, which defines the source_directory for the script to be executed, the name of the script and the arguments to be passed to the script.
+In addition to the wrapper function arguments, two other arguments are passed: <span style="font-family: Times New Roman;">*data\_dir*</span>, the directory where the data is stored and <span style="font-family: Times New Roman;">*end_year*</span> is the largest year to use partition from.
+
+
+As mentioned earlier the size of the data that can be processed increases with the number of gpus, in the function, dictionary <span style="font-family: Times New Roman;">*max\_gpu\_count\_data\_partition_mapping*</span> maps the maximum number of partitions that we empirically found that the system can handle given the number of GPUs used. The function throws a warning when the number of partitions for a given number of gpus exceeds the maximum but the script is still executed, however the user should expect an error as an out of memory situation would be encountered
+If the user wants to use a different RAPIDS script, the reference to the process_data.py script has to be changed
+
+&nbsp;  
+#### Submitting Experiments
+We are ready to submit experiments: launching the RAPIDS script with different sets of parameters.
+
+&nbsp;  
+The following couple of steps submit experiments under different conditions. 
+
+![](imgs/submission1.png)
+
+&nbsp;  
+The user can change variable num\_gpu between one and the number of GPUs supported by the chosen vmSize. Variable part\_count can take any value between 1 and 11, but if it exceeds the maximum for num_gpu, the run would result in an error
+
+&nbsp;  
+If the experiment is successfully submitted, it would be placed on a queue for processing, its status would appeared as Queued and an output like the following would appear 
+
+![](imgs/queue.png)
+
+&nbsp;  
+When the experiment starts running, its status would appeared as Running and the output would change to something like this:
+
+![](imgs/running.png)
+
+&nbsp;  
+#### Reproducing the performance gains plot results on the Blog Post
+When the run has finished successfully, its status would appeared as Completed and the output would change to something like this:
+
+&nbsp; 
+![](imgs/completed.png)
+
+Which is the output for an experiment run with three partitions and one GPU, notice that the reported processing time is 49.16 seconds just as depicted on the performance gains plot on the blog post
+
+&nbsp;  
+
+![](imgs/2GPUs.png)
+
+
+This output corresponds to a run with three partitions and two GPUs, notice that the reported processing time is 37.50 seconds just as depicted on the performance gains plot on the blog post
+
+&nbsp;  
+![](imgs/3GPUs.png)
+
+This output corresponds to an experiment run with three partitions and three GPUs, notice that the reported processing time is 24.40 seconds just as depicted on the performance gains plot on the blog post
+
+&nbsp;  
+![](imgs/4gpus.png)
+
+This output corresponds to an experiment run with three partitions and four GPUs, notice that the reported processing time is 23.33 seconds just as depicted on the performance gains plot on the blogpost
+
+&nbsp;  
+![](imgs/CPUBase.png)
+
+This output corresponds to an experiment run with three partitions and using only CPU, notice that the reported processing time is 9 minutes and 1.21 seconds or 541.21 second just as depicted on the performance gains plot on the blog post
+
+&nbsp;  
+![](imgs/OOM.png)
+
+This output corresponds to an experiment run with nine partitions and four GPUs, notice that the notebook throws a warning signaling that the number of partitions exceed the maximum that the system can handle with those many GPUs and the run ends up failing, hence having and status of Failed. 
+
+&nbsp;  
+##### Freeing Resources
+In the last step the notebook deletes the compute target. (This step is optional especially if the min_nodes in the cluster is set to 0 with which the cluster will scale down to 0 nodes when there is no usage.)
+
+![](imgs/clusterdelete.png)
+
+&nbsp;  
+### RAPIDS Script
+The Master Notebook runs experiments by launching a RAPIDS script with different sets of parameters. In this section, the RAPIDS script, process_data.py in the material, is analyzed
+
+The script first imports all the necessary libraries and parses the arguments passed by the Master Notebook.
+
+The all internal functions to be used by the script are defined.
+
+&nbsp;  
+#### Wrapper Auxiliary Functions:
+The below functions are wrappers for a configuration module for librmm, the RAPIDS Memory Manager python interface:
+
+![](imgs/wap1.png)![](imgs/wap2.png)
+
+&nbsp;  
+A couple of other functions are wrappers for the submission of jobs to the DASK client:
+
+![](imgs/wap3.png)
+![](imgs/wap4.png)
+
+&nbsp;  
+#### Data Loading Functions:
+The data is loaded through the use of the following three functions 
+
+![](imgs/DLF1.png)![](imgs/DLF2.png)![](imgs/DLF3.png)
+
+All three functions use library function cudf.read_csv(), cuDF version for the well known counterpart on Pandas.
+
+&nbsp;  
+#### Data Transformation and Feature Extraction Functions:
+The raw data is transformed and processed to extract features by joining, slicing, grouping, aggregating, factoring, etc, the original dataframes just as is done with Pandas. The following functions in the script are used for that purpose:
+![](imgs/fef1.png)![](imgs/fef2.png)![](imgs/fef3.png)![](imgs/fef4.png)![](imgs/fef5.png)
+
+![](imgs/fef6.png)![](imgs/fef7.png)![](imgs/fef8.png)![](imgs/fef9.png)
+
+&nbsp;  
+#### Main() Function
+The previous functions are used in the Main function to accomplish several steps: Set up the Dask client, do all ETL operations, set up and train an XGBoost model, the function also assigns which data needs to be processed by each Dask client
+
+&nbsp;  
+##### Setting Up DASK client:
+The following lines:
+
+![](imgs/daskini.png)
+
+&nbsp;  
+Initialize and set up a DASK client with a number of workers corresponding to the number of GPUs to be used on the run. A successful execution of the set up will result on the following output:
+
+![](imgs/daskoutput.png)
+
+##### All ETL functions are used on single calls to process\_quarter_gpu, one per data partition
+
+![](imgs/ETL.png)
+
+&nbsp;  
+##### Concentrating the data assigned to each DASK worker
+The partitions assigned to each worker are concatenated and set up for training.
+
+![](imgs/Dask2.png)
+
+&nbsp;  
+##### Setting Training Parameters
+The parameters used for the training of a gradient boosted decision tree model are set up in the following code block:
+![](imgs/PArameters.png)
+
+Notice how the parameters are modified when using the CPU-only mode.
+
+&nbsp;  
+##### Launching the training of a gradient boosted decision tree model using XGBoost.
+
+![](imgs/training.png)
+
+The outputs of the script can be observed in the master notebook as the script is executed
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

contrib/RAPIDS/azure-ml-with-nvidia-rapids.ipynb

@@ -0,0 +1,547 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Copyright (c) Microsoft Corporation. All rights reserved.\n",
+        "\n",
+        "Licensed under the MIT License."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "![Impressions](https://PixelServer20190423114238.azurewebsites.net/api/impressions/MachineLearningNotebooks/contrib/RAPIDS/azure-ml-with-nvidia-rapids/azure-ml-with-nvidia-rapids.png)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# NVIDIA RAPIDS in Azure Machine Learning"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The [RAPIDS](https://www.developer.nvidia.com/rapids) suite of software libraries from NVIDIA enables the execution of end-to-end data science and analytics pipelines entirely on GPUs. In many machine learning projects, a significant portion of the model training time is spent in setting up the data; this stage of the process is known as Extraction, Transformation and Loading, or ETL. By using the DataFrame API for ETL\u00c2\u00a0and GPU-capable ML algorithms in RAPIDS, data preparation and training models can be done in GPU-accelerated end-to-end pipelines without incurring serialization costs between the pipeline stages. This notebook demonstrates how to use NVIDIA RAPIDS to prepare data and train model\u00c3\u201a\u00c2\u00a0in Azure.\n",
+        " \n",
+        "In this notebook, we will do the following:\n",
+        " \n",
+        "* Create an Azure Machine Learning Workspace\n",
+        "* Create an AMLCompute target\n",
+        "* Use a script to process our data and train a model\n",
+        "* Obtain the data required to run this sample\n",
+        "* Create an AML run configuration to launch a machine learning job\n",
+        "* Run the script to prepare data for training and train the model\n",
+        " \n",
+        "Prerequisites:\n",
+        "* An Azure subscription to create a Machine Learning Workspace\n",
+        "* Familiarity with the Azure ML SDK (refer to [notebook samples](https://github.com/Azure/MachineLearningNotebooks))\n",
+        "* A Jupyter notebook environment with Azure Machine Learning SDK installed. Refer to instructions to [setup the environment](https://docs.microsoft.com/en-us/azure/machine-learning/service/how-to-configure-environment#local)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Verify if Azure ML SDK is installed"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import azureml.core\n",
+        "print(\"SDK version:\", azureml.core.VERSION)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import os\n",
+        "from azureml.core import Workspace, Experiment\n",
+        "from azureml.core.conda_dependencies import CondaDependencies\n",
+        "from azureml.core.compute import AmlCompute, ComputeTarget\n",
+        "from azureml.data.data_reference import DataReference\n",
+        "from azureml.core.runconfig import RunConfiguration\n",
+        "from azureml.core import ScriptRunConfig\n",
+        "from azureml.widgets import RunDetails"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Create Azure ML Workspace"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The following step is optional if you already have a workspace. If you want to use an existing workspace, then\n",
+        "skip this workspace creation step and move on to the next step to load the workspace.\n",
+        " \n",
+        "<font color='red'>Important</font>: in the code cell below, be sure to set the correct values for the subscription_id, \n",
+        "resource_group, workspace_name, region before executing this code cell."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "subscription_id = os.environ.get(\"SUBSCRIPTION_ID\", \"<subscription_id>\")\n",
+        "resource_group = os.environ.get(\"RESOURCE_GROUP\", \"<resource_group>\")\n",
+        "workspace_name = os.environ.get(\"WORKSPACE_NAME\", \"<workspace_name>\")\n",
+        "workspace_region = os.environ.get(\"WORKSPACE_REGION\", \"<region>\")\n",
+        "\n",
+        "ws = Workspace.create(workspace_name, subscription_id=subscription_id, resource_group=resource_group, location=workspace_region)\n",
+        "\n",
+        "# write config to a local directory for future use\n",
+        "ws.write_config()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Load existing Workspace"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "ws = Workspace.from_config()\n",
+        "\n",
+        "# if a locally-saved configuration file for the workspace is not available, use the following to load workspace\n",
+        "# ws = Workspace(subscription_id=subscription_id, resource_group=resource_group, workspace_name=workspace_name)\n",
+        "\n",
+        "print('Workspace name: ' + ws.name, \n",
+        "      'Azure region: ' + ws.location, \n",
+        "      'Subscription id: ' + ws.subscription_id, \n",
+        "      'Resource group: ' + ws.resource_group, sep = '\\n')\n",
+        "\n",
+        "scripts_folder = \"scripts_folder\"\n",
+        "\n",
+        "if not os.path.isdir(scripts_folder):\n",
+        "    os.mkdir(scripts_folder)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Create AML Compute Target"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Because NVIDIA RAPIDS requires P40 or V100 GPUs, the user needs to specify compute targets from one of [NC_v3](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#ncv3-series), [NC_v2](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#ncv2-series), [ND](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#nd-series) or [ND_v2](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/sizes-gpu#ndv2-series-preview) virtual machine types in Azure; these are the families of virtual machines in Azure that are provisioned with these GPUs.\n",
+        " \n",
+        "Pick one of the supported VM SKUs based on the number of GPUs you want to use for ETL and training in RAPIDS.\n",
+        " \n",
+        "The script in this notebook is implemented for single-machine scenarios. An example supporting multiple nodes will be published later."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "gpu_cluster_name = \"gpucluster\"\n",
+        "\n",
+        "if gpu_cluster_name in ws.compute_targets:\n",
+        "    gpu_cluster = ws.compute_targets[gpu_cluster_name]\n",
+        "    if gpu_cluster and type(gpu_cluster) is AmlCompute:\n",
+        "        print('Found compute target. Will use {0} '.format(gpu_cluster_name))\n",
+        "else:\n",
+        "    print(\"creating new cluster\")\n",
+        "    # vm_size parameter below could be modified to one of the RAPIDS-supported VM types\n",
+        "    provisioning_config = AmlCompute.provisioning_configuration(vm_size = \"Standard_NC6s_v2\", min_nodes=1, max_nodes = 1)\n",
+        "\n",
+        "    # create the cluster\n",
+        "    gpu_cluster = ComputeTarget.create(ws, gpu_cluster_name, provisioning_config)\n",
+        "    gpu_cluster.wait_for_completion(show_output=True)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Script to process data and train model"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# copy process_data.py into the script folder\n",
+        "import shutil\n",
+        "shutil.copy('./process_data.py', os.path.join(scripts_folder, 'process_data.py'))"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Data required to run this sample"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "This sample uses [Fannie Mae's Single-Family Loan Performance Data](http://www.fanniemae.com/portal/funding-the-market/data/loan-performance-data.html). Once you obtain access to the data, you will need to make this data available in an [Azure Machine Learning Datastore](https://docs.microsoft.com/en-us/azure/machine-learning/service/how-to-access-data), for use in this sample. The following code shows how to do that."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Downloading Data"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import tarfile\n",
+        "import hashlib\n",
+        "from urllib.request import urlretrieve\n",
+        "\n",
+        "def validate_downloaded_data(path):\n",
+        "    if(os.path.isdir(path) and os.path.exists(path + '//names.csv')) :\n",
+        "        if(os.path.isdir(path + '//acq' ) and len(os.listdir(path + '//acq')) == 8):\n",
+        "            if(os.path.isdir(path + '//perf' ) and len(os.listdir(path + '//perf')) == 11):\n",
+        "                print(\"Data has been downloaded and decompressed at: {0}\".format(path))\n",
+        "                return True\n",
+        "    print(\"Data has not been downloaded and decompressed\")\n",
+        "    return False\n",
+        "\n",
+        "def show_progress(count, block_size, total_size):\n",
+        "    global pbar\n",
+        "    global processed\n",
+        "    \n",
+        "    if count == 0:\n",
+        "        pbar = ProgressBar(maxval=total_size)\n",
+        "        processed = 0\n",
+        "    \n",
+        "    processed += block_size\n",
+        "    processed = min(processed,total_size)\n",
+        "    pbar.update(processed)\n",
+        "\n",
+        "        \n",
+        "def download_file(fileroot):\n",
+        "    filename = fileroot + '.tgz'\n",
+        "    if(not os.path.exists(filename) or hashlib.md5(open(filename, 'rb').read()).hexdigest() != '82dd47135053303e9526c2d5c43befd5' ):\n",
+        "        url_format = 'http://rapidsai-data.s3-website.us-east-2.amazonaws.com/notebook-mortgage-data/{0}.tgz'\n",
+        "        url = url_format.format(fileroot)\n",
+        "        print(\"...Downloading file :{0}\".format(filename))\n",
+        "        urlretrieve(url, filename)\n",
+        "        pbar.finish()\n",
+        "        print(\"...File :{0} finished downloading\".format(filename))\n",
+        "    else:\n",
+        "        print(\"...File :{0} has been downloaded already\".format(filename))\n",
+        "    return filename\n",
+        "\n",
+        "def decompress_file(filename,path):\n",
+        "    tar = tarfile.open(filename)\n",
+        "    print(\"...Getting information from {0} about files to decompress\".format(filename))\n",
+        "    members = tar.getmembers()\n",
+        "    numFiles = len(members)\n",
+        "    so_far = 0\n",
+        "    for member_info in members:\n",
+        "        tar.extract(member_info,path=path)\n",
+        "        so_far += 1\n",
+        "    print(\"...All {0} files have been decompressed\".format(numFiles))\n",
+        "    tar.close()"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "fileroot = 'mortgage_2000-2001'\n",
+        "path = '.\\\\{0}'.format(fileroot)\n",
+        "pbar = None\n",
+        "processed = 0\n",
+        "\n",
+        "if(not validate_downloaded_data(path)):\n",
+        "    print(\"Downloading and Decompressing Input Data\")\n",
+        "    filename = download_file(fileroot)\n",
+        "    decompress_file(filename,path)\n",
+        "    print(\"Input Data has been Downloaded and Decompressed\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Uploading Data to Workspace"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "ds = ws.get_default_datastore()\n",
+        "\n",
+        "# download and uncompress data in a local directory before uploading to data store\n",
+        "# directory specified in src_dir parameter below should have the acq, perf directories with data and names.csv file\n",
+        "\n",
+        "# ---->>>> UNCOMMENT THE BELOW LINE TO UPLOAD YOUR DATA IF NOT DONE SO ALREADY <<<<----\n",
+        "# ds.upload(src_dir=path, target_path=fileroot, overwrite=True, show_progress=True)\n",
+        "\n",
+        "# data already uploaded to the datastore\n",
+        "data_ref = DataReference(data_reference_name='data', datastore=ds, path_on_datastore=fileroot)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Create AML run configuration to launch a machine learning job"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "RunConfiguration is used to submit jobs to Azure Machine Learning service. When creating RunConfiguration for a job, users can either \n",
+        "1. specify a Docker image with prebuilt conda environment and use it without any modifications to run the job, or \n",
+        "2. specify a Docker image as the base image and conda or pip packages as dependnecies to let AML build a new Docker image with a conda environment containing specified dependencies to use in the job\n",
+        "\n",
+        "The second option is the recommended option in AML. \n",
+        "The following steps have code for both options. You can pick the one that is more appropriate for your requirements. "
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Specify prebuilt conda environment"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The following code shows how to install RAPIDS using conda. The `rapids.yml` file contains the list of packages necessary to run this tutorial. **NOTE:** Initial build of the image might take up to 20 minutes as the service needs to build and cache the new image; once the image is built the subequent runs use the cached image and the overhead is minimal."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "cd = CondaDependencies(conda_dependencies_file_path='rapids.yml')\n",
+        "run_config = RunConfiguration(conda_dependencies=cd)\n",
+        "run_config.framework = 'python'\n",
+        "run_config.target = gpu_cluster_name\n",
+        "run_config.environment.docker.enabled = True\n",
+        "run_config.environment.docker.gpu_support = True\n",
+        "run_config.environment.docker.base_image = \"mcr.microsoft.com/azureml/openmpi4.1.0-cuda11.1-cudnn8-ubuntu20.04\"\n",
+        "run_config.environment.spark.precache_packages = False\n",
+        "run_config.data_references={'data':data_ref.to_config()}"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "#### Using Docker"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Alternatively, you can specify RAPIDS Docker image."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# run_config = RunConfiguration()\n",
+        "# run_config.framework = 'python'\n",
+        "# run_config.environment.python.user_managed_dependencies = True\n",
+        "# run_config.environment.python.interpreter_path = '/conda/envs/rapids/bin/python'\n",
+        "# run_config.target = gpu_cluster_name\n",
+        "# run_config.environment.docker.enabled = True\n",
+        "# run_config.environment.docker.gpu_support = True\n",
+        "# run_config.environment.docker.base_image = \"rapidsai/rapidsai:cuda9.2-runtime-ubuntu18.04\"\n",
+        "# # run_config.environment.docker.base_image_registry.address = '<registry_url>' # not required if the base_image is in Docker hub\n",
+        "# # run_config.environment.docker.base_image_registry.username = '<user_name>' # needed only for private images\n",
+        "# # run_config.environment.docker.base_image_registry.password = '<password>' # needed only for private images\n",
+        "# run_config.environment.spark.precache_packages = False\n",
+        "# run_config.data_references={'data':data_ref.to_config()}"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Wrapper function to submit Azure Machine Learning experiment"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# parameter cpu_predictor indicates if training should be done on CPU. If set to true, GPUs are used *only* for ETL and *not* for training\n",
+        "# parameter num_gpu indicates number of GPUs to use among the GPUs available in the VM for ETL and if cpu_predictor is false, for training as well \n",
+        "def run_rapids_experiment(cpu_training, gpu_count, part_count):\n",
+        "    # any value between 1-4 is allowed here depending the type of VMs available in gpu_cluster\n",
+        "    if gpu_count not in [1, 2, 3, 4]:\n",
+        "        raise Exception('Value specified for the number of GPUs to use {0} is invalid'.format(gpu_count))\n",
+        "\n",
+        "    # following data partition mapping is empirical (specific to GPUs used and current data partitioning scheme) and may need to be tweaked\n",
+        "    max_gpu_count_data_partition_mapping = {1: 3, 2: 4, 3: 6, 4: 8}\n",
+        "    \n",
+        "    if part_count > max_gpu_count_data_partition_mapping[gpu_count]:\n",
+        "        print(\"Too many partitions for the number of GPUs, exceeding memory threshold\")\n",
+        "        \n",
+        "    if part_count > 11:\n",
+        "        print(\"Warning: Maximum number of partitions available is 11\")\n",
+        "        part_count = 11\n",
+        "        \n",
+        "    end_year = 2000\n",
+        "    \n",
+        "    if part_count > 4:\n",
+        "        end_year = 2001 # use more data with more GPUs\n",
+        "\n",
+        "    src = ScriptRunConfig(source_directory=scripts_folder, \n",
+        "                          script='process_data.py', \n",
+        "                          arguments = ['--num_gpu', gpu_count, '--data_dir', str(data_ref),\n",
+        "                                      '--part_count', part_count, '--end_year', end_year,\n",
+        "                                      '--cpu_predictor', cpu_training\n",
+        "                                      ],\n",
+        "                          run_config=run_config\n",
+        "                         )\n",
+        "\n",
+        "    exp = Experiment(ws, 'rapidstest')\n",
+        "    run = exp.submit(config=src)\n",
+        "    RunDetails(run).show()\n",
+        "    return run"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Submit experiment (ETL & training on GPU)"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "cpu_predictor = False\n",
+        "# the value for num_gpu should be less than or equal to the number of GPUs available in the VM\n",
+        "num_gpu = 1\n",
+        "data_part_count = 1\n",
+        "# train using CPU, use GPU for both ETL and training\n",
+        "run = run_rapids_experiment(cpu_predictor, num_gpu, data_part_count)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Submit experiment (ETL on GPU, training on CPU)\n",
+        "\n",
+        "To observe performance difference between GPU-accelerated RAPIDS based training with CPU-only training, set 'cpu_predictor' predictor to 'True' and rerun the experiment"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "cpu_predictor = True\n",
+        "# the value for num_gpu should be less than or equal to the number of GPUs available in the VM\n",
+        "num_gpu = 1\n",
+        "data_part_count = 1\n",
+        "# train using CPU, use GPU for ETL\n",
+        "run = run_rapids_experiment(cpu_predictor, num_gpu, data_part_count)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Delete cluster"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# delete the cluster\n",
+        "# gpu_cluster.delete()"
+      ]
+    }
+  ],
+  "metadata": {
+    "authors": [
+      {
+        "name": "ksivas"
+      }
+    ],
+    "kernelspec": {
+      "display_name": "Python 3.6",
+      "language": "python",
+      "name": "python36"
+    },
+    "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.8"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}

contrib/RAPIDS/process_data.py

@@ -0,0 +1,470 @@
+import numpy as np
+import datetime
+import dask_xgboost as dxgb_gpu
+import dask
+import dask_cudf
+from dask_cuda import LocalCUDACluster
+from dask.delayed import delayed
+from dask.distributed import Client, wait
+import xgboost as xgb
+import cudf
+from cudf.dataframe import DataFrame
+from collections import OrderedDict
+import gc
+from glob import glob
+import os
+import argparse
+
+def run_dask_task(func, **kwargs):
+    task = func(**kwargs)
+    return task
+
+def process_quarter_gpu(client, col_names_path, acq_data_path, year=2000, quarter=1, perf_file=""):
+    dask_client = client
+    ml_arrays = run_dask_task(delayed(run_gpu_workflow),
+                                          col_path=col_names_path,
+                                          acq_path=acq_data_path,
+                                          quarter=quarter,
+                                          year=year,
+                                          perf_file=perf_file)
+    return dask_client.compute(ml_arrays,
+                          optimize_graph=False,
+                          fifo_timeout="0ms")
+
+def null_workaround(df, **kwargs):
+    for column, data_type in df.dtypes.items():
+        if str(data_type) == "category":
+            df[column] = df[column].astype('int32').fillna(-1)
+        if str(data_type) in ['int8', 'int16', 'int32', 'int64', 'float32', 'float64']:
+            df[column] = df[column].fillna(-1)
+    return df
+
+def run_gpu_workflow(col_path, acq_path, quarter=1, year=2000, perf_file="", **kwargs):
+    names = gpu_load_names(col_path=col_path)
+    acq_gdf = gpu_load_acquisition_csv(acquisition_path= acq_path + "/Acquisition_"
+                                      + str(year) + "Q" + str(quarter) + ".txt")
+    acq_gdf = acq_gdf.merge(names, how='left', on=['seller_name'])
+    acq_gdf.drop_column('seller_name')
+    acq_gdf['seller_name'] = acq_gdf['new']
+    acq_gdf.drop_column('new')
+    perf_df_tmp = gpu_load_performance_csv(perf_file)
+    gdf = perf_df_tmp
+    everdf = create_ever_features(gdf)
+    delinq_merge = create_delinq_features(gdf)
+    everdf = join_ever_delinq_features(everdf, delinq_merge)
+    del(delinq_merge)
+    joined_df = create_joined_df(gdf, everdf)
+    testdf = create_12_mon_features(joined_df)
+    joined_df = combine_joined_12_mon(joined_df, testdf)
+    del(testdf)
+    perf_df = final_performance_delinquency(gdf, joined_df)
+    del(gdf, joined_df)
+    final_gdf = join_perf_acq_gdfs(perf_df, acq_gdf)
+    del(perf_df)
+    del(acq_gdf)
+    final_gdf = last_mile_cleaning(final_gdf)
+    return final_gdf
+
+def gpu_load_performance_csv(performance_path, **kwargs):
+    """ Loads performance data
+
+    Returns
+    -------
+    GPU DataFrame
+    """
+    
+    cols = [
+        "loan_id", "monthly_reporting_period", "servicer", "interest_rate", "current_actual_upb",
+        "loan_age", "remaining_months_to_legal_maturity", "adj_remaining_months_to_maturity",
+        "maturity_date", "msa", "current_loan_delinquency_status", "mod_flag", "zero_balance_code",
+        "zero_balance_effective_date", "last_paid_installment_date", "foreclosed_after",
+        "disposition_date", "foreclosure_costs", "prop_preservation_and_repair_costs",
+        "asset_recovery_costs", "misc_holding_expenses", "holding_taxes", "net_sale_proceeds",
+        "credit_enhancement_proceeds", "repurchase_make_whole_proceeds", "other_foreclosure_proceeds",
+        "non_interest_bearing_upb", "principal_forgiveness_upb", "repurchase_make_whole_proceeds_flag",
+        "foreclosure_principal_write_off_amount", "servicing_activity_indicator"
+    ]
+    
+    dtypes = OrderedDict([
+        ("loan_id", "int64"),
+        ("monthly_reporting_period", "date"),
+        ("servicer", "category"),
+        ("interest_rate", "float64"),
+        ("current_actual_upb", "float64"),
+        ("loan_age", "float64"),
+        ("remaining_months_to_legal_maturity", "float64"),
+        ("adj_remaining_months_to_maturity", "float64"),
+        ("maturity_date", "date"),
+        ("msa", "float64"),
+        ("current_loan_delinquency_status", "int32"),
+        ("mod_flag", "category"),
+        ("zero_balance_code", "category"),
+        ("zero_balance_effective_date", "date"),
+        ("last_paid_installment_date", "date"),
+        ("foreclosed_after", "date"),
+        ("disposition_date", "date"),
+        ("foreclosure_costs", "float64"),
+        ("prop_preservation_and_repair_costs", "float64"),
+        ("asset_recovery_costs", "float64"),
+        ("misc_holding_expenses", "float64"),
+        ("holding_taxes", "float64"),
+        ("net_sale_proceeds", "float64"),
+        ("credit_enhancement_proceeds", "float64"),
+        ("repurchase_make_whole_proceeds", "float64"),
+        ("other_foreclosure_proceeds", "float64"),
+        ("non_interest_bearing_upb", "float64"),
+        ("principal_forgiveness_upb", "float64"),
+        ("repurchase_make_whole_proceeds_flag", "category"),
+        ("foreclosure_principal_write_off_amount", "float64"),
+        ("servicing_activity_indicator", "category")
+    ])
+
+    print(performance_path)
+    
+    return cudf.read_csv(performance_path, names=cols, delimiter='|', dtype=list(dtypes.values()), skiprows=1)
+
+def gpu_load_acquisition_csv(acquisition_path, **kwargs):
+    """ Loads acquisition data
+
+    Returns
+    -------
+    GPU DataFrame
+    """
+    
+    cols = [
+        'loan_id', 'orig_channel', 'seller_name', 'orig_interest_rate', 'orig_upb', 'orig_loan_term', 
+        'orig_date', 'first_pay_date', 'orig_ltv', 'orig_cltv', 'num_borrowers', 'dti', 'borrower_credit_score', 
+        'first_home_buyer', 'loan_purpose', 'property_type', 'num_units', 'occupancy_status', 'property_state',
+        'zip', 'mortgage_insurance_percent', 'product_type', 'coborrow_credit_score', 'mortgage_insurance_type', 
+        'relocation_mortgage_indicator'
+    ]
+    
+    dtypes = OrderedDict([
+        ("loan_id", "int64"),
+        ("orig_channel", "category"),
+        ("seller_name", "category"),
+        ("orig_interest_rate", "float64"),
+        ("orig_upb", "int64"),
+        ("orig_loan_term", "int64"),
+        ("orig_date", "date"),
+        ("first_pay_date", "date"),
+        ("orig_ltv", "float64"),
+        ("orig_cltv", "float64"),
+        ("num_borrowers", "float64"),
+        ("dti", "float64"),
+        ("borrower_credit_score", "float64"),
+        ("first_home_buyer", "category"),
+        ("loan_purpose", "category"),
+        ("property_type", "category"),
+        ("num_units", "int64"),
+        ("occupancy_status", "category"),
+        ("property_state", "category"),
+        ("zip", "int64"),
+        ("mortgage_insurance_percent", "float64"),
+        ("product_type", "category"),
+        ("coborrow_credit_score", "float64"),
+        ("mortgage_insurance_type", "float64"),
+        ("relocation_mortgage_indicator", "category")
+    ])
+    
+    print(acquisition_path)
+    
+    return cudf.read_csv(acquisition_path, names=cols, delimiter='|', dtype=list(dtypes.values()), skiprows=1)
+
+def gpu_load_names(col_path):
+    """ Loads names used for renaming the banks
+    
+    Returns
+    -------
+    GPU DataFrame
+    """
+
+    cols = [
+        'seller_name', 'new'
+    ]
+    
+    dtypes = OrderedDict([
+        ("seller_name", "category"),
+        ("new", "category"),
+    ])
+
+    return cudf.read_csv(col_path, names=cols, delimiter='|', dtype=list(dtypes.values()), skiprows=1)
+
+def create_ever_features(gdf, **kwargs):
+    everdf = gdf[['loan_id', 'current_loan_delinquency_status']]
+    everdf = everdf.groupby('loan_id', method='hash').max().reset_index()
+    del(gdf)
+    everdf['ever_30'] = (everdf['current_loan_delinquency_status'] >= 1).astype('int8')
+    everdf['ever_90'] = (everdf['current_loan_delinquency_status'] >= 3).astype('int8')
+    everdf['ever_180'] = (everdf['current_loan_delinquency_status'] >= 6).astype('int8')
+    everdf.drop_column('current_loan_delinquency_status')
+    return everdf
+
+def create_delinq_features(gdf, **kwargs):
+    delinq_gdf = gdf[['loan_id', 'monthly_reporting_period', 'current_loan_delinquency_status']]
+    del(gdf)
+    delinq_30 = delinq_gdf.query('current_loan_delinquency_status >= 1')[['loan_id', 'monthly_reporting_period']].groupby('loan_id', method='hash').min().reset_index()
+    delinq_30['delinquency_30'] = delinq_30['monthly_reporting_period']
+    delinq_30.drop_column('monthly_reporting_period')
+    delinq_90 = delinq_gdf.query('current_loan_delinquency_status >= 3')[['loan_id', 'monthly_reporting_period']].groupby('loan_id', method='hash').min().reset_index()
+    delinq_90['delinquency_90'] = delinq_90['monthly_reporting_period']
+    delinq_90.drop_column('monthly_reporting_period')
+    delinq_180 = delinq_gdf.query('current_loan_delinquency_status >= 6')[['loan_id', 'monthly_reporting_period']].groupby('loan_id', method='hash').min().reset_index()
+    delinq_180['delinquency_180'] = delinq_180['monthly_reporting_period']
+    delinq_180.drop_column('monthly_reporting_period')
+    del(delinq_gdf)
+    delinq_merge = delinq_30.merge(delinq_90, how='left', on=['loan_id'], type='hash')
+    delinq_merge['delinquency_90'] = delinq_merge['delinquency_90'].fillna(np.dtype('datetime64[ms]').type('1970-01-01').astype('datetime64[ms]'))
+    delinq_merge = delinq_merge.merge(delinq_180, how='left', on=['loan_id'], type='hash')
+    delinq_merge['delinquency_180'] = delinq_merge['delinquency_180'].fillna(np.dtype('datetime64[ms]').type('1970-01-01').astype('datetime64[ms]'))
+    del(delinq_30)
+    del(delinq_90)
+    del(delinq_180)
+    return delinq_merge
+
+def join_ever_delinq_features(everdf_tmp, delinq_merge, **kwargs):
+    everdf = everdf_tmp.merge(delinq_merge, on=['loan_id'], how='left', type='hash')
+    del(everdf_tmp)
+    del(delinq_merge)
+    everdf['delinquency_30'] = everdf['delinquency_30'].fillna(np.dtype('datetime64[ms]').type('1970-01-01').astype('datetime64[ms]'))
+    everdf['delinquency_90'] = everdf['delinquency_90'].fillna(np.dtype('datetime64[ms]').type('1970-01-01').astype('datetime64[ms]'))
+    everdf['delinquency_180'] = everdf['delinquency_180'].fillna(np.dtype('datetime64[ms]').type('1970-01-01').astype('datetime64[ms]'))
+    return everdf
+
+def create_joined_df(gdf, everdf, **kwargs):
+    test = gdf[['loan_id', 'monthly_reporting_period', 'current_loan_delinquency_status', 'current_actual_upb']]
+    del(gdf)
+    test['timestamp'] = test['monthly_reporting_period']
+    test.drop_column('monthly_reporting_period')
+    test['timestamp_month'] = test['timestamp'].dt.month
+    test['timestamp_year'] = test['timestamp'].dt.year
+    test['delinquency_12'] = test['current_loan_delinquency_status']
+    test.drop_column('current_loan_delinquency_status')
+    test['upb_12'] = test['current_actual_upb']
+    test.drop_column('current_actual_upb')
+    test['upb_12'] = test['upb_12'].fillna(999999999)
+    test['delinquency_12'] = test['delinquency_12'].fillna(-1)
+    
+    joined_df = test.merge(everdf, how='left', on=['loan_id'], type='hash')
+    del(everdf)
+    del(test)
+    
+    joined_df['ever_30'] = joined_df['ever_30'].fillna(-1)
+    joined_df['ever_90'] = joined_df['ever_90'].fillna(-1)
+    joined_df['ever_180'] = joined_df['ever_180'].fillna(-1)
+    joined_df['delinquency_30'] = joined_df['delinquency_30'].fillna(-1)
+    joined_df['delinquency_90'] = joined_df['delinquency_90'].fillna(-1)
+    joined_df['delinquency_180'] = joined_df['delinquency_180'].fillna(-1)
+    
+    joined_df['timestamp_year'] = joined_df['timestamp_year'].astype('int32')
+    joined_df['timestamp_month'] = joined_df['timestamp_month'].astype('int32')
+    
+    return joined_df
+
+def create_12_mon_features(joined_df, **kwargs):
+    testdfs = []
+    n_months = 12
+
+    for y in range(1, n_months + 1):
+        tmpdf = joined_df[['loan_id', 'timestamp_year', 'timestamp_month', 'delinquency_12', 'upb_12']]
+        tmpdf['josh_months'] = tmpdf['timestamp_year'] * 12 + tmpdf['timestamp_month']
+        tmpdf['josh_mody_n'] = ((tmpdf['josh_months'].astype('float64') - 24000 - y) / 12).floor()
+        tmpdf = tmpdf.groupby(['loan_id', 'josh_mody_n'], method='hash').agg({'delinquency_12': 'max','upb_12': 'min'}).reset_index()
+        tmpdf['delinquency_12'] = (tmpdf['delinquency_12']>3).astype('int32')
+        tmpdf['delinquency_12'] +=(tmpdf['upb_12']==0).astype('int32')
+        tmpdf['upb_12'] = tmpdf['upb_12']
+        tmpdf['timestamp_year'] = (((tmpdf['josh_mody_n'] * n_months) + 24000 + (y - 1)) / 12).floor().astype('int16')
+        tmpdf['timestamp_month'] = np.int8(y)
+        tmpdf.drop_column('josh_mody_n')
+        testdfs.append(tmpdf)
+        del(tmpdf)
+    del(joined_df)
+
+    return cudf.concat(testdfs)
+
+def combine_joined_12_mon(joined_df, testdf, **kwargs):
+    joined_df.drop_column('delinquency_12')
+    joined_df.drop_column('upb_12')
+    joined_df['timestamp_year'] = joined_df['timestamp_year'].astype('int16')
+    joined_df['timestamp_month'] = joined_df['timestamp_month'].astype('int8')
+    return joined_df.merge(testdf, how='left', on=['loan_id', 'timestamp_year', 'timestamp_month'], type='hash')
+
+def final_performance_delinquency(gdf, joined_df, **kwargs):
+    merged = null_workaround(gdf)
+    joined_df = null_workaround(joined_df)
+    merged['timestamp_month'] = merged['monthly_reporting_period'].dt.month
+    merged['timestamp_month'] = merged['timestamp_month'].astype('int8')
+    merged['timestamp_year'] = merged['monthly_reporting_period'].dt.year
+    merged['timestamp_year'] = merged['timestamp_year'].astype('int16')
+    merged = merged.merge(joined_df, how='left', on=['loan_id', 'timestamp_year', 'timestamp_month'], type='hash')
+    merged.drop_column('timestamp_year')
+    merged.drop_column('timestamp_month')
+    return merged
+
+def join_perf_acq_gdfs(perf, acq, **kwargs):
+    perf = null_workaround(perf)
+    acq = null_workaround(acq)
+    return perf.merge(acq, how='left', on=['loan_id'], type='hash')
+
+def last_mile_cleaning(df, **kwargs):
+    drop_list = [
+        'loan_id', 'orig_date', 'first_pay_date', 'seller_name',
+        'monthly_reporting_period', 'last_paid_installment_date', 'maturity_date', 'ever_30', 'ever_90', 'ever_180',
+        'delinquency_30', 'delinquency_90', 'delinquency_180', 'upb_12',
+        'zero_balance_effective_date','foreclosed_after', 'disposition_date','timestamp'
+    ]
+
+    for column in drop_list:
+        df.drop_column(column)
+    for col, dtype in df.dtypes.iteritems():
+        if str(dtype)=='category':
+            df[col] = df[col].cat.codes
+        df[col] = df[col].astype('float32')
+    df['delinquency_12'] = df['delinquency_12'] > 0
+    df['delinquency_12'] = df['delinquency_12'].fillna(False).astype('int32')
+    for column in df.columns:
+        df[column] = df[column].fillna(-1)
+    return df.to_arrow(preserve_index=False)
+
+def main():
+    parser = argparse.ArgumentParser("rapidssample")
+    parser.add_argument("--data_dir", type=str, help="location of data")
+    parser.add_argument("--num_gpu", type=int, help="Number of GPUs to use", default=1)
+    parser.add_argument("--part_count", type=int, help="Number of data files to train against", default=2)
+    parser.add_argument("--end_year", type=int, help="Year to end the data load", default=2000)
+    parser.add_argument("--cpu_predictor", type=str, help="Flag to use CPU for prediction", default='False')
+    parser.add_argument('-f', type=str, default='') # added for notebook execution scenarios
+    args = parser.parse_args()
+    data_dir = args.data_dir
+    num_gpu = args.num_gpu
+    part_count = args.part_count
+    end_year = args.end_year
+    cpu_predictor = args.cpu_predictor.lower() in ('yes', 'true', 't', 'y', '1')
+
+    if cpu_predictor:
+        print('Training with CPUs require num gpu = 1')
+        num_gpu = 1
+
+    print('data_dir = {0}'.format(data_dir))
+    print('num_gpu = {0}'.format(num_gpu))
+    print('part_count = {0}'.format(part_count))
+    print('end_year = {0}'.format(end_year))
+    print('cpu_predictor = {0}'.format(cpu_predictor))
+    
+    import subprocess
+
+    cmd = "hostname --all-ip-addresses"
+    process = subprocess.Popen(cmd.split(), stdout=subprocess.PIPE)
+    output, error = process.communicate()
+    IPADDR = str(output.decode()).split()[0]
+    
+    cluster = LocalCUDACluster(ip=IPADDR,n_workers=num_gpu)
+    client = Client(cluster)
+    client
+    print(client.ncores())
+
+    # to download data for this notebook, visit https://rapidsai.github.io/demos/datasets/mortgage-data and update the following paths accordingly
+    acq_data_path = "{0}/acq".format(data_dir) #"/rapids/data/mortgage/acq"
+    perf_data_path = "{0}/perf".format(data_dir) #"/rapids/data/mortgage/perf"
+    col_names_path = "{0}/names.csv".format(data_dir) # "/rapids/data/mortgage/names.csv"
+    start_year = 2000
+
+    client
+    print('--->>> Workers used: {0}'.format(client.ncores()))
+
+    # NOTE: The ETL calculates additional features which are then dropped before creating the XGBoost DMatrix.
+    # This can be optimized to avoid calculating the dropped features.
+    print("Reading ...")
+    t1 = datetime.datetime.now()
+    gpu_dfs = []
+    gpu_time = 0
+    quarter = 1
+    year = start_year
+    count = 0
+    while year <= end_year:
+        for file in glob(os.path.join(perf_data_path + "/Performance_" + str(year) + "Q" + str(quarter) + "*")):
+            if count < part_count:
+                gpu_dfs.append(process_quarter_gpu(client, col_names_path, acq_data_path, year=year, quarter=quarter, perf_file=file))
+                count += 1
+                print('file: {0}'.format(file))
+                print('count: {0}'.format(count))
+        quarter += 1
+        if quarter == 5:
+            year += 1
+            quarter = 1
+            
+    wait(gpu_dfs)
+    t2 = datetime.datetime.now()
+    print("Reading time: {0}".format(str(t2-t1)))
+    print('--->>> Number of data parts: {0}'.format(len(gpu_dfs)))
+
+    dxgb_gpu_params = {
+        'nround':            100,
+        'max_depth':         8,
+        'max_leaves':        2**8,
+        'alpha':             0.9,
+        'eta':               0.1,
+        'gamma':             0.1,
+        'learning_rate':     0.1,
+        'subsample':         1,
+        'reg_lambda':        1,
+        'scale_pos_weight':  2,
+        'min_child_weight':  30,
+        'tree_method':       'gpu_hist',
+        'n_gpus':            1, 
+        'distributed_dask':  True,
+        'loss':              'ls',
+        'objective':         'reg:squarederror',
+        'max_features':      'auto',
+        'criterion':         'friedman_mse',
+        'grow_policy':       'lossguide',
+        'verbose':           True
+    }
+      
+    if cpu_predictor:
+        print('\n---->>>> Training using CPUs <<<<----\n')
+        dxgb_gpu_params['predictor'] = 'cpu_predictor'
+        dxgb_gpu_params['tree_method'] = 'hist'
+        dxgb_gpu_params['objective'] = 'reg:linear'
+        
+    else:
+        print('\n---->>>> Training using GPUs <<<<----\n')
+    
+    print('Training parameters are {0}'.format(dxgb_gpu_params))
+    
+    gpu_dfs = [delayed(DataFrame.from_arrow)(gpu_df) for gpu_df in gpu_dfs[:part_count]]
+    gpu_dfs = [gpu_df for gpu_df in gpu_dfs]
+    wait(gpu_dfs)
+    
+    tmp_map = [(gpu_df, list(client.who_has(gpu_df).values())[0]) for gpu_df in gpu_dfs]
+    new_map = {}
+    for key, value in tmp_map:
+        if value not in new_map:
+            new_map[value] = [key]
+        else:
+            new_map[value].append(key)
+    
+    del(tmp_map)
+    gpu_dfs = []
+    for list_delayed in new_map.values():
+        gpu_dfs.append(delayed(cudf.concat)(list_delayed))
+    
+    del(new_map)
+    gpu_dfs = [(gpu_df[['delinquency_12']], gpu_df[delayed(list)(gpu_df.columns.difference(['delinquency_12']))]) for gpu_df in gpu_dfs]
+    gpu_dfs = [(gpu_df[0].persist(), gpu_df[1].persist()) for gpu_df in gpu_dfs]
+    
+    gpu_dfs = [dask.delayed(xgb.DMatrix)(gpu_df[1], gpu_df[0]) for gpu_df in gpu_dfs]
+    gpu_dfs = [gpu_df.persist() for gpu_df in gpu_dfs]
+    gc.collect()
+    wait(gpu_dfs)
+
+    # TRAIN THE MODEL
+    labels = None
+    t1 = datetime.datetime.now()
+    bst = dxgb_gpu.train(client, dxgb_gpu_params, gpu_dfs, labels, num_boost_round=dxgb_gpu_params['nround'])
+    t2 = datetime.datetime.now()
+    print('\n---->>>> Training time: {0} <<<<----\n'.format(str(t2-t1)))
+    print('Exiting script')
+
+if __name__ == '__main__':
+    main()

contrib/fairness/fairlearn-azureml-mitigation.ipynb

@@ -0,0 +1,621 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Copyright (c) Microsoft Corporation. All rights reserved.  \n",
+        "Licensed under the MIT License."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "![Impressions](https://PixelServer20190423114238.azurewebsites.net/api/impressions/MachineLearningNotebooks/contrib/fairness/fairlearn-azureml-mitigation.png)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Unfairness Mitigation with Fairlearn and Azure Machine Learning\n",
+        "**This notebook shows how to upload results from Fairlearn's GridSearch mitigation algorithm into a dashboard in Azure Machine Learning Studio**\n",
+        "\n",
+        "## Table of Contents\n",
+        "\n",
+        "1. [Introduction](#Introduction)\n",
+        "1. [Loading the Data](#LoadingData)\n",
+        "1. [Training an Unmitigated Model](#UnmitigatedModel)\n",
+        "1. [Mitigation with GridSearch](#Mitigation)\n",
+        "1. [Uploading a Fairness Dashboard to Azure](#AzureUpload)\n",
+        "    1. Registering models\n",
+        "    1. Computing Fairness Metrics\n",
+        "    1. Uploading to Azure\n",
+        "1. [Conclusion](#Conclusion)\n",
+        "\n",
+        "<a id=\"Introduction\"></a>\n",
+        "## Introduction\n",
+        "This notebook shows how to use [Fairlearn (an open source fairness assessment and unfairness mitigation package)](http://fairlearn.org) and Azure Machine Learning Studio for a binary classification problem. This example uses the well-known adult census dataset. For the purposes of this notebook, we shall treat this as a loan decision problem. We will pretend that the label indicates whether or not each individual repaid a loan in the past. We will use the data to train a predictor to predict whether previously unseen individuals will repay a loan or not. The assumption is that the model predictions are used to decide whether an individual should be offered a loan. Its purpose is purely illustrative of a workflow including a fairness dashboard - in particular, we do **not** include a full discussion of the detailed issues which arise when considering fairness in machine learning. For such discussions, please [refer to the Fairlearn website](http://fairlearn.org/).\n",
+        "\n",
+        "We will apply the [grid search algorithm](https://fairlearn.org/v0.4.6/api_reference/fairlearn.reductions.html#fairlearn.reductions.GridSearch) from the Fairlearn package using a specific notion of fairness called Demographic Parity. This produces a set of models, and we will view these in a dashboard both locally and in the Azure Machine Learning Studio.\n",
+        "\n",
+        "### Setup\n",
+        "\n",
+        "To use this notebook, an Azure Machine Learning workspace is required.\n",
+        "Please see the [configuration notebook](../../configuration.ipynb) for information about creating one, if required.\n",
+        "This notebook also requires the following packages:\n",
+        "* `azureml-contrib-fairness`\n",
+        "* `fairlearn>=0.6.2` (pre-v0.5.0 will work with minor modifications)\n",
+        "* `joblib`\n",
+        "* `liac-arff`\n",
+        "* `raiwidgets`\n",
+        "\n",
+        "Fairlearn relies on features introduced in v0.22.1 of `scikit-learn`. If you have an older version already installed, please uncomment and run the following cell:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# !pip install --upgrade scikit-learn>=0.22.1"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Finally, please ensure that when you downloaded this notebook, you also downloaded the `fairness_nb_utils.py` file from the same location, and placed it in the same directory as this notebook."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"LoadingData\"></a>\n",
+        "## Loading the Data\n",
+        "We use the well-known `adult` census dataset, which we will fetch from the OpenML website. We start with a fairly unremarkable set of imports:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from fairlearn.reductions import GridSearch, DemographicParity, ErrorRate\n",
+        "from raiwidgets import FairnessDashboard\n",
+        "\n",
+        "from sklearn.compose import ColumnTransformer\n",
+        "from sklearn.impute import SimpleImputer\n",
+        "from sklearn.linear_model import LogisticRegression\n",
+        "from sklearn.model_selection import train_test_split\n",
+        "from sklearn.preprocessing import StandardScaler, OneHotEncoder\n",
+        "from sklearn.compose import make_column_selector as selector\n",
+        "from sklearn.pipeline import Pipeline\n",
+        "\n",
+        "import pandas as pd"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can now load and inspect the data:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from fairness_nb_utils import fetch_census_dataset\n",
+        "\n",
+        "data = fetch_census_dataset()\n",
+        "    \n",
+        "# Extract the items we want\n",
+        "X_raw = data.data\n",
+        "y = (data.target == '>50K') * 1\n",
+        "\n",
+        "X_raw[\"race\"].value_counts().to_dict()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We are going to treat the sex and race of each individual as protected attributes, and in this particular case we are going to remove these attributes from the main data (this is not always the best option - see the [Fairlearn website](http://fairlearn.github.io/) for further discussion). Protected attributes are often denoted by 'A' in the literature, and we follow that convention here:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "A = X_raw[['sex','race']]\n",
+        "X_raw = X_raw.drop(labels=['sex', 'race'], axis = 1)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We now preprocess our data. To avoid the problem of data leakage, we split our data into training and test sets before performing any other transformations. Subsequent transformations (such as scalings) will be fit to the training data set, and then applied to the test dataset."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "(X_train, X_test, y_train, y_test, A_train, A_test) = train_test_split(\n",
+        "    X_raw, y, A, test_size=0.3, random_state=12345, stratify=y\n",
+        ")\n",
+        "\n",
+        "# Ensure indices are aligned between X, y and A,\n",
+        "# after all the slicing and splitting of DataFrames\n",
+        "# and Series\n",
+        "\n",
+        "X_train = X_train.reset_index(drop=True)\n",
+        "X_test = X_test.reset_index(drop=True)\n",
+        "y_train = y_train.reset_index(drop=True)\n",
+        "y_test = y_test.reset_index(drop=True)\n",
+        "A_train = A_train.reset_index(drop=True)\n",
+        "A_test = A_test.reset_index(drop=True)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We have two types of column in the dataset - categorical columns which will need to be one-hot encoded, and numeric ones which will need to be rescaled. We also need to take care of missing values. We use a simple approach here, but please bear in mind that this is another way that bias could be introduced (especially if one subgroup tends to have more missing values).\n",
+        "\n",
+        "For this preprocessing, we make use of `Pipeline` objects from `sklearn`:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "numeric_transformer = Pipeline(\n",
+        "    steps=[\n",
+        "        (\"impute\", SimpleImputer()),\n",
+        "        (\"scaler\", StandardScaler()),\n",
+        "    ]\n",
+        ")\n",
+        "\n",
+        "categorical_transformer = Pipeline(\n",
+        "    [\n",
+        "        (\"impute\", SimpleImputer(strategy=\"most_frequent\")),\n",
+        "        (\"ohe\", OneHotEncoder(handle_unknown=\"ignore\", sparse=False)),\n",
+        "    ]\n",
+        ")\n",
+        "\n",
+        "preprocessor = ColumnTransformer(\n",
+        "    transformers=[\n",
+        "        (\"num\", numeric_transformer, selector(dtype_exclude=\"category\")),\n",
+        "        (\"cat\", categorical_transformer, selector(dtype_include=\"category\")),\n",
+        "    ]\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Now, the preprocessing pipeline is defined, we can run it on our training data, and apply the generated transform to our test data:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "X_train = preprocessor.fit_transform(X_train)\n",
+        "X_test = preprocessor.transform(X_test)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"UnmitigatedModel\"></a>\n",
+        "## Training an Unmitigated Model\n",
+        "\n",
+        "So we have a point of comparison, we first train a model (specifically, logistic regression from scikit-learn) on the raw data, without applying any mitigation algorithm:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "unmitigated_predictor = LogisticRegression(solver='liblinear', fit_intercept=True)\n",
+        "\n",
+        "unmitigated_predictor.fit(X_train, y_train)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can view this model in the fairness dashboard, and see the disparities which appear:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "FairnessDashboard(sensitive_features=A_test,\n",
+        "                  y_true=y_test,\n",
+        "                  y_pred={\"unmitigated\": unmitigated_predictor.predict(X_test)})"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Looking at the disparity in accuracy when we select 'Sex' as the sensitive feature, we see that males have an error rate about three times greater than the females. More interesting is the disparity in opportunitiy - males are offered loans at three times the rate of females.\n",
+        "\n",
+        "Despite the fact that we removed the feature from the training data, our predictor still discriminates based on sex. This demonstrates that simply ignoring a protected attribute when fitting a predictor rarely eliminates unfairness. There will generally be enough other features correlated with the removed attribute to lead to disparate impact."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"Mitigation\"></a>\n",
+        "## Mitigation with GridSearch\n",
+        "\n",
+        "The `GridSearch` class in `Fairlearn` implements a simplified version of the exponentiated gradient reduction of [Agarwal et al. 2018](https://arxiv.org/abs/1803.02453). The user supplies a standard ML estimator, which is treated as a blackbox - for this simple example, we shall use the logistic regression estimator from scikit-learn. `GridSearch` works by generating a sequence of relabellings and reweightings, and trains a predictor for each.\n",
+        "\n",
+        "For this example, we specify demographic parity (on the protected attribute of sex) as the fairness metric. Demographic parity requires that individuals are offered the opportunity (a loan in this example) independent of membership in the protected class (i.e., females and males should be offered loans at the same rate). *We are using this metric for the sake of simplicity* in this example; the appropriate fairness metric can only be selected after *careful examination of the broader context* in which the model is to be used."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "sweep = GridSearch(LogisticRegression(solver='liblinear', fit_intercept=True),\n",
+        "                   constraints=DemographicParity(),\n",
+        "                   grid_size=71)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "With our estimator created, we can fit it to the data. After `fit()` completes, we extract the full set of predictors from the `GridSearch` object.\n",
+        "\n",
+        "The following cell trains a many copies of the underlying estimator, and may take a minute or two to run:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "sweep.fit(X_train, y_train,\n",
+        "          sensitive_features=A_train.sex)\n",
+        "\n",
+        "# For Fairlearn pre-v0.5.0, need sweep._predictors\n",
+        "predictors = sweep.predictors_"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We could load these predictors into the Fairness dashboard now. However, the plot would be somewhat confusing due to their number. In this case, we are going to remove the predictors which are dominated in the error-disparity space by others from the sweep (note that the disparity will only be calculated for the protected attribute; other potentially protected attributes will *not* be mitigated). In general, one might not want to do this, since there may be other considerations beyond the strict optimisation of error and disparity (of the given protected attribute)."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "errors, disparities = [], []\n",
+        "for predictor in predictors:\n",
+        "    error = ErrorRate()\n",
+        "    error.load_data(X_train, pd.Series(y_train), sensitive_features=A_train.sex)\n",
+        "    disparity = DemographicParity()\n",
+        "    disparity.load_data(X_train, pd.Series(y_train), sensitive_features=A_train.sex)\n",
+        "    \n",
+        "    errors.append(error.gamma(predictor.predict)[0])\n",
+        "    disparities.append(disparity.gamma(predictor.predict).max())\n",
+        "    \n",
+        "all_results = pd.DataFrame( {\"predictor\": predictors, \"error\": errors, \"disparity\": disparities})\n",
+        "\n",
+        "dominant_models_dict = dict()\n",
+        "base_name_format = \"census_gs_model_{0}\"\n",
+        "row_id = 0\n",
+        "for row in all_results.itertuples():\n",
+        "    model_name = base_name_format.format(row_id)\n",
+        "    errors_for_lower_or_eq_disparity = all_results[\"error\"][all_results[\"disparity\"]<=row.disparity]\n",
+        "    if row.error <= errors_for_lower_or_eq_disparity.min():\n",
+        "        dominant_models_dict[model_name] = row.predictor\n",
+        "    row_id = row_id + 1"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can construct predictions for the dominant models (we include the unmitigated predictor as well, for comparison):"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "predictions_dominant = {\"census_unmitigated\": unmitigated_predictor.predict(X_test)}\n",
+        "models_dominant = {\"census_unmitigated\": unmitigated_predictor}\n",
+        "for name, predictor in dominant_models_dict.items():\n",
+        "    value = predictor.predict(X_test)\n",
+        "    predictions_dominant[name] = value\n",
+        "    models_dominant[name] = predictor"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "These predictions may then be viewed in the fairness dashboard. We include the race column from the dataset, as an alternative basis for assessing the models. However, since we have not based our mitigation on it, the variation in the models with respect to race can be large."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "FairnessDashboard(sensitive_features=A_test, \n",
+        "                  y_true=y_test.tolist(),\n",
+        "                  y_pred=predictions_dominant)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "When using sex as the sensitive feature and accuracy as the metric, we see a Pareto front forming - the set of predictors which represent optimal tradeoffs between accuracy and disparity in predictions. In the ideal case, we would have a predictor at (1,0) - perfectly accurate and without any unfairness under demographic parity (with respect to the protected attribute \"sex\"). The Pareto front represents the closest we can come to this ideal based on our data and choice of estimator. Note the range of the axes - the disparity axis covers more values than the accuracy, so we can reduce disparity substantially for a small loss in accuracy. Finally, we also see that the unmitigated model is towards the top right of the plot, with high accuracy, but worst disparity.\n",
+        "\n",
+        "By clicking on individual models on the plot, we can inspect their metrics for disparity and accuracy in greater detail. In a real example, we would then pick the model which represented the best trade-off between accuracy and disparity given the relevant business constraints."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"AzureUpload\"></a>\n",
+        "## Uploading a Fairness Dashboard to Azure\n",
+        "\n",
+        "Uploading a fairness dashboard to Azure is a two stage process. The `FairnessDashboard` invoked in the previous section relies on the underlying Python kernel to compute metrics on demand. This is obviously not available when the fairness dashboard is rendered in AzureML Studio. By default, the dashboard in Azure Machine Learning Studio also requires the models to be registered. The required stages are therefore:\n",
+        "1. Register the dominant models\n",
+        "1. Precompute all the required metrics\n",
+        "1. Upload to Azure\n",
+        "\n",
+        "Before that, we need to connect to Azure Machine Learning Studio:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from azureml.core import Workspace, Experiment, Model\n",
+        "\n",
+        "ws = Workspace.from_config()\n",
+        "ws.get_details()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"RegisterModels\"></a>\n",
+        "### Registering Models\n",
+        "\n",
+        "The fairness dashboard is designed to integrate with registered models, so we need to do this for the models we want in the Studio portal. The assumption is that the names of the models specified in the dashboard dictionary correspond to the `id`s (i.e. `<name>:<version>` pairs) of registered models in the workspace. We register each of the models in the `models_dominant` dictionary into the workspace. For this, we have to save each model to a file, and then register that file:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import joblib\n",
+        "import os\n",
+        "\n",
+        "os.makedirs('models', exist_ok=True)\n",
+        "def register_model(name, model):\n",
+        "    print(\"Registering \", name)\n",
+        "    model_path = \"models/{0}.pkl\".format(name)\n",
+        "    joblib.dump(value=model, filename=model_path)\n",
+        "    registered_model = Model.register(model_path=model_path,\n",
+        "                                      model_name=name,\n",
+        "                                      workspace=ws)\n",
+        "    print(\"Registered \", registered_model.id)\n",
+        "    return registered_model.id\n",
+        "\n",
+        "model_name_id_mapping = dict()\n",
+        "for name, model in models_dominant.items():\n",
+        "    m_id = register_model(name, model)\n",
+        "    model_name_id_mapping[name] = m_id"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Now, produce new predictions dictionaries, with the updated names:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "predictions_dominant_ids = dict()\n",
+        "for name, y_pred in predictions_dominant.items():\n",
+        "    predictions_dominant_ids[model_name_id_mapping[name]] = y_pred"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"PrecomputeMetrics\"></a>\n",
+        "### Precomputing Metrics\n",
+        "\n",
+        "We create a _dashboard dictionary_ using Fairlearn's `metrics` package. The `_create_group_metric_set` method has arguments similar to the Dashboard constructor, except that the sensitive features are passed as a dictionary (to ensure that names are available), and we must specify the type of prediction. Note that we use the `predictions_dominant_ids` dictionary we just created:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "sf = { 'sex': A_test.sex, 'race': A_test.race }\n",
+        "\n",
+        "from fairlearn.metrics._group_metric_set import _create_group_metric_set\n",
+        "\n",
+        "\n",
+        "dash_dict = _create_group_metric_set(y_true=y_test,\n",
+        "                                     predictions=predictions_dominant_ids,\n",
+        "                                     sensitive_features=sf,\n",
+        "                                     prediction_type='binary_classification')"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"DashboardUpload\"></a>\n",
+        "### Uploading the Dashboard\n",
+        "\n",
+        "Now, we import our `contrib` package which contains the routine to perform the upload:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from azureml.contrib.fairness import upload_dashboard_dictionary, download_dashboard_by_upload_id"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Now we can create an Experiment, then a Run, and upload our dashboard to it:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "exp = Experiment(ws, \"Test_Fairlearn_GridSearch_Census_Demo\")\n",
+        "print(exp)\n",
+        "\n",
+        "run = exp.start_logging()\n",
+        "try:\n",
+        "    dashboard_title = \"Dominant Models from GridSearch\"\n",
+        "    upload_id = upload_dashboard_dictionary(run,\n",
+        "                                            dash_dict,\n",
+        "                                            dashboard_name=dashboard_title)\n",
+        "    print(\"\\nUploaded to id: {0}\\n\".format(upload_id))\n",
+        "\n",
+        "    downloaded_dict = download_dashboard_by_upload_id(run, upload_id)\n",
+        "finally:\n",
+        "    run.complete()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The dashboard can be viewed in the Run Details page.\n",
+        "\n",
+        "Finally, we can verify that the dashboard dictionary which we downloaded matches our upload:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "print(dash_dict == downloaded_dict)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"Conclusion\"></a>\n",
+        "## Conclusion\n",
+        "\n",
+        "In this notebook we have demonstrated how to use the `GridSearch` algorithm from Fairlearn to generate a collection of models, and then present them in the fairness dashboard in Azure Machine Learning Studio. Please remember that this notebook has not attempted to discuss the many considerations which should be part of any approach to unfairness mitigation. The [Fairlearn website](http://fairlearn.org/) provides that discussion"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": []
+    }
+  ],
+  "metadata": {
+    "authors": [
+      {
+        "name": "riedgar"
+      }
+    ],
+    "kernelspec": {
+      "display_name": "Python 3.6",
+      "language": "python",
+      "name": "python36"
+    },
+    "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.10"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 2
+}

contrib/fairness/fairlearn-azureml-mitigation.yml

@@ -0,0 +1,11 @@
+name: fairlearn-azureml-mitigation
+dependencies:
+- pip:
+  - azureml-sdk
+  - azureml-contrib-fairness
+  - fairlearn>=0.6.2
+  - joblib
+  - liac-arff
+  - raiwidgets~=0.17.0
+  - itsdangerous==2.0.1
+  - markupsafe<2.1.0

contrib/fairness/fairness_nb_utils.py

@@ -0,0 +1,111 @@
+# ---------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# ---------------------------------------------------------
+
+"""Utilities for azureml-contrib-fairness notebooks."""
+
+import arff
+from collections import OrderedDict
+from contextlib import closing
+import gzip
+import pandas as pd
+from sklearn.datasets import fetch_openml
+from sklearn.utils import Bunch
+import time
+
+
+def fetch_openml_with_retries(data_id, max_retries=4, retry_delay=60):
+    """Fetch a given dataset from OpenML with retries as specified."""
+    for i in range(max_retries):
+        try:
+            print("Download attempt {0} of {1}".format(i + 1, max_retries))
+            data = fetch_openml(data_id=data_id, as_frame=True)
+            break
+        except Exception as e:  # noqa: B902
+            print("Download attempt failed with exception:")
+            print(e)
+            if i + 1 != max_retries:
+                print("Will retry after {0} seconds".format(retry_delay))
+                time.sleep(retry_delay)
+                retry_delay = retry_delay * 2
+    else:
+        raise RuntimeError("Unable to download dataset from OpenML")
+
+    return data
+
+
+_categorical_columns = [
+    'workclass',
+    'education',
+    'marital-status',
+    'occupation',
+    'relationship',
+    'race',
+    'sex',
+    'native-country'
+]
+
+
+def fetch_census_dataset():
+    """Fetch the Adult Census Dataset.
+
+    This uses a particular URL for the Adult Census dataset. The code
+    is a simplified version of fetch_openml() in sklearn.
+
+    The data are copied from:
+    https://openml.org/data/v1/download/1595261.gz
+    (as of 2021-03-31)
+    """
+    try:
+        from urllib import urlretrieve
+    except ImportError:
+        from urllib.request import urlretrieve
+
+    filename = "1595261.gz"
+    data_url = "https://rainotebookscdn.blob.core.windows.net/datasets/"
+
+    remaining_attempts = 5
+    sleep_duration = 10
+    while remaining_attempts > 0:
+        try:
+            urlretrieve(data_url + filename, filename)
+
+            http_stream = gzip.GzipFile(filename=filename, mode='rb')
+
+            with closing(http_stream):
+                def _stream_generator(response):
+                    for line in response:
+                        yield line.decode('utf-8')
+
+                stream = _stream_generator(http_stream)
+                data = arff.load(stream)
+        except Exception as exc:  # noqa: B902
+            remaining_attempts -= 1
+            print("Error downloading dataset from {} ({} attempt(s) remaining)"
+                  .format(data_url, remaining_attempts))
+            print(exc)
+            time.sleep(sleep_duration)
+            sleep_duration *= 2
+            continue
+        else:
+            # dataset successfully downloaded
+            break
+    else:
+        raise Exception("Could not retrieve dataset from {}.".format(data_url))
+
+    attributes = OrderedDict(data['attributes'])
+    arff_columns = list(attributes)
+
+    raw_df = pd.DataFrame(data=data['data'], columns=arff_columns)
+
+    target_column_name = 'class'
+    target = raw_df.pop(target_column_name)
+    for col_name in _categorical_columns:
+        dtype = pd.api.types.CategoricalDtype(attributes[col_name])
+        raw_df[col_name] = raw_df[col_name].astype(dtype, copy=False)
+
+    result = Bunch()
+    result.data = raw_df
+    result.target = target
+
+    return result

contrib/fairness/upload-fairness-dashboard.ipynb

@@ -0,0 +1,545 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Copyright (c) Microsoft Corporation. All rights reserved.  \n",
+        "Licensed under the MIT License."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "![Impressions](https://PixelServer20190423114238.azurewebsites.net/api/impressions/MachineLearningNotebooks/contrib/fairness/upload-fairness-dashboard.png)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Upload a Fairness Dashboard to Azure Machine Learning Studio\n",
+        "**This notebook shows how to generate and upload a fairness assessment dashboard from Fairlearn to AzureML Studio**\n",
+        "\n",
+        "## Table of Contents\n",
+        "\n",
+        "1. [Introduction](#Introduction)\n",
+        "1. [Loading the Data](#LoadingData)\n",
+        "1. [Processing the Data](#ProcessingData)\n",
+        "1. [Training Models](#TrainingModels)\n",
+        "1. [Logging in to AzureML](#LoginAzureML)\n",
+        "1. [Registering the Models](#RegisterModels)\n",
+        "1. [Using the Fairness Dashboard](#LocalDashboard)\n",
+        "1. [Uploading a Fairness Dashboard to Azure](#AzureUpload)\n",
+        "    1. Computing Fairness Metrics\n",
+        "    1. Uploading to Azure\n",
+        "1. [Conclusion](#Conclusion)\n",
+        "    \n",
+        "\n",
+        "<a id=\"Introduction\"></a>\n",
+        "## Introduction\n",
+        "\n",
+        "In this notebook, we walk through a simple example of using the `azureml-contrib-fairness` package to upload a collection of fairness statistics for a fairness dashboard. It is an example of integrating the [open source Fairlearn package](https://www.github.com/fairlearn/fairlearn) with Azure Machine Learning. This is not an example of fairness analysis or mitigation - this notebook simply shows how to get a fairness dashboard into the Azure Machine Learning portal. We will load the data and train a couple of simple models. We will then use Fairlearn to generate data for a Fairness dashboard, which we can upload to Azure Machine Learning portal and view there.\n",
+        "\n",
+        "### Setup\n",
+        "\n",
+        "To use this notebook, an Azure Machine Learning workspace is required.\n",
+        "Please see the [configuration notebook](../../configuration.ipynb) for information about creating one, if required.\n",
+        "This notebook also requires the following packages:\n",
+        "* `azureml-contrib-fairness`\n",
+        "* `fairlearn>=0.6.2` (also works for pre-v0.5.0 with slight modifications)\n",
+        "* `joblib`\n",
+        "* `liac-arff`\n",
+        "* `raiwidgets`\n",
+        "\n",
+        "Fairlearn relies on features introduced in v0.22.1 of `scikit-learn`. If you have an older version already installed, please uncomment and run the following cell:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "# !pip install --upgrade scikit-learn>=0.22.1"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Finally, please ensure that when you downloaded this notebook, you also downloaded the `fairness_nb_utils.py` file from the same location, and placed it in the same directory as this notebook."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"LoadingData\"></a>\n",
+        "## Loading the Data\n",
+        "We use the well-known `adult` census dataset, which we fetch from the OpenML website. We start with a fairly unremarkable set of imports:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from sklearn import svm\n",
+        "from sklearn.compose import ColumnTransformer\n",
+        "from sklearn.impute import SimpleImputer\n",
+        "from sklearn.linear_model import LogisticRegression\n",
+        "from sklearn.model_selection import train_test_split\n",
+        "from sklearn.preprocessing import StandardScaler, OneHotEncoder\n",
+        "from sklearn.compose import make_column_selector as selector\n",
+        "from sklearn.pipeline import Pipeline"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Now we can load the data:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from fairness_nb_utils import fetch_census_dataset\n",
+        "\n",
+        "data = fetch_census_dataset()\n",
+        "    \n",
+        "# Extract the items we want\n",
+        "X_raw = data.data\n",
+        "y = (data.target == '>50K') * 1"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can take a look at some of the data. For example, the next cells shows the counts of the different races identified in the dataset:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "print(X_raw[\"race\"].value_counts().to_dict())"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"ProcessingData\"></a>\n",
+        "## Processing the Data\n",
+        "\n",
+        "With the data loaded, we process it for our needs. First, we extract the sensitive features of interest into `A` (conventionally used in the literature) and leave the rest of the feature data in `X_raw`:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "A = X_raw[['sex','race']]\n",
+        "X_raw = X_raw.drop(labels=['sex', 'race'],axis = 1)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We now preprocess our data. To avoid the problem of data leakage, we split our data into training and test sets before performing any other transformations. Subsequent transformations (such as scalings) will be fit to the training data set, and then applied to the test dataset."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "(X_train, X_test, y_train, y_test, A_train, A_test) = train_test_split(\n",
+        "    X_raw, y, A, test_size=0.3, random_state=12345, stratify=y\n",
+        ")\n",
+        "\n",
+        "# Ensure indices are aligned between X, y and A,\n",
+        "# after all the slicing and splitting of DataFrames\n",
+        "# and Series\n",
+        "\n",
+        "X_train = X_train.reset_index(drop=True)\n",
+        "X_test = X_test.reset_index(drop=True)\n",
+        "y_train = y_train.reset_index(drop=True)\n",
+        "y_test = y_test.reset_index(drop=True)\n",
+        "A_train = A_train.reset_index(drop=True)\n",
+        "A_test = A_test.reset_index(drop=True)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We have two types of column in the dataset - categorical columns which will need to be one-hot encoded, and numeric ones which will need to be rescaled. We also need to take care of missing values. We use a simple approach here, but please bear in mind that this is another way that bias could be introduced (especially if one subgroup tends to have more missing values).\n",
+        "\n",
+        "For this preprocessing, we make use of `Pipeline` objects from `sklearn`:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "numeric_transformer = Pipeline(\n",
+        "    steps=[\n",
+        "        (\"impute\", SimpleImputer()),\n",
+        "        (\"scaler\", StandardScaler()),\n",
+        "    ]\n",
+        ")\n",
+        "\n",
+        "categorical_transformer = Pipeline(\n",
+        "    [\n",
+        "        (\"impute\", SimpleImputer(strategy=\"most_frequent\")),\n",
+        "        (\"ohe\", OneHotEncoder(handle_unknown=\"ignore\", sparse=False)),\n",
+        "    ]\n",
+        ")\n",
+        "\n",
+        "preprocessor = ColumnTransformer(\n",
+        "    transformers=[\n",
+        "        (\"num\", numeric_transformer, selector(dtype_exclude=\"category\")),\n",
+        "        (\"cat\", categorical_transformer, selector(dtype_include=\"category\")),\n",
+        "    ]\n",
+        ")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Now, the preprocessing pipeline is defined, we can run it on our training data, and apply the generated transform to our test data:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "X_train = preprocessor.fit_transform(X_train)\n",
+        "X_test = preprocessor.transform(X_test)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"TrainingModels\"></a>\n",
+        "## Training Models\n",
+        "\n",
+        "We now train a couple of different models on our data. The `adult` census dataset is a classification problem - the goal is to predict whether a particular individual exceeds an income threshold. For the purpose of generating a dashboard to upload, it is sufficient to train two basic classifiers. First, a logistic regression classifier:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "lr_predictor = LogisticRegression(solver='liblinear', fit_intercept=True)\n",
+        "\n",
+        "lr_predictor.fit(X_train, y_train)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "And for comparison, a support vector classifier:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "svm_predictor = svm.SVC()\n",
+        "\n",
+        "svm_predictor.fit(X_train, y_train)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"LoginAzureML\"></a>\n",
+        "## Logging in to AzureML\n",
+        "\n",
+        "With our two classifiers trained, we can log into our AzureML workspace:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from azureml.core import Workspace, Experiment, Model\n",
+        "\n",
+        "ws = Workspace.from_config()\n",
+        "ws.get_details()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"RegisterModels\"></a>\n",
+        "## Registering the Models\n",
+        "\n",
+        "Next, we register our models. By default, the subroutine which uploads the models checks that the names provided correspond to registered models in the workspace. We define a utility routine to do the registering:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "import joblib\n",
+        "import os\n",
+        "\n",
+        "os.makedirs('models', exist_ok=True)\n",
+        "def register_model(name, model):\n",
+        "    print(\"Registering \", name)\n",
+        "    model_path = \"models/{0}.pkl\".format(name)\n",
+        "    joblib.dump(value=model, filename=model_path)\n",
+        "    registered_model = Model.register(model_path=model_path,\n",
+        "                                      model_name=name,\n",
+        "                                      workspace=ws)\n",
+        "    print(\"Registered \", registered_model.id)\n",
+        "    return registered_model.id"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Now, we register the models. For convenience in subsequent method calls, we store the results in a dictionary, which maps the `id` of the registered model (a string in `name:version` format) to the predictor itself:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "model_dict = {}\n",
+        "\n",
+        "lr_reg_id = register_model(\"fairness_linear_regression\", lr_predictor)\n",
+        "model_dict[lr_reg_id] = lr_predictor\n",
+        "svm_reg_id = register_model(\"fairness_svm\", svm_predictor)\n",
+        "model_dict[svm_reg_id] = svm_predictor"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"LocalDashboard\"></a>\n",
+        "## Using the Fairlearn Dashboard\n",
+        "\n",
+        "We can now examine the fairness of the two models we have training, both as a function of race and (binary) sex. Before uploading the dashboard to the AzureML portal, we will first instantiate a local instance of the Fairlearn dashboard.\n",
+        "\n",
+        "Regardless of the viewing location, the dashboard is based on three things - the true values, the model predictions and the sensitive feature values. The dashboard can use predictions from multiple models and multiple sensitive features if desired (as we are doing here).\n",
+        "\n",
+        "Our first step is to generate a dictionary mapping the `id` of the registered model to the corresponding array of predictions:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "ys_pred = {}\n",
+        "for n, p in model_dict.items():\n",
+        "    ys_pred[n] = p.predict(X_test)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "We can examine these predictions in a locally invoked Fairlearn dashboard. This can be compared to the dashboard uploaded to the portal (in the next section):"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from raiwidgets import FairnessDashboard\n",
+        "\n",
+        "FairnessDashboard(sensitive_features=A_test, \n",
+        "                  y_true=y_test.tolist(),\n",
+        "                  y_pred=ys_pred)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"AzureUpload\"></a>\n",
+        "## Uploading a Fairness Dashboard to Azure\n",
+        "\n",
+        "Uploading a fairness dashboard to Azure is a two stage process. The `FairnessDashboard` invoked in the previous section relies on the underlying Python kernel to compute metrics on demand. This is obviously not available when the fairness dashboard is rendered in AzureML Studio. The required stages are therefore:\n",
+        "1. Precompute all the required metrics\n",
+        "1. Upload to Azure\n",
+        "\n",
+        "\n",
+        "### Computing Fairness Metrics\n",
+        "We use Fairlearn to create a dictionary which contains all the data required to display a dashboard. This includes both the raw data (true values, predicted values and sensitive features), and also the fairness metrics. The API is similar to that used to invoke the Dashboard locally. However, there are a few minor changes to the API, and the type of problem being examined (binary classification, regression etc.) needs to be specified explicitly:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "sf = { 'Race': A_test.race, 'Sex': A_test.sex }\n",
+        "\n",
+        "from fairlearn.metrics._group_metric_set import _create_group_metric_set\n",
+        "\n",
+        "dash_dict = _create_group_metric_set(y_true=y_test,\n",
+        "                                     predictions=ys_pred,\n",
+        "                                     sensitive_features=sf,\n",
+        "                                     prediction_type='binary_classification')"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "The `_create_group_metric_set()` method is currently underscored since its exact design is not yet final in Fairlearn."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "### Uploading to Azure\n",
+        "\n",
+        "We can now import the `azureml.contrib.fairness` package itself. We will round-trip the data, so there are two required subroutines:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "from azureml.contrib.fairness import upload_dashboard_dictionary, download_dashboard_by_upload_id"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Finally, we can upload the generated dictionary to AzureML. The upload method requires a run, so we first create an experiment and a run. The uploaded dashboard can be seen on the corresponding Run Details page in AzureML Studio. For completeness, we also download the dashboard dictionary which we uploaded."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "exp = Experiment(ws, \"notebook-01\")\n",
+        "print(exp)\n",
+        "\n",
+        "run = exp.start_logging()\n",
+        "try:\n",
+        "    dashboard_title = \"Sample notebook upload\"\n",
+        "    upload_id = upload_dashboard_dictionary(run,\n",
+        "                                            dash_dict,\n",
+        "                                            dashboard_name=dashboard_title)\n",
+        "    print(\"\\nUploaded to id: {0}\\n\".format(upload_id))\n",
+        "\n",
+        "    downloaded_dict = download_dashboard_by_upload_id(run, upload_id)\n",
+        "finally:\n",
+        "    run.complete()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Finally, we can verify that the dashboard dictionary which we downloaded matches our upload:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "print(dash_dict == downloaded_dict)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "<a id=\"Conclusion\"></a>\n",
+        "## Conclusion\n",
+        "\n",
+        "In this notebook we have demonstrated how to generate and upload a fairness dashboard to AzureML Studio. We have not discussed how to analyse the results and apply mitigations. Those topics will be covered elsewhere."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": []
+    }
+  ],
+  "metadata": {
+    "authors": [
+      {
+        "name": "riedgar"
+      }
+    ],
+    "kernelspec": {
+      "display_name": "Python 3.6",
+      "language": "python",
+      "name": "python36"
+    },
+    "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.10"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 4
+}

contrib/fairness/upload-fairness-dashboard.yml

@@ -0,0 +1,11 @@
+name: upload-fairness-dashboard
+dependencies:
+- pip:
+  - azureml-sdk
+  - azureml-contrib-fairness
+  - fairlearn>=0.6.2
+  - joblib
+  - liac-arff
+  - raiwidgets~=0.17.0
+  - itsdangerous==2.0.1
+  - markupsafe<2.1.0