{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Model Understanding\n",
    "\n",
    "Simply examining a model's performance metrics is not enough to select a model and promote it for use in a production setting. While developing an ML algorithm, it is important to understand how the model behaves on the data, to examine the key factors influencing its predictions and to consider where it may be deficient. Determination of what \"success\" may mean for an ML project depends first and foremost on the user's domain expertise.\n",
    "\n",
    "EvalML includes a variety of tools for understanding models, from graphing utilities to methods for explaining predictions.\n",
    "\n",
    "\n",
    "** Graphing methods on Jupyter Notebook and Jupyter Lab require [ipywidgets](https://ipywidgets.readthedocs.io/en/latest/user_install.html) to be installed.\n",
    "\n",
    "** If graphing on Jupyter Lab, [jupyterlab-plotly](https://plotly.com/python/getting-started/#jupyterlab-support-python-35) required. To download this, make sure you have [npm](https://nodejs.org/en/download/) installed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Explaining Feature Influence"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The EvalML package offers a variety of methods for understanding which features in a dataset have an impact on the output of the model. We can investigate this either through feature importance or through permutation importance, and leverage either in generating more readable explanations.\n",
    "\n",
    "First, let's train a pipeline on some data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import evalml\n",
    "from evalml.pipelines import BinaryClassificationPipeline\n",
    "\n",
    "X, y = evalml.demos.load_breast_cancer()\n",
    "\n",
    "X_train, X_holdout, y_train, y_holdout = evalml.preprocessing.split_data(\n",
    "    X, y, problem_type=\"binary\", test_size=0.2, random_seed=0\n",
    ")\n",
    "\n",
    "\n",
    "pipeline_binary = BinaryClassificationPipeline(\n",
    "    component_graph={\n",
    "        \"Label Encoder\": [\"Label Encoder\", \"X\", \"y\"],\n",
    "        \"Imputer\": [\"Imputer\", \"X\", \"Label Encoder.y\"],\n",
    "        \"Random Forest Classifier\": [\n",
    "            \"Random Forest Classifier\",\n",
    "            \"Imputer.x\",\n",
    "            \"Label Encoder.y\",\n",
    "        ],\n",
    "    }\n",
    ")\n",
    "pipeline_binary.fit(X_train, y_train)\n",
    "print(pipeline_binary.score(X_holdout, y_holdout, objectives=[\"log loss binary\"]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Feature Importance\n",
    "\n",
    "We can get the importance associated with each feature of the resulting pipeline"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pipeline_binary.feature_importance"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also create a bar plot of the feature importances"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pipeline_binary.graph_feature_importance()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we have a linear model, we can also view feature importance by simply inspecting the coefficients of the model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding import get_linear_coefficients\n",
    "\n",
    "pipeline_linear = BinaryClassificationPipeline(\n",
    "    component_graph={\n",
    "        \"Label Encoder\": [\"Label Encoder\", \"X\", \"y\"],\n",
    "        \"Imputer\": [\"Imputer\", \"X\", \"Label Encoder.y\"],\n",
    "        \"Logistic Regression Classifier\": [\n",
    "            \"Logistic Regression Classifier\",\n",
    "            \"Imputer.x\",\n",
    "            \"Label Encoder.y\",\n",
    "        ],\n",
    "    }\n",
    ")\n",
    "pipeline_linear.fit(X_train, y_train)\n",
    "\n",
    "get_linear_coefficients(pipeline_linear.estimator, features=X.columns)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Permutation Importance\n",
    "\n",
    "We can also compute and plot [the permutation importance](https://scikit-learn.org/stable/modules/permutation_importance.html) of the pipeline."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding import calculate_permutation_importance\n",
    "\n",
    "calculate_permutation_importance(\n",
    "    pipeline_binary, X_holdout, y_holdout, \"log loss binary\"\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding import graph_permutation_importance\n",
    "\n",
    "graph_permutation_importance(pipeline_binary, X_holdout, y_holdout, \"log loss binary\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Human Readable Importance\n",
    "\n",
    "We can generate a more human-comprehensible understanding of either the feature or permutation importance by using `readable_explanation(pipeline)`. This picks out a subset of features that have the highest impact on the output of the model, sorting them into either \"heavily\" or \"somewhat\" influential on the model. These features are selected either by feature importance or permutation importance with a given objective. If there are any features that actively decrease the performance of the pipeline, this function highlights those and recommends removal.\n",
    "\n",
    "Note that permutation importance runs on the original input features, while feature importance runs on the features as they were passed in to the final estimator, having gone through a number of preprocessing steps. The two methods will highlight different features as being important, and feature names may vary as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding import readable_explanation\n",
    "\n",
    "readable_explanation(\n",
    "    pipeline_binary,\n",
    "    X_holdout,\n",
    "    y_holdout,\n",
    "    objective=\"log loss binary\",\n",
    "    importance_method=\"permutation\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "readable_explanation(\n",
    "    pipeline_binary, importance_method=\"feature\"\n",
    ")  # feature importance doesn't require X and y"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can adjust the number of most important features visible with the `max_features` argument, or modify the minimum threshold for \"importance\" with `min_importance_threshold`. However, these values will not affect any detrimental features displayed, as this function always displays all of them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Metrics for Model Understanding"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Confusion Matrix\n",
    "\n",
    "For binary or multiclass classification, we can view a [confusion matrix](https://en.wikipedia.org/wiki/Confusion_matrix) of the classifier's predictions. In the DataFrame output of `confusion_matrix()`, the column header represents the predicted labels while row header represents the actual labels."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.metrics import confusion_matrix\n",
    "\n",
    "y_pred = pipeline_binary.predict(X_holdout)\n",
    "confusion_matrix(y_holdout, y_pred)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.metrics import graph_confusion_matrix\n",
    "\n",
    "y_pred = pipeline_binary.predict(X_holdout)\n",
    "graph_confusion_matrix(y_holdout, y_pred)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Precision-Recall Curve\n",
    "\n",
    "For binary classification, we can view the precision-recall curve of the pipeline."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.metrics import graph_precision_recall_curve\n",
    "\n",
    "# get the predicted probabilities associated with the \"true\" label\n",
    "import woodwork as ww\n",
    "\n",
    "y_encoded = y_holdout.ww.map({\"benign\": 0, \"malignant\": 1})\n",
    "y_pred_proba = pipeline_binary.predict_proba(X_holdout)[\"malignant\"]\n",
    "graph_precision_recall_curve(y_encoded, y_pred_proba)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ROC Curve\n",
    "\n",
    "For binary and multiclass classification, we can view the [Receiver Operating Characteristic (ROC) curve](https://en.wikipedia.org/wiki/Receiver_operating_characteristic) of the pipeline."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.metrics import graph_roc_curve\n",
    "\n",
    "# get the predicted probabilities associated with the \"malignant\" label\n",
    "y_pred_proba = pipeline_binary.predict_proba(X_holdout)[\"malignant\"]\n",
    "graph_roc_curve(y_encoded, y_pred_proba)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ROC curve can also be generated for multiclass classification problems. For multiclass problems, the graph will show a one-vs-many ROC curve for each class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.pipelines import MulticlassClassificationPipeline\n",
    "\n",
    "X_multi, y_multi = evalml.demos.load_wine()\n",
    "\n",
    "pipeline_multi = MulticlassClassificationPipeline(\n",
    "    [\"Simple Imputer\", \"Random Forest Classifier\"]\n",
    ")\n",
    "pipeline_multi.fit(X_multi, y_multi)\n",
    "\n",
    "y_pred_proba = pipeline_multi.predict_proba(X_multi)\n",
    "graph_roc_curve(y_multi, y_pred_proba)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualizations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Binary Objective Score vs. Threshold Graph\n",
    "\n",
    "Some [binary classification objectives](./objectives.ipynb) (objectives that have `score_needs_proba` set to False) are sensitive to a decision threshold. For those objectives, we can obtain and graph the scores for thresholds from zero to one, calculated at evenly-spaced intervals determined by `steps`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.visualizations import binary_objective_vs_threshold\n",
    "\n",
    "binary_objective_vs_threshold(pipeline_binary, X_holdout, y_holdout, \"f1\", steps=10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.visualizations import (\n",
    "    graph_binary_objective_vs_threshold,\n",
    ")\n",
    "\n",
    "graph_binary_objective_vs_threshold(\n",
    "    pipeline_binary, X_holdout, y_holdout, \"f1\", steps=100\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Predicted Vs Actual Values Graph for Regression Problems\n",
    "\n",
    "We can also create a scatterplot comparing predicted vs actual values for regression problems. We can specify an `outlier_threshold` to color values differently if the absolute difference between the actual and predicted values are outside of a given threshold. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.visualizations import graph_prediction_vs_actual\n",
    "from evalml.pipelines import RegressionPipeline\n",
    "\n",
    "X_regress, y_regress = evalml.demos.load_diabetes()\n",
    "X_train_reg, X_test_reg, y_train_reg, y_test_reg = evalml.preprocessing.split_data(\n",
    "    X_regress, y_regress, problem_type=\"regression\"\n",
    ")\n",
    "\n",
    "pipeline_regress = RegressionPipeline([\"One Hot Encoder\", \"Linear Regressor\"])\n",
    "pipeline_regress.fit(X_train_reg, y_train_reg)\n",
    "\n",
    "y_pred = pipeline_regress.predict(X_test_reg)\n",
    "graph_prediction_vs_actual(y_test_reg, y_pred, outlier_threshold=50)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tree Visualization\n",
    "\n",
    "Now let's train a decision tree on some data. We can visualize the structure of the Decision Tree that was fit to that data, and save it if necessary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pipeline_dt = BinaryClassificationPipeline(\n",
    "    [\"Simple Imputer\", \"Decision Tree Classifier\"]\n",
    ")\n",
    "pipeline_dt.fit(X_train, y_train)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.visualizations import visualize_decision_tree\n",
    "\n",
    "visualize_decision_tree(\n",
    "    pipeline_dt.estimator, max_depth=2, rotate=False, filled=True, filepath=None\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Confusion Matrix and Thresholds for Binary Classification Pipelines\n",
    "\n",
    "For binary classification pipelines, EvalML also provides the ability to compare the actual positive and actual negative histograms, as well as obtaining the confusion matrices and ideal thresholds per objective."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding import find_confusion_matrix_per_thresholds\n",
    "\n",
    "df, objective_thresholds = find_confusion_matrix_per_thresholds(\n",
    "    pipeline_binary, X, y, n_bins=10\n",
    ")\n",
    "df.head(10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "objective_thresholds"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the above results, the first dataframe contains the histograms for the actual positive and negative classes, indicated by `true_pos_count` and `true_neg_count`. The columns `true_positives`, `true_negatives`, `false_positives`, and `false_negatives` contain the confusion matrix information for the associated threshold, and the `data_in_bins` holds a random subset of row indices (both postive and negative) that belong in each bin. The index of the dataframe represents the associated threshold. For instance, at index `0.1`, there is 1 positive and 309 negative rows that fall between `[0.0, 0.1]`.\n",
    "\n",
    "The returned `objective_thresholds` dictionary has the objective measure as the key, and the dictionary value associated contains both the best objective score and the threshold that results in the associated score."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visualize high dimensional data in lower space\n",
    "\n",
    "We can use [T-SNE](https://evalml.alteryx.com/en/stable/autoapi/evalml/model_understanding/index.html#evalml.model_understanding.graph_t_sne) to visualize data with many features on a 2D plot, making it easier to see relationships in your data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Our data is highly dimensional, we can't plot this in a way we understand\n",
    "print(len(X.columns))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding import graph_t_sne\n",
    "\n",
    "fig = graph_t_sne(X)\n",
    "fig"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Partial Dependence Plots\n",
    "We can calculate the one-way [partial dependence plots](https://christophm.github.io/interpretable-ml-book/pdp.html) for a feature."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding import partial_dependence\n",
    "\n",
    "partial_dependence(\n",
    "    pipeline_binary, X_holdout, features=\"mean radius\", grid_resolution=5\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding import graph_partial_dependence\n",
    "\n",
    "graph_partial_dependence(\n",
    "    pipeline_binary, X_holdout, features=\"mean radius\", grid_resolution=5\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also compute the partial dependence for a categorical feature. We will demonstrate this on the fraud dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "X_fraud, y_fraud = evalml.demos.load_fraud(100, verbose=False)\n",
    "X_fraud.ww.init(\n",
    "    logical_types={\n",
    "        \"provider\": \"Categorical\",\n",
    "        \"region\": \"Categorical\",\n",
    "        \"currency\": \"Categorical\",\n",
    "        \"expiration_date\": \"Categorical\",\n",
    "    }\n",
    ")\n",
    "\n",
    "fraud_pipeline = BinaryClassificationPipeline(\n",
    "    [\"DateTime Featurizer\", \"One Hot Encoder\", \"Random Forest Classifier\"]\n",
    ")\n",
    "fraud_pipeline.fit(X_fraud, y_fraud)\n",
    "\n",
    "graph_partial_dependence(fraud_pipeline, X_fraud, features=\"provider\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Two-way partial dependence plots are also possible and invoke the same API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "partial_dependence(\n",
    "    pipeline_binary,\n",
    "    X_holdout,\n",
    "    features=(\"worst perimeter\", \"worst radius\"),\n",
    "    grid_resolution=5,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "graph_partial_dependence(\n",
    "    pipeline_binary,\n",
    "    X_holdout,\n",
    "    features=(\"worst perimeter\", \"worst radius\"),\n",
    "    grid_resolution=5,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Explaining Predictions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can explain why the model made certain predictions with the [explain_predictions](../autoapi/evalml/model_understanding/prediction_explanations/explainers/index.rst#evalml.model_understanding.prediction_explanations.explainers.explain_predictions) function. This can use either the [Shapley Additive Explanations (SHAP)](https://github.com/slundberg/shap) algorithm or the [Local Interpretable Model-agnostic Explanations (LIME)](https://github.com/marcotcr/lime) algorithm to identify the top features that explain the predicted value. \n",
    "\n",
    "This function can explain both classification and regression models - all you need to do is provide the pipeline, the input features, and a list of rows corresponding to the indices of the input features you want to explain. The function will return a table that you can print summarizing the top 3 most positive and negative contributing features to the predicted value.\n",
    "\n",
    "In the example below, we explain the prediction for the third data point in the data set. We see that the `worst concave points` feature increased the estimated probability that the tumor is malignant by 20% while the `worst radius` feature decreased the probability the tumor is malignant by 5%.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.prediction_explanations import explain_predictions\n",
    "\n",
    "table = explain_predictions(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X_holdout,\n",
    "    y=None,\n",
    "    indices_to_explain=[3],\n",
    "    top_k_features=6,\n",
    "    include_explainer_values=True,\n",
    ")\n",
    "print(table)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The interpretation of the table is the same for regression problems - but the SHAP value now corresponds to the change in the estimated value of the dependent variable rather than a change in probability. For multiclass classification problems, a table will be output for each possible class.\n",
    "\n",
    "Below is an example of how you would explain three predictions with [explain_predictions](../autoapi/evalml/model_understanding/prediction_explanations/explainers/index.rst#evalml.model_understanding.prediction_explanations.explainers.explain_predictions)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.prediction_explanations import explain_predictions\n",
    "\n",
    "report = explain_predictions(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X_holdout,\n",
    "    y=y_holdout,\n",
    "    indices_to_explain=[0, 4, 9],\n",
    "    include_explainer_values=True,\n",
    "    output_format=\"text\",\n",
    ")\n",
    "print(report)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above examples used the SHAP algorithm, since that is what `explain_predictions` uses by default. If you would like to use LIME instead, you can change that with the `algorithm=\"lime\"` argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.prediction_explanations import explain_predictions\n",
    "\n",
    "table = explain_predictions(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X_holdout,\n",
    "    y=None,\n",
    "    indices_to_explain=[3],\n",
    "    top_k_features=6,\n",
    "    include_explainer_values=True,\n",
    "    algorithm=\"lime\",\n",
    ")\n",
    "print(table)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.prediction_explanations import explain_predictions\n",
    "\n",
    "report = explain_predictions(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X_holdout,\n",
    "    y=None,\n",
    "    indices_to_explain=[0, 4, 9],\n",
    "    include_explainer_values=True,\n",
    "    output_format=\"text\",\n",
    "    algorithm=\"lime\",\n",
    ")\n",
    "print(report)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Explaining Best and Worst Predictions\n",
    "\n",
    "When debugging machine learning models, it is often useful to analyze the best and worst predictions the model made. The [explain_predictions_best_worst](../autoapi/evalml/model_understanding/prediction_explanations/explainers/index.rst#evalml.model_understanding.prediction_explanations.explainers.explain_predictions_best_worst) function can help us with this.\n",
    "\n",
    "This function will display the output of [explain_predictions](../autoapi/evalml/model_understanding/prediction_explanations/explainers/index.rst#evalml.model_understanding.prediction_explanations.explainers.explain_predictions) for the best 2 and worst 2 predictions. By default, the best and worst predictions are determined by the absolute error for regression problems and [cross entropy](https://en.wikipedia.org/wiki/Cross_entropy) for classification problems.\n",
    "\n",
    "We can specify our own ranking function by passing in a function to the `metric` parameter. This function will be called on `y_true` and `y_pred`. By convention, lower scores are better.\n",
    "\n",
    "At the top of each table, we can see the predicted probabilities, target value, error, and row index for that prediction. For a regression problem, we would see the predicted value instead of predicted probabilities.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from evalml.model_understanding.prediction_explanations import (\n",
    "    explain_predictions_best_worst,\n",
    ")\n",
    "\n",
    "shap_report = explain_predictions_best_worst(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X_holdout,\n",
    "    y_true=y_holdout,\n",
    "    include_explainer_values=True,\n",
    "    top_k_features=6,\n",
    "    num_to_explain=2,\n",
    ")\n",
    "\n",
    "print(shap_report)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lime_report = explain_predictions_best_worst(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X_holdout,\n",
    "    y_true=y_holdout,\n",
    "    include_explainer_values=True,\n",
    "    top_k_features=6,\n",
    "    num_to_explain=2,\n",
    "    algorithm=\"lime\",\n",
    ")\n",
    "\n",
    "print(lime_report)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We use a custom metric ([hinge loss](https://en.wikipedia.org/wiki/Hinge_loss)) for selecting the best and worst predictions. See this example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "\n",
    "def hinge_loss(y_true, y_pred_proba):\n",
    "    probabilities = np.clip(y_pred_proba.iloc[:, 1], 0.001, 0.999)\n",
    "    y_true[y_true == 0] = -1\n",
    "\n",
    "    return np.clip(\n",
    "        1 - y_true * np.log(probabilities / (1 - probabilities)), a_min=0, a_max=None\n",
    "    )\n",
    "\n",
    "\n",
    "report = explain_predictions_best_worst(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X,\n",
    "    y_true=y,\n",
    "    include_explainer_values=True,\n",
    "    num_to_explain=5,\n",
    "    metric=hinge_loss,\n",
    ")\n",
    "\n",
    "print(report)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Changing Output Formats\n",
    "\n",
    "Instead of getting the prediction explanations as text, you can get the report as a python dictionary or pandas dataframe. All you have to do is pass `output_format=\"dict\"` or `output_format=\"dataframe\"` to either `explain_prediction`, `explain_predictions`, or `explain_predictions_best_worst`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Single prediction as a dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "\n",
    "single_prediction_report = explain_predictions(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X_holdout,\n",
    "    indices_to_explain=[3],\n",
    "    y=y_holdout,\n",
    "    top_k_features=6,\n",
    "    include_explainer_values=True,\n",
    "    output_format=\"dict\",\n",
    ")\n",
    "print(json.dumps(single_prediction_report, indent=2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Single prediction as a dataframe"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "single_prediction_report = explain_predictions(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X_holdout,\n",
    "    indices_to_explain=[3],\n",
    "    y=y_holdout,\n",
    "    top_k_features=6,\n",
    "    include_explainer_values=True,\n",
    "    output_format=\"dataframe\",\n",
    ")\n",
    "single_prediction_report"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Best and worst predictions as a dictionary"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "report = explain_predictions_best_worst(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X,\n",
    "    y_true=y,\n",
    "    num_to_explain=1,\n",
    "    top_k_features=6,\n",
    "    include_explainer_values=True,\n",
    "    output_format=\"dict\",\n",
    ")\n",
    "print(json.dumps(report, indent=2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Best and worst predictions as a dataframe"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "report = explain_predictions_best_worst(\n",
    "    pipeline=pipeline_binary,\n",
    "    input_features=X_holdout,\n",
    "    y_true=y_holdout,\n",
    "    num_to_explain=1,\n",
    "    top_k_features=6,\n",
    "    include_explainer_values=True,\n",
    "    output_format=\"dataframe\",\n",
    ")\n",
    "report"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Force Plots\n",
    "Force plots can be generated to predict single or multiple rows for binary, multiclass and regression problem types. These use the SHAP algorithm. Here's an example of predicting a single row on a binary classification dataset.  The force plots show the predictive power of each of the features in making the negative (\"Class: 0\") prediction and the positive (\"Class: 1\") prediction. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import shap\n",
    "\n",
    "from evalml.model_understanding.force_plots import graph_force_plot\n",
    "\n",
    "rows_to_explain = [0]  # Should be a list of integer indices of the rows to explain.\n",
    "\n",
    "results = graph_force_plot(\n",
    "    pipeline_binary,\n",
    "    rows_to_explain=rows_to_explain,\n",
    "    training_data=X_holdout,\n",
    "    y=y_holdout,\n",
    ")\n",
    "\n",
    "for result in results:\n",
    "    for cls in result:\n",
    "        print(\"Class:\", cls)\n",
    "        display(result[cls][\"plot\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's an example of a force plot explaining multiple predictions on a multiclass problem.  These plots show the force plots for each row arranged as consecutive columns that can be ordered by the dropdown above.  Clicking the column indicates which row explanation is underneath."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rows_to_explain = [\n",
    "    0,\n",
    "    1,\n",
    "    2,\n",
    "    3,\n",
    "    4,\n",
    "]  # Should be a list of integer indices of the rows to explain.\n",
    "\n",
    "results = graph_force_plot(\n",
    "    pipeline_multi, rows_to_explain=rows_to_explain, training_data=X_multi, y=y_multi\n",
    ")\n",
    "\n",
    "for idx, result in enumerate(results):\n",
    "    print(\"Row:\", idx)\n",
    "    for cls in result:\n",
    "        print(\"Class:\", cls)\n",
    "        display(result[cls][\"plot\"])"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.8.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}