LORE_Tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "32c02afe",
   "metadata": {},
   "source": [
    "# Tutorial: explain a tabular classifier through LORE\n",
    "\n",
    "LORE provides interpretable explanations for the decisions made by machine learning models, particularly in situations where it might be challenging to explain the model's behavior using traditional methods. LORE is designed to offer explanations on a per-instance basis, meaning it provides insights into why a specific prediction was made for a particular data point. This is in contrast to global explanations that aim to provide an overview of a model's behavior across the entire dataset.\n",
    "\n",
    "\n",
    "In this tutorial we will explain the reasoning of a random forest classifier when applied to an instance of the Adult Income dataset ( https://archive.ics.uci.edu/dataset/2/adult). This dataset contains census data from 1994 census database, the classification problem associated to such data involves the prediction of the annual income of a person, given a set of socio-economic caracteristics: \n",
    "- working class\n",
    "- marital status\n",
    "- occupation\n",
    "- relationship\n",
    "- race\n",
    "- sex\n",
    "- capital gain/loss\n",
    "- native country \n",
    "\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "67746cc7",
   "metadata": {},
   "source": [
    "### Dataset loading \n",
    "\n",
    "Lore libray has a module devoted to dataset handling. Here we use TabularDataset class to load a dataset from a csv file. A TabularDataset has a column that represent the target class (`class_name`) of the classification task  object, and has two main attributes: \n",
    "- `df` : a pandas dataframe representing the tabular data\n",
    "- `descriptor` : a dictionary containing internal data related to the dataset. It is build when a TabularDataset is created, but it could also be edited. It is used by the next steps of LORE methodology to distinguish among numerical, categorical, ordinal and target features of the dataset."
   ]
  },
  {
   "cell_type": "code",
   "id": "66c360ef",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T09:13:06.822427Z",
     "start_time": "2024-07-01T09:13:06.227080Z"
    }
   },
   "source": [
    "from lore_sa.dataset import TabularDataset\n",
    "import pandas as pd\n",
    "\n",
    "dataset = TabularDataset.from_csv('test/resources/adult.csv', class_name = \"class\")\n",
    "dataset.df.dropna(inplace = True)\n",
    "dataset.df\n"
   ],
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2024-07-01 11:13:06,391 numexpr.utils INFO     Note: NumExpr detected 36 cores but \"NUMEXPR_MAX_THREADS\" not set, so enforcing safe limit of 8.\n",
      "2024-07-01 11:13:06,392 numexpr.utils INFO     NumExpr defaulting to 8 threads.\n",
      "2024-07-01 11:13:06,778 root         INFO     test/resources/adult.csv file imported\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "       age         workclass  fnlwgt   education  education-num  \\\n",
       "0       39         State-gov   77516   Bachelors             13   \n",
       "1       50  Self-emp-not-inc   83311   Bachelors             13   \n",
       "2       38           Private  215646     HS-grad              9   \n",
       "3       53           Private  234721        11th              7   \n",
       "4       28           Private  338409   Bachelors             13   \n",
       "...    ...               ...     ...         ...            ...   \n",
       "32556   27           Private  257302  Assoc-acdm             12   \n",
       "32557   40           Private  154374     HS-grad              9   \n",
       "32558   58           Private  151910     HS-grad              9   \n",
       "32559   22           Private  201490     HS-grad              9   \n",
       "32560   52      Self-emp-inc  287927     HS-grad              9   \n",
       "\n",
       "           marital-status         occupation   relationship   race     sex  \\\n",
       "0           Never-married       Adm-clerical  Not-in-family  White    Male   \n",
       "1      Married-civ-spouse    Exec-managerial        Husband  White    Male   \n",
       "2                Divorced  Handlers-cleaners  Not-in-family  White    Male   \n",
       "3      Married-civ-spouse  Handlers-cleaners        Husband  Black    Male   \n",
       "4      Married-civ-spouse     Prof-specialty           Wife  Black  Female   \n",
       "...                   ...                ...            ...    ...     ...   \n",
       "32556  Married-civ-spouse       Tech-support           Wife  White  Female   \n",
       "32557  Married-civ-spouse  Machine-op-inspct        Husband  White    Male   \n",
       "32558             Widowed       Adm-clerical      Unmarried  White  Female   \n",
       "32559       Never-married       Adm-clerical      Own-child  White    Male   \n",
       "32560  Married-civ-spouse    Exec-managerial           Wife  White  Female   \n",
       "\n",
       "       capital-gain  capital-loss  hours-per-week native-country  class  \n",
       "0              2174             0              40  United-States  <=50K  \n",
       "1                 0             0              13  United-States  <=50K  \n",
       "2                 0             0              40  United-States  <=50K  \n",
       "3                 0             0              40  United-States  <=50K  \n",
       "4                 0             0              40           Cuba  <=50K  \n",
       "...             ...           ...             ...            ...    ...  \n",
       "32556             0             0              38  United-States  <=50K  \n",
       "32557             0             0              40  United-States   >50K  \n",
       "32558             0             0              40  United-States  <=50K  \n",
       "32559             0             0              20  United-States  <=50K  \n",
       "32560         15024             0              40  United-States   >50K  \n",
       "\n",
       "[30162 rows x 15 columns]"
      ],
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>age</th>\n",
       "      <th>workclass</th>\n",
       "      <th>fnlwgt</th>\n",
       "      <th>education</th>\n",
       "      <th>education-num</th>\n",
       "      <th>marital-status</th>\n",
       "      <th>occupation</th>\n",
       "      <th>relationship</th>\n",
       "      <th>race</th>\n",
       "      <th>sex</th>\n",
       "      <th>capital-gain</th>\n",
       "      <th>capital-loss</th>\n",
       "      <th>hours-per-week</th>\n",
       "      <th>native-country</th>\n",
       "      <th>class</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>39</td>\n",
       "      <td>State-gov</td>\n",
       "      <td>77516</td>\n",
       "      <td>Bachelors</td>\n",
       "      <td>13</td>\n",
       "      <td>Never-married</td>\n",
       "      <td>Adm-clerical</td>\n",
       "      <td>Not-in-family</td>\n",
       "      <td>White</td>\n",
       "      <td>Male</td>\n",
       "      <td>2174</td>\n",
       "      <td>0</td>\n",
       "      <td>40</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>50</td>\n",
       "      <td>Self-emp-not-inc</td>\n",
       "      <td>83311</td>\n",
       "      <td>Bachelors</td>\n",
       "      <td>13</td>\n",
       "      <td>Married-civ-spouse</td>\n",
       "      <td>Exec-managerial</td>\n",
       "      <td>Husband</td>\n",
       "      <td>White</td>\n",
       "      <td>Male</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>13</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>38</td>\n",
       "      <td>Private</td>\n",
       "      <td>215646</td>\n",
       "      <td>HS-grad</td>\n",
       "      <td>9</td>\n",
       "      <td>Divorced</td>\n",
       "      <td>Handlers-cleaners</td>\n",
       "      <td>Not-in-family</td>\n",
       "      <td>White</td>\n",
       "      <td>Male</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>40</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>53</td>\n",
       "      <td>Private</td>\n",
       "      <td>234721</td>\n",
       "      <td>11th</td>\n",
       "      <td>7</td>\n",
       "      <td>Married-civ-spouse</td>\n",
       "      <td>Handlers-cleaners</td>\n",
       "      <td>Husband</td>\n",
       "      <td>Black</td>\n",
       "      <td>Male</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>40</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>28</td>\n",
       "      <td>Private</td>\n",
       "      <td>338409</td>\n",
       "      <td>Bachelors</td>\n",
       "      <td>13</td>\n",
       "      <td>Married-civ-spouse</td>\n",
       "      <td>Prof-specialty</td>\n",
       "      <td>Wife</td>\n",
       "      <td>Black</td>\n",
       "      <td>Female</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>40</td>\n",
       "      <td>Cuba</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>...</th>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "      <td>...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32556</th>\n",
       "      <td>27</td>\n",
       "      <td>Private</td>\n",
       "      <td>257302</td>\n",
       "      <td>Assoc-acdm</td>\n",
       "      <td>12</td>\n",
       "      <td>Married-civ-spouse</td>\n",
       "      <td>Tech-support</td>\n",
       "      <td>Wife</td>\n",
       "      <td>White</td>\n",
       "      <td>Female</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>38</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32557</th>\n",
       "      <td>40</td>\n",
       "      <td>Private</td>\n",
       "      <td>154374</td>\n",
       "      <td>HS-grad</td>\n",
       "      <td>9</td>\n",
       "      <td>Married-civ-spouse</td>\n",
       "      <td>Machine-op-inspct</td>\n",
       "      <td>Husband</td>\n",
       "      <td>White</td>\n",
       "      <td>Male</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>40</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&gt;50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32558</th>\n",
       "      <td>58</td>\n",
       "      <td>Private</td>\n",
       "      <td>151910</td>\n",
       "      <td>HS-grad</td>\n",
       "      <td>9</td>\n",
       "      <td>Widowed</td>\n",
       "      <td>Adm-clerical</td>\n",
       "      <td>Unmarried</td>\n",
       "      <td>White</td>\n",
       "      <td>Female</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>40</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32559</th>\n",
       "      <td>22</td>\n",
       "      <td>Private</td>\n",
       "      <td>201490</td>\n",
       "      <td>HS-grad</td>\n",
       "      <td>9</td>\n",
       "      <td>Never-married</td>\n",
       "      <td>Adm-clerical</td>\n",
       "      <td>Own-child</td>\n",
       "      <td>White</td>\n",
       "      <td>Male</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>20</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&lt;=50K</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>32560</th>\n",
       "      <td>52</td>\n",
       "      <td>Self-emp-inc</td>\n",
       "      <td>287927</td>\n",
       "      <td>HS-grad</td>\n",
       "      <td>9</td>\n",
       "      <td>Married-civ-spouse</td>\n",
       "      <td>Exec-managerial</td>\n",
       "      <td>Wife</td>\n",
       "      <td>White</td>\n",
       "      <td>Female</td>\n",
       "      <td>15024</td>\n",
       "      <td>0</td>\n",
       "      <td>40</td>\n",
       "      <td>United-States</td>\n",
       "      <td>&gt;50K</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>30162 rows × 15 columns</p>\n",
       "</div>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 1
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "The `TabularDataset` class does some data inspection and preparation when it is created starting from a text-based file. Each attribute of the data is analysed to derive type and internal statistics. The `descriptor` field is automatically updates with these information. In particular, the `descriptor` is a dictionary that contains the following keys:\n",
    "- `numerical` : a dictionary containing the numerical features of the dataset and their statistics\n",
    "- `categorical` : a dictionary containing the categorical features of the dataset and their statistics\n",
    "- `ordinal` : (this is still not implemented) a dictionary containing the ordinal features of the dataset and their statistics\n",
    "- `target` : the details of the target feature of the dataset and its statistics  "
   ],
   "id": "21bea4759835d0e9"
  },
  {
   "cell_type": "code",
   "id": "504054e3",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T09:19:47.500531Z",
     "start_time": "2024-07-01T09:19:47.492422Z"
    }
   },
   "source": [
    "dataset.descriptor.keys()"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "dict_keys(['numeric', 'categorical', 'ordinal', 'target'])"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 2
  },
  {
   "cell_type": "markdown",
   "id": "cdd47bee",
   "metadata": {},
   "source": [
    "Before proceeding with the explanation, let's do some data preprocessing by dropping a few attributes that are not relevant for the learning. \n",
    "\n",
    "We operate directly on the `df` attribute of the dataset, then we update the descriptor.\n"
   ]
  },
  {
   "cell_type": "code",
   "id": "a974d87a",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T09:21:25.971357Z",
     "start_time": "2024-07-01T09:21:25.698303Z"
    }
   },
   "source": [
    "dataset.df.drop(['fnlwgt', 'education-num'], inplace=True, axis=1)\n",
    "dataset.update_descriptor()"
   ],
   "outputs": [],
   "execution_count": 3
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Model Learning\n",
    "\n",
    "We start by training a Random Forest classifier on the Adult dataset. We will use the `df` attribute of the dataset, which is a pandas dataframe containing the tabular data. We will use the `class_name` attribute of the dataset to identify the target feature of the classification task. Since the data contains non-numeric attributes, we proceed with a preprocessing of the data to mange these attributes. We will exploit `Pipeline` class from `sklearn` to create a pipeline that applies one-hot encoding to the categorical features and label encoding to the target feature. "
   ],
   "id": "c1904ce31a9bc2ca"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T09:33:08.224084Z",
     "start_time": "2024-07-01T09:33:08.209156Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from sklearn.pipeline import make_pipeline\n",
    "from sklearn.preprocessing import StandardScaler, OrdinalEncoder\n",
    "from sklearn.compose import ColumnTransformer\n",
    "from sklearn.ensemble import RandomForestClassifier\n",
    "from sklearn.model_selection import train_test_split\n",
    "from lore_sa.bbox import sklearn_classifier_bbox\n",
    "\n",
    "\n",
    "def train_model(dataset: TabularDataset):\n",
    "    preprocessor = ColumnTransformer(\n",
    "        transformers=[\n",
    "            ('num', StandardScaler(), [0,8,9,10]),\n",
    "            ('cat', OrdinalEncoder(), [1,2,3,4,5,6,7,11])\n",
    "        ]\n",
    "    )\n",
    "    model = make_pipeline(preprocessor, RandomForestClassifier(n_estimators=100, random_state=42))\n",
    "    \n",
    "    X_train, X_test, y_train, y_test = train_test_split(dataset.df.loc[:, 'age':'native-country'].values, dataset.df['class'].values,\n",
    "                test_size=0.3, random_state=42, stratify=dataset.df['class'].values)\n",
    "    model.fit(X_train, y_train)\n",
    "    \n",
    "    return sklearn_classifier_bbox.sklearnBBox(model)\n",
    "    "
   ],
   "id": "adb3009d21ac3996",
   "outputs": [],
   "execution_count": 12
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T09:33:09.806446Z",
     "start_time": "2024-07-01T09:33:08.432660Z"
    }
   },
   "cell_type": "code",
   "source": "bbox = train_model(dataset)",
   "id": "5249087cf760cf4f",
   "outputs": [],
   "execution_count": 13
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## Explanation\n",
    "\n",
    "Given the blackbox model, we can now explain the reasoning behind the classification of a specific instance. We will use the `LORE` class to explain the classification of the first instance of the dataset. The `explain_instance` method of the `LORE` class takes as input the instance to be explained, the blackbox model, and the dataset. It returns an explanation object that contains the explanation of the classification of the instance.\n",
    "\n",
    "The constructor of the explanator class takes as input the blackbox model and the dataset. The `dataset` instance is used to get the information from the descriptor. In case the trainin set is not available, the descriptor could be built from the test set or by the metadata of the dataset."
   ],
   "id": "491ffdf321054d5c"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T09:36:30.604558Z",
     "start_time": "2024-07-01T09:36:30.583912Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from lore_sa.lore import TabularRandomGeneratorLore\n",
    "\n",
    "tabularLore = TabularRandomGeneratorLore(bbox, dataset)"
   ],
   "id": "96805c27b65ef473",
   "outputs": [],
   "execution_count": 14
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T09:37:08.770330Z",
     "start_time": "2024-07-01T09:37:06.281941Z"
    }
   },
   "cell_type": "code",
   "source": [
    "num_row = 10\n",
    "x = dataset.df.iloc[num_row][:-1] # we exclude the target feature\n",
    "# when\n",
    "explanation = tabularLore.explain(x)\n",
    "# then\n",
    "print(explanation)"
   ],
   "id": "ee629c32bee32dcd",
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'x': age                               37\n",
      "workclass                    Private\n",
      "education               Some-college\n",
      "marital-status    Married-civ-spouse\n",
      "occupation           Exec-managerial\n",
      "relationship                 Husband\n",
      "race                           Black\n",
      "sex                             Male\n",
      "capital-gain                       0\n",
      "capital-loss                       0\n",
      "hours-per-week                    80\n",
      "native-country         United-States\n",
      "Name: 10, dtype: object, 'rule': <lore_sa.rule.Rule object at 0x752c8cb05670>, 'counterfactuals': [<lore_sa.rule.Rule object at 0x752c2d647f10>, <lore_sa.rule.Rule object at 0x752c2d611c10>, <lore_sa.rule.Rule object at 0x752c2f209dc0>, <lore_sa.rule.Rule object at 0x752c2d611190>, <lore_sa.rule.Rule object at 0x752c2d647d60>, <lore_sa.rule.Rule object at 0x752c2d647df0>, <lore_sa.rule.Rule object at 0x752c2d6478b0>, <lore_sa.rule.Rule object at 0x752c2d647820>, <lore_sa.rule.Rule object at 0x752c2d6472e0>, <lore_sa.rule.Rule object at 0x752c2d642700>, <lore_sa.rule.Rule object at 0x752c2d642910>, <lore_sa.rule.Rule object at 0x752c2d642670>], 'deltas': [[<lore_sa.rule.Expression object at 0x752c2d647400>], [<lore_sa.rule.Expression object at 0x752c2d611c40>], [<lore_sa.rule.Expression object at 0x752c2d611c70>], [<lore_sa.rule.Expression object at 0x752c2d611a90>], [<lore_sa.rule.Expression object at 0x752c2d647490>], [<lore_sa.rule.Expression object at 0x752c2d647a60>], [<lore_sa.rule.Expression object at 0x752c2d647280>], [<lore_sa.rule.Expression object at 0x752c2d647700>], [<lore_sa.rule.Expression object at 0x752c2d6478e0>], [<lore_sa.rule.Expression object at 0x752c2d642a00>], [<lore_sa.rule.Expression object at 0x752c2d6426a0>], [<lore_sa.rule.Expression object at 0x752c2d642cd0>]]}\n"
     ]
    }
   ],
   "execution_count": 15
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Drill down the explanation process\n",
    "\n",
    "The example above shows the explanation of the classification of one of the instances of the dataset. The `TabularRandomGenerator` encapsulates many of the deatils of the explanation process. The class construct and explanation pipeline that is composed by the following steps:\n",
    "- **Neighborhood generation**: the neighborhood of the instance to be explained is generated. The neighborhood is a synthetic dataset that is created by generating random instances around the instance to be explained. The neighborhood is used to understand the behavior of the blackbox model in the vicinity of the instance to be explained.\n",
    "- ** Encoding**: the neighborhood dataset is encoded using one-hot encoding. The encoded neighborhood dataset is used to train the surrogate model.\n",
    "- **Surrogate model**: a surrogate model is trained on the neighborhood dataset. The surrogate model is a simpler model that approximates the behavior of the blackbox model in the neighborhood of the instance to be explained. The surrogate model is used to extract classification rules that explain the behavior of the blackbox model.\n",
    "- **Rule extraction**: the classification rules are extracted from the surrogate model. The classification rules are used to explain the classification of the instance to be explained. The classification rules provide insights into the features that are important for the classification of the instance.\n",
    "\n",
    "Each of these step can be customized separately, in order to adapt the explanation process to the specific needs of the user. For example, let's construct an explanation process by managing manually the choice of each component of the explanation pipeline.\n",
    "\n",
    "#### Encoding / Decoding\n",
    "\n",
    "We use a `ColumnTransformerEnc` to exploit the `TransformerMixin` interface of the `sklearn` transformers. The `ColumnTransformerEnc` class is a wrapper around the `ColumnTransformer` class that provides the `encode` and `decode` methods to encode and decode the dataset. The `encode` method applies the transformations of the transformers to the dataset, while the `decode` method applies the inverse transformations to the dataset. The `ColumnTransformerEnc` class is used to encode and decode the dataset in the explanation process. "
   ],
   "id": "13dad302bc281573"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T09:48:07.642149Z",
     "start_time": "2024-07-01T09:48:07.621250Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from lore_sa.encoder_decoder import ColumnTransformerEnc\n",
    "\n",
    "tabular_enc = ColumnTransformerEnc(dataset.descriptor)\n",
    "ref_value = dataset.df.iloc[0].values[:-1]\n",
    "encoded = tabular_enc.encode([ref_value])\n",
    "decoded = tabular_enc.decode(encoded)\n",
    "\n",
    "print(f\"Original value: {ref_value}\")\n",
    "print(f\"Encoded value: {encoded}\")\n",
    "print(f\"Decoded value: {decoded}\")"
   ],
   "id": "324b79c41abee753",
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Original value: [39 'State-gov' 'Bachelors' 'Never-married' 'Adm-clerical' 'Not-in-family'\n",
      " 'White' 'Male' 2174 0 40 'United-States']\n",
      "Encoded value: [[39 2174 0 40 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 1 0\n",
      "  0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 1 0 1 0 0 0 0 0 0 0 0\n",
      "  0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0]]\n",
      "Decoded value: [[39 'State-gov' 'Bachelors' 'Never-married' 'Adm-clerical'\n",
      "  'Not-in-family' 'White' 'Male' 2174 0 40 'United-States']]\n"
     ]
    }
   ],
   "execution_count": 16
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "#### Neighborhood generation\n",
    "Now that we are able to encode and decode the dataset, we can generate the neighborhood of the instance to be explained. To personalize the neighborhood generation process, we create now a Genetic Generator, using the class `GeneticGenerator`. The neighborhood is a synthetic dataset that is created by generating random instances around the instance to be explained, refined with a genetic algorithm to obtain a more dense and compact neighborhood."
   ],
   "id": "6da4e1a37110d163"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T09:59:24.680102Z",
     "start_time": "2024-07-01T09:59:24.390393Z"
    }
   },
   "cell_type": "code",
   "source": [
    "from lore_sa.neighgen import RandomGenerator\n",
    "\n",
    "num_row = 10\n",
    "x = dataset.df.iloc[num_row][:-1]\n",
    "z = tabular_enc.encode([x.values])[0] # remove the class feature from the input instance\n",
    "\n",
    "gen = RandomGenerator(bbox=bbox, dataset=dataset, encoder=tabular_enc, ocr=0.1)\n",
    "neighbour = gen.generate(z, 100, dataset.descriptor, tabular_enc)\n",
    "\n",
    "print('Neighborhood', neighbour)"
   ],
   "id": "cf3d676c4377406f",
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Neighborhood [[28.016444366192374 62820.53236135742 4007.9233443601856 ... 0 0 0]\n",
      " [73.12999435602602 53402.49655114709 774.6525771607363 ... 0 0 0]\n",
      " [82.95026755277675 51612.96907032331 2208.3959787663866 ... 0 0 0]\n",
      " ...\n",
      " [30.21970153755531 43842.72818354014 469.4905352571088 ... 0 1 0]\n",
      " [30.21970153755531 43842.72818354014 469.4905352571088 ... 0 1 0]\n",
      " [30.21970153755531 43842.72818354014 469.4905352571088 ... 0 1 0]]\n"
     ]
    }
   ],
   "execution_count": 19
  },
  {
   "cell_type": "markdown",
   "id": "161ebd01",
   "metadata": {},
   "source": ""
  },
  {
   "cell_type": "markdown",
   "id": "ba809d76",
   "metadata": {},
   "source": [
    "## surrogate model\n",
    "\n",
    "The `surrogate` submodule creates a classifier and provides the methods to extract its corresponding classification rules. Once trained the surrogate, we extract a set of rules that explains why the surrogate model classifies the instance in a certain way. \n",
    "\n",
    "In the following example, the instance `x` has been classified as an adult with income less than 50k. The surrogate model has used the features `capital-gain`, `capital-loss`, `marital-status`, and `native-country`. "
   ]
  },
  {
   "cell_type": "code",
   "id": "a6a759df",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T10:01:00.016752Z",
     "start_time": "2024-07-01T10:00:59.991210Z"
    }
   },
   "source": [
    "from lore_sa.surrogate import DecisionTreeSurrogate\n",
    "# decode the neighborhood to be labeled by the blackbox model\n",
    "neighb_train_X = tabular_enc.decode(neighbour)\n",
    "neighb_train_y = bbox.predict(neighb_train_X)\n",
    "# encode the target class to the surrogate model\n",
    "neighb_train_yz = tabular_enc.encode_target_class(neighb_train_y.reshape(-1, 1)).squeeze()\n",
    "\n",
    "dt = DecisionTreeSurrogate()\n",
    "dt.train(neighbour, neighb_train_yz)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "DecisionTreeClassifier()"
      ],
      "text/html": [
       "<style>#sk-container-id-1 {color: black;}#sk-container-id-1 pre{padding: 0;}#sk-container-id-1 div.sk-toggleable {background-color: white;}#sk-container-id-1 label.sk-toggleable__label {cursor: pointer;display: block;width: 100%;margin-bottom: 0;padding: 0.3em;box-sizing: border-box;text-align: center;}#sk-container-id-1 label.sk-toggleable__label-arrow:before {content: \"▸\";float: left;margin-right: 0.25em;color: #696969;}#sk-container-id-1 label.sk-toggleable__label-arrow:hover:before {color: black;}#sk-container-id-1 div.sk-estimator:hover label.sk-toggleable__label-arrow:before {color: black;}#sk-container-id-1 div.sk-toggleable__content {max-height: 0;max-width: 0;overflow: hidden;text-align: left;background-color: #f0f8ff;}#sk-container-id-1 div.sk-toggleable__content pre {margin: 0.2em;color: black;border-radius: 0.25em;background-color: #f0f8ff;}#sk-container-id-1 input.sk-toggleable__control:checked~div.sk-toggleable__content {max-height: 200px;max-width: 100%;overflow: auto;}#sk-container-id-1 input.sk-toggleable__control:checked~label.sk-toggleable__label-arrow:before {content: \"▾\";}#sk-container-id-1 div.sk-estimator input.sk-toggleable__control:checked~label.sk-toggleable__label {background-color: #d4ebff;}#sk-container-id-1 div.sk-label input.sk-toggleable__control:checked~label.sk-toggleable__label {background-color: #d4ebff;}#sk-container-id-1 input.sk-hidden--visually {border: 0;clip: rect(1px 1px 1px 1px);clip: rect(1px, 1px, 1px, 1px);height: 1px;margin: -1px;overflow: hidden;padding: 0;position: absolute;width: 1px;}#sk-container-id-1 div.sk-estimator {font-family: monospace;background-color: #f0f8ff;border: 1px dotted black;border-radius: 0.25em;box-sizing: border-box;margin-bottom: 0.5em;}#sk-container-id-1 div.sk-estimator:hover {background-color: #d4ebff;}#sk-container-id-1 div.sk-parallel-item::after {content: \"\";width: 100%;border-bottom: 1px solid gray;flex-grow: 1;}#sk-container-id-1 div.sk-label:hover label.sk-toggleable__label {background-color: #d4ebff;}#sk-container-id-1 div.sk-serial::before {content: \"\";position: absolute;border-left: 1px solid gray;box-sizing: border-box;top: 0;bottom: 0;left: 50%;z-index: 0;}#sk-container-id-1 div.sk-serial {display: flex;flex-direction: column;align-items: center;background-color: white;padding-right: 0.2em;padding-left: 0.2em;position: relative;}#sk-container-id-1 div.sk-item {position: relative;z-index: 1;}#sk-container-id-1 div.sk-parallel {display: flex;align-items: stretch;justify-content: center;background-color: white;position: relative;}#sk-container-id-1 div.sk-item::before, #sk-container-id-1 div.sk-parallel-item::before {content: \"\";position: absolute;border-left: 1px solid gray;box-sizing: border-box;top: 0;bottom: 0;left: 50%;z-index: -1;}#sk-container-id-1 div.sk-parallel-item {display: flex;flex-direction: column;z-index: 1;position: relative;background-color: white;}#sk-container-id-1 div.sk-parallel-item:first-child::after {align-self: flex-end;width: 50%;}#sk-container-id-1 div.sk-parallel-item:last-child::after {align-self: flex-start;width: 50%;}#sk-container-id-1 div.sk-parallel-item:only-child::after {width: 0;}#sk-container-id-1 div.sk-dashed-wrapped {border: 1px dashed gray;margin: 0 0.4em 0.5em 0.4em;box-sizing: border-box;padding-bottom: 0.4em;background-color: white;}#sk-container-id-1 div.sk-label label {font-family: monospace;font-weight: bold;display: inline-block;line-height: 1.2em;}#sk-container-id-1 div.sk-label-container {text-align: center;}#sk-container-id-1 div.sk-container {/* jupyter's `normalize.less` sets `[hidden] { display: none; }` but bootstrap.min.css set `[hidden] { display: none !important; }` so we also need the `!important` here to be able to override the default hidden behavior on the sphinx rendered scikit-learn.org. See: https://github.com/scikit-learn/scikit-learn/issues/21755 */display: inline-block !important;position: relative;}#sk-container-id-1 div.sk-text-repr-fallback {display: none;}</style><div id=\"sk-container-id-1\" class=\"sk-top-container\"><div class=\"sk-text-repr-fallback\"><pre>DecisionTreeClassifier()</pre><b>In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook. <br />On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.</b></div><div class=\"sk-container\" hidden><div class=\"sk-item\"><div class=\"sk-estimator sk-toggleable\"><input class=\"sk-toggleable__control sk-hidden--visually\" id=\"sk-estimator-id-1\" type=\"checkbox\" checked><label for=\"sk-estimator-id-1\" class=\"sk-toggleable__label sk-toggleable__label-arrow\">DecisionTreeClassifier</label><div class=\"sk-toggleable__content\"><pre>DecisionTreeClassifier()</pre></div></div></div></div></div>"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 20
  },
  {
   "cell_type": "code",
   "id": "8b04bfca",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-07-01T10:04:11.923034Z",
     "start_time": "2024-07-01T10:04:11.829006Z"
    }
   },
   "source": [
    "num_row = 10\n",
    "x = dataset.df.iloc[num_row][:-1] # remove the class feature from the input instance\n",
    "z = tabular_enc.encode([x.values])[0]\n",
    "rule = dt.get_rule(z, tabular_enc)\n",
    "print('rule', rule)\n",
    "crules, deltas = dt.get_counterfactual_rules(z, neighbour, neighb_train_yz, tabular_enc)\n",
    "print('\\n crules')\n",
    "for c in crules:\n",
    "    print(c)\n"
   ],
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "rule premises:\n",
      "capital-gain <= 9314.40087890625\n",
      "race != Other \n",
      "consequence: class = <=50K\n",
      "\n",
      " crules\n",
      "premises:\n",
      "capital-gain <= 9314.40087890625\n",
      "race = Other\n",
      "relationship != Other-relative \n",
      "consequence: class = >50K\n"
     ]
    }
   ],
   "execution_count": 23
  }
 ],
 "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}