notebook_examples/text_classification-model_explanation-lime.ipynb

{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "@notebook{text_classification-model_explanation-lime.ipynb,\n",
    "    title: Text Classification and Model Explanations using LIME,\n",
    "    summary: Perform model explanations on an NLP classifier using the locally interpretable model explanations technique (LIME).,\n",
    "    developed_on: nlp_p37_cpu_v2,\n",
    "    keywords: nlp, lime, model_explanation, text_classification, text_explanation, \n",
    "    license: Universal Permissive License v 1.0\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Upgrade Oracle ADS to pick up latest features and maintain compatibility with Oracle Cloud Infrastructure.\n",
    "\n",
    "!pip install -U oracle-ads"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Oracle Data Science service sample notebook.\n",
    "\n",
    "Copyright (c) 2021 Oracle, Inc. All rights reserved. Licensed under the [Universal Permissive License v 1.0](https://oss.oracle.com/licenses/upl).\n",
    "\n",
    "---\n",
    "\n",
    "# <font color=\"red\">Text Classification and Model Explanations using LIME</font>\n",
    "<p style=\"margin-left:10%; margin-right:10%;\">by the <font color=\"teal\">Oracle Cloud Infrastructure Data Science Service.</font></p>\n",
    "\n",
    "---\n",
    "\n",
    "# Overview:\n",
    "\n",
    "This notebook demonstrates an example of peforming model explanations on an NLP classifier using a surrogate model technique called \"Locally Interpretable Model Explanations\" (LIME). \n",
    "\n",
    "Specifically, it focuses on training a Decision Tree multiclass classification model using the 20 Newsgroups dataset. It illustrates how to do this using two different implementations of LIME within the NLP conda pack.\n",
    " \n",
    "The 20 Newsgroups dataset is used in this notebook. The original dataset has 20 different categories with 11,314 news documents in the training dataset, and 7,532 in the testing dataset. \n",
    "\n",
    "Compatible conda pack: [Natural Language Processing](https://docs.oracle.com/en-us/iaas/data-science/using/conda-nlp-fam.htm) for CPU on Python 3.7 (version 2.0)\n",
    "\n",
    "---\n",
    "\n",
    "## Contents:\n",
    "\n",
    "- <a href='#loaddataset'>Load the Dataset</a>\n",
    "- <a href='#xgboost'>Train the Decision Tree Model</a>\n",
    "- <a href='#eli5'>Model Explanation Using an Eli5 package</a>\n",
    "    - <a href='#eli5-global'>Global Explanation</a>\n",
    "    - <a href='#eli5-local'>Local Explanation</a>\n",
    "    - <a href='#eli5-Lime'>Inpect Black-Box Models Using a Lime Algorithm</a>\n",
    "- <a href='#lime'>Model Explanation Using a Lime Package</a>\n",
    "- <a href='#ref'>References</a>\n",
    "\n",
    "---\n",
    "\n",
    "\n",
    "Datasets are provided as a convenience.  Datasets are considered third-party content and are not considered materials \n",
    "under your agreement with Oracle.\n",
    "    \n",
    "You can access the `20 Newsgroups` dataset license [here](https://github.com/scikit-learn/scikit-learn/blob/master/COPYING).\n",
    "\n",
    "---\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import eli5\n",
    "import nltk\n",
    "import numpy as np\n",
    "import os\n",
    "import pandas as pd\n",
    "import string\n",
    "\n",
    "\n",
    "from nltk import word_tokenize\n",
    "from sklearn.datasets import fetch_20newsgroups\n",
    "from sklearn.feature_extraction.text import TfidfVectorizer\n",
    "from sklearn.pipeline import Pipeline\n",
    "from sklearn.tree import DecisionTreeClassifier\n",
    "\n",
    "pd.set_option(\"display.max_colwidth\", None)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Need to get the punkt word tokenizer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nltk.download(\"punkt\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='loaddataset'></a>\n",
    "## Load the Dataset\n",
    "\n",
    "First, create a `TwentyNewsDataset` class to load news data and do simple preprocessing to prepare data for model training."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class TwentyNewsDataset:\n",
    "    def __init__(self, data=\"train\", categories=None):\n",
    "        self.data = fetch_20newsgroups(\n",
    "            subset=data,\n",
    "            categories=categories,\n",
    "            shuffle=True,\n",
    "            random_state=42,\n",
    "            remove=(\"headers\", \"footers\"),\n",
    "        )\n",
    "\n",
    "    def load_data(self):\n",
    "        labels = [self.data[\"target_names\"][x] for x in self.data[\"target\"]]\n",
    "\n",
    "        # preprocessing\n",
    "        processed_data = []\n",
    "        for s in self.data[\"data\"]:\n",
    "            new_s = s.translate(str.maketrans(\"\", \"\", string.punctuation))\n",
    "            processed_data.append(new_s)\n",
    "        return processed_data, labels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Initialize the class and load the data for the train and test dataset. Only four of the twenty categories are included to simplify this example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "categories = [\"sci.med\", \"rec.autos\", \"misc.forsale\"]\n",
    "train_data, train_label = TwentyNewsDataset(categories=categories).load_data()\n",
    "test_data, test_label = TwentyNewsDataset(\n",
    "    data=\"test\", categories=categories\n",
    ").load_data()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='Decision Tree'></a>\n",
    "## Train the Decision Tree Model\n",
    "\n",
    "Next, you use sklearns `TfidfVectorizer` to transform the text data into feature vectors, and then train a Decision Tree model using scikit-learns `DecisionTreeClassifier`. The bigrams and trigrams are included as features alongside unigrams (words)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tf_vectorizer = TfidfVectorizer(\n",
    "    stop_words=\"english\", analyzer=\"word\", ngram_range=(1, 3)\n",
    ")\n",
    "\n",
    "trainx = tf_vectorizer.fit_transform(train_data)\n",
    "testx = tf_vectorizer.transform(test_data)\n",
    "\n",
    "\n",
    "dt_classifier = DecisionTreeClassifier()\n",
    "dt_classifier.fit(trainx, train_label)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, create a `Pipeline` object to make your model code more modular, which makes it easier to try different kinds of preprocessing or vectorization:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "predict_pipeline = Pipeline([(\"vectorizer\", tf_vectorizer), (\"model\", dt_classifier)])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Take a look at the performace of your trained model:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "predict_pipeline.score(test_data, test_label)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can use the `predict` and `predict_proba` methods of the `Pipeline` object to transform and predict the probablity of different classes on any test data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(train_data[0])\n",
    "\n",
    "print(predict_pipeline.predict_proba([train_data[0]]))\n",
    "print(predict_pipeline.predict([train_data[0]]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, try this model on an unseen example as a sanity check:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "predict_pipeline.predict([\"Cars are very exciting!\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='eli5'></a>\n",
    "\n",
    "## Model Explanation Using an Eli5 Package\n",
    "\n",
    "When you evaluate a machine learning model, you want to know why the model makes incorrect predictions. You can leverage model explanation libraries to understand why a model makes the prediction that it does. Using model explanations (even surrogate ones) aids in interpretating the model. Otherwise the model may be a black-box and so is unusable in many domains.\n",
    "\n",
    "Model explanations can be classified into two different categories, global or local explanations. Global explainability techniques seeks to explain the entire model behavior by inspecting model features. While local explanations checks an individual prediction of a model and shows why the model makes that particular decision. Local iexplanation methods tend to be easier to apply to any kind of model than global explanations are. \n",
    "\n",
    "The [Eli5 package](https://eli5.readthedocs.io/en/latest/overview.html#features) is helpful to demonstrate model explanations. It supports common machine learning libraries and frameworks and implements algorithms for the inpection of black-box models."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='eli5-global'></a>\n",
    "### Global Explanation\n",
    "\n",
    "Feature importance is a good way to demonstrate global explanation. Eli5 implements permutation importance method to calculate feature importance for any black-box estimator. In this example, this is not as useful because Decision Tree models supports directly calculating feature importance. This example can be used with a model that doesn't support these direct calculations too. \n",
    "\n",
    "To show global explanation, you can simply call the `show_weights` method from the eli5 package, pass in the trained classifer, and optionally configure a few other parameters. The output shows the features (words, bigrams, and trigrams) ranked by its weight trained in your model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "eli5.show_weights(\n",
    "    estimator=dt_classifier, vec=tf_vectorizer, top=10, target_names=categories\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='eli5-local'></a>\n",
    "### Local Explanation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To inspect a single prediction of the model on directly white-box models like Decision Trees, use the `show_prediction()` method and pass in any test data you want the model to predict. The results show the prediction score for each class and the feature contribution to the predicted class ranked by its weight."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "eli5.show_prediction(\n",
    "    estimator=dt_classifier,\n",
    "    doc=train_data[0],\n",
    "    top=10,\n",
    "    vec=tf_vectorizer,\n",
    "    target_names=categories,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What if your model is not a white-box? "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='eli5-Lime'></a>\n",
    "### Inpect Black-Box Models Using a LIME Algorithm\n",
    "\n",
    "Eli5 implements the LIME algorithm to interpret a [black-box classfier](https://eli5.readthedocs.io/en/latest/tutorials/black-box-text-classifiers.html) using a locally-fit white-box classifier for text data:\n",
    "\n",
    "- Create a fake text dataset using perturbed versions of the text.\n",
    "- Use the black-box classifier to predict on the generated fake dataset.\n",
    "- Train a white-box classifier on the faked data with the black-box classifiers predicted labels.\n",
    "- Interpret the original model through weights of this white-box estimator instead."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The next cell is an example of using the LIME algorithm and a surrogate linear model to interpret our Decision Tree model. The results show the prediction score for each class and the highlighted text based on the feature contribution of each word to the predicted class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from eli5.lime import TextExplainer\n",
    "\n",
    "te = TextExplainer(random_state=42)\n",
    "\n",
    "te.fit(train_data[3], predict_pipeline.predict_proba)\n",
    "te.show_prediction(target_names=categories)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can investigate the quality on a held out dataset from the generated data by calling the `metrics_` attribute to see if the explanation using LIME algorithm is accurate and can be trusted:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "te.metrics_"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also check the generated fake dataset by calling the `samples_` attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(te.samples_[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Besides the implementation of LIME found with the `Eli5` package, there is also an implementation of LIME from the authors of its paper."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='lime'></a>\n",
    "## Model Explanation Using a LIME Package\n",
    "\n",
    "The LIME package focuses on local model interpretable and model-agnostic part only.\n",
    "\n",
    "Similar to the Lime algorithm in Eli5 package, the [algorithm](https://github.com/marcotcr/lime)also perturbs the original dataset, but it uses to a sparse linear model to explain the black-box model.\n",
    "\n",
    "This is a simple example showing how to use LIME API for local explanation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from lime.lime_text import LimeTextExplainer\n",
    "\n",
    "explainer = LimeTextExplainer(class_names=categories)\n",
    "\n",
    "exp = explainer.explain_instance(\n",
    "    train_data[0], predict_pipeline.predict_proba, num_features=10, top_labels=5\n",
    ")\n",
    "\n",
    "exp.show_in_notebook()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id=\"ref\"></a>\n",
    "# References\n",
    "\n",
    "- [ADS Library Documentation](https://accelerated-data-science.readthedocs.io/en/latest/index.html)\n",
    "- [Data Science YouTube Videos](https://www.youtube.com/playlist?list=PLKCk3OyNwIzv6CWMhvqSB_8MLJIZdO80L)\n",
    "- [OCI Data Science Documentation](https://docs.cloud.oracle.com/en-us/iaas/data-science/using/data-science.htm)\n",
    "- [Oracle Data & AI Blog](https://blogs.oracle.com/datascience/)"
   ]
  }
 ],
 "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.15"
  },
  "vscode": {
   "interpreter": {
    "hash": "1a1af0ee75eeea9e2e1ee996c87e7a2b11a0bebd85af04bb136d915cefc0abce"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}