{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Preferences"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The PyXAI library offers the possibility to handle user preferences. Two kinds of preferences are supported:\n\n- The user may prefer some explanations to others.\n- The user may exclude some features from explanations.\n\nMore information about preferences can be found in the paper [On Preferred Abductive Explanations for Decision Trees and Random Forests](https://www.ijcai.org/proceedings/2022/0091.pdf).\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preferred reasons"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case, the user has to provide a weight for each feature, representing its disutility (or cost). The PyXAI library offers different options:\n\n- ```PreferredReasonMethod.SHAPLEY```: Only available with Scikit-learn. It uses Shapley values to discriminate 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 feature importance of features to discriminate them. See this [paper](https://www.jmlr.org/papers/volume12/pedregosa11a/pedregosa11a.pdf) for more information.\n- ```PreferredReasonMethod.WORD_FREQUENCY```: It uses the [wordfreq](https://pypi.org/project/wordfreq/) package to discriminate features. The more frequent a word in a feature name, the more likely it is to be understood by users.\n- ```PreferredReasonMethod.WEIGHTS```: The user defines the weights to be used.\n- ```PreferredReasonMethod.INCLUSION_PREFERRED```: The user defines a partition over all features (a list of lists). The first elements of the partition are preferred to the second ones, which are preferred to the third ones, and so on.\n\nThe following methods accept a ```method``` parameter of type ```PreferredReasonMethod```:\n\n| Method | Model |\n|:-------|:------|\n| ```preferred_sufficient_reason``` | Decision Tree |\n| ```preferred_majoritary_reason``` | Random Forest |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Excluded features"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Excluding some features from explanations can be achieved using ```set_excluded_features```. The function ```unset_excluded_features``` restores the initial state where no features are excluded.\n\nThe following methods respect excluded features:\n\n| Method | DT | RF | BT |\n|:-------|:--:|:--:|:--:|\n| ```direct_reason``` | ✓ | ✓ | ✓ |\n| ```sufficient_reason``` | ✓ | ✓ | |\n| ```minimal_sufficient_reason``` | ✓ | ✓ | |\n| ```preferred_sufficient_reason``` | ✓ | | |\n| ```contrastive_reason``` | ✓ | | |\n| ```majoritary_reason``` | | ✓ | |\n| ```preferred_majoritary_reason``` | | ✓ | |\n| ```minimal_majoritary_reason``` | | ✓ | |\n| ```minimal_contrastive_reason``` | | ✓ | ✓ |\n| ```tree_specific_reason``` | | | ✓ |\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "{: .warning}\n> It may happen that excluded features prevent an explanation from being computed. In that case, the method returns ```[]```.\n"
   ]
  }
 ],
 "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
}