{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "a2dae705",
   "metadata": {},
   "source": [
    "# Preferences"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "074d7c80",
   "metadata": {},
   "source": [
    "The PyXAI library offers the possibility to process user preferences. Different kinds of preferences are handled:\n",
    "\n",
    "- The user may prefer some explanations to others.\n",
    "- The user may exclude some features from explanations.\n",
    "\n",
    "More information about preferences can be found in the\n",
    "paper [On Preferred Abductive Explanations for Decision Trees and Random Forests](https://www.ijcai.org/proceedings/2022/0091.pdf)\n",
    "."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff28d12a",
   "metadata": {},
   "source": [
    "## Preferred reasons"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "65bf8db2",
   "metadata": {},
   "source": [
    "In this case, the user has to provide a weight for each feature, representing its disutility (or cost).\n",
    "The PyXAI library offers different options:\n",
    "\n",
    "- ```PreferredReasonMethod.SHAPLEY```: Only available with Scikit-learn. It uses Shapley values to discriminate\n",
    "  features. See this [paper](https://arxiv.org/abs/1705.07874)  for more information.\n",
    "- ```PreferredReasonMethod.FEATURE_IMPORTANCE```: Only available with Scikit-learn. It uses the f-importance of features\n",
    "  to discriminate them. See this [paper](https://www.jmlr.org/papers/volume12/pedregosa11a/pedregosa11a.pdf) for more\n",
    "  information.\n",
    "- ```PreferredReasonMethod.WORD_FREQUENCY```: It uses the [wordfreq](https://pypi.org/project/wordfreq/) package to\n",
    "  discriminate features. The more frequent is a word in a feature name, the more likely it is to be understood by users.\n",
    "- ```PreferredReasonMethod.WEIGHTS```: The user defines the the weights to be used.\n",
    "- ```PreferredReasonMethod.INCLUSION_PREFERRED```: The user has to define a partition over all features\n",
    "- (a list of list). The first elements of the partition are preferred to the second ones which are preferred to the\n",
    "  third ones and so on."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f8e8d4ff",
   "metadata": {},
   "source": [
    "## Excluded features"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fb38c582",
   "metadata": {},
   "source": [
    "Eecluding some features from explanations can be achieved using the function ```set_excluded_features```. The\n",
    "function ```unset_excluded_features``` allows to restore the initial state (where default there is no\n",
    "excluded features)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d20574a2",
   "metadata": {},
   "source": [
    "| <font style=\"font-family:Consolas,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New;\" size=\"+1pt\">&lt;Explainer Object&gt;.set_excluded_features(self, excluded):</font> |\n",
    "|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n",
    "| Sets the features that the user does not want to see in explanations. You must give the name of the features.                                                                                                        |                                                                                                                                                                                                             |\n",
    "| <b><font style=\"font-family:Consolas,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New;\">excluded</font></b> ```List``` ```Tuple```: A list of feature names.       "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "539f2053",
   "metadata": {},
   "source": [
    "{: .warning}\n",
    "It may happen that excluded features prevent from computing explanations. In this case, the method that computes the explanation\n",
    "will return ```[]```."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40dbd194",
   "metadata": {},
   "source": [
    "| <font style=\"font-family:Consolas,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New;\" size=\"+1pt\">&lt;Explainer Object&gt;.unset_excluded_features(self):</font> |\n",
    "|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n",
    "| Unset the features set with the ```set_excluded_features``` method.|       "
   ]
  }
 ],
 "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.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}