{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8bf3a3e1",
   "metadata": {},
   "source": [
    "# Getting Started"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1491dd2",
   "metadata": {},
   "source": [
    "This getting started notebook is an overview of the functionality in this repository.  Note that this notebook is not runnable, it has a high-level overview of the APIs available and contains links to other notebooks in the repository."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2bf7fe3a",
   "metadata": {},
   "source": [
    "## Installation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "07303d17",
   "metadata": {},
   "source": [
    "Use the following `pip` commands to install the Responsible AI Toolbox.\n",
    "\n",
    "If running in jupyter, please make sure to restart the jupyter kernel after installing."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "756f5f51",
   "metadata": {},
   "source": [
    "!pip install raiwidgets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "60dca68e",
   "metadata": {},
   "source": [
    "## Dependencies"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1bf0e821",
   "metadata": {},
   "source": [
    "Please make sure to have the latest version of pandas installed if you are planning to use the error analysis component."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f2ae1cd",
   "metadata": {},
   "source": [
    "!pip install --upgrade pandas"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f46ea6a5",
   "metadata": {},
   "source": [
    "## Overview & Setup"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da3c519c",
   "metadata": {},
   "source": [
    "Responsible AI Toolbox is an interoperable, customizable tool that empowers machine learning practitioners to evaluate their models and data based on their place in the model lifecycle.\n",
    "\n",
    "Users may select components whose functionality supports their current objectives. First, the RAIInsights and ResponsibleAIDashboard must be imported."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "428f2b2d",
   "metadata": {},
   "source": [
    "```Python\n",
    "from raiwidgets import ResponsibleAIDashboard\n",
    "from responsibleai import RAIInsights\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f152ac8",
   "metadata": {},
   "source": [
    "Users will need to load a dataset, spit it into train and test datasets, and train a model on the training dataset."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "88a8e0fd",
   "metadata": {},
   "source": [
    "It is necessary to initialize a RAIInsights object upon which the different components can be loaded. `task_type` holds the string `'regression'` or `'classification'` depending on the developer's purpose.\n",
    "\n",
    "Users can also specify categorical features via the `categorical_features` parameter.\n",
    "\n",
    "Using the `FeatureMetadata` container, you can declare an `identity_feature`, and specify features to withhold from the model via the `dropped_features` parameter. The `FeatureMetadata` serves as an input argument for `RAIInsights`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c9433f32",
   "metadata": {},
   "source": [
    "```Python\n",
    "from responsibleai.feature_metadata import FeatureMetadata\n",
    "# Add 's1' as an identity feature, set 'age' as a dropped feature\n",
    "feature_metadata = FeatureMetadata(identity_feature_name='s1', dropped_features=['age'])\n",
    "\n",
    "task_type = 'regression'\n",
    "\n",
    "rai_insights = RAIInsights(model, train_data, test_data, target_feature, task_type, categorical_features=[], feature_metadata=feature_metadata)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c360364e",
   "metadata": {},
   "source": [
    "The Interpretability and Error Analysis components can be added to the dashboard without any additional arguments.\n",
    "\n",
    "For an example, please see the [census classification model debugging notebook](https://github.com/microsoft/responsible-ai-toolbox/blob/main/notebooks/responsibleaidashboard/responsibleaidashboard-census-classification-model-debugging.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "407571b5",
   "metadata": {},
   "source": [
    "```Python\n",
    "rai_insights.explainer.add()\n",
    "rai_insights.error_analysis.add()\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "714655b3",
   "metadata": {},
   "source": [
    "The Causal Inferencing component must be added with a specification of the feature that would be changed as a treatment.\n",
    "\n",
    "For an example, please see the [diabetes decision making notebook](https://github.com/microsoft/responsible-ai-toolbox/blob/main/notebooks/responsibleaidashboard/responsibleaidashboard-diabetes-decision-making.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "70f6f73e",
   "metadata": {},
   "source": [
    "```Python\n",
    "rai_insights.causal.add(treatment_features=['bmi', 'bp', 's2'])\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7f5e8f45",
   "metadata": {},
   "source": [
    "The Counterfactuals component takes arguments specifying the number of counterfactuals to generate, the list of columns containing continuous values, and the desired label of the counterfactuals."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "308d93ad",
   "metadata": {},
   "source": [
    "In a classification situation, `desired_class` must specify the classification that the generated counterfactuals would fall into.\n",
    "\n",
    "For an example, please see the [housing classification model debugging notebook](https://github.com/microsoft/responsible-ai-toolbox/blob/main/notebooks/responsibleaidashboard/responsibleaidashboard-housing-classification-model-debugging.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7c244f2",
   "metadata": {},
   "source": [
    "```Python\n",
    "rai_insights.counterfactual.add(total_CFs=20, desired_class='opposite')\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa9ec639",
   "metadata": {},
   "source": [
    "In a regression situation, `desired_range` must specify the minimum and maximum label that the generated counterfactuals can have.\n",
    "For an example, please see the [diabetes regression model debugging notebook](https://github.com/microsoft/responsible-ai-toolbox/blob/main/notebooks/responsibleaidashboard/responsibleaidashboard-diabetes-regression-model-debugging.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "824449d9",
   "metadata": {},
   "source": [
    "```Python\n",
    "rai_insights.counterfactual.add(total_CFs=20, desired_range=[50, 120])\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3031a740",
   "metadata": {},
   "source": [
    "## Computing and Visualizing Insights"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b3a4aec0",
   "metadata": {},
   "source": [
    "After loading the components into the RAIInsights object, it is necessary to calculate values relevant to them, such as model metrics and counterfactuals."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3e534a3",
   "metadata": {},
   "source": [
    "```Python\n",
    "rai_insights.compute()\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d2e05195",
   "metadata": {},
   "source": [
    "Once the values for each component have been computed, they can be displayed by loading the RAIInsights object into a ResponsibleAIDashboard."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3188e42d",
   "metadata": {},
   "source": [
    "```Python\n",
    "ResponsibleAIDashboard(rai_insights)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17df1a35",
   "metadata": {},
   "source": [
    "## Learn More"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10b56cde",
   "metadata": {},
   "source": [
    "Visit the [GitHub](https://github.com/microsoft/responsible-ai-widgets) of Responsible AI Toolbox for more details, and take this [dashboard tour](./tour.ipynb) for an explanation of the different parts of each component."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}