{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Black-box Vector Optimization on Fairness\n",
    "This notebook contains a vector optimization example on an ML fairness dataset, and compares Naive Elimination and PaVeBa algorithms."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "warnings.filterwarnings(\"ignore\")\n",
    "\n",
    "import vopy.algorithms\n",
    "from vopy.utils import set_seed\n",
    "from vopy.order import ConeTheta2DOrder\n",
    "from vopy.datasets import get_dataset_instance\n",
    "from vopy.utils.evaluate import calculate_epsilonF1_score"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's first create an `Order` object to define our preference and visualize it's cone. Our preference correspond to allowing a little trade-off between objectives."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 600x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "order = ConeTheta2DOrder(cone_degree=100)\n",
    "fig_cone = order.ordering_cone.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we will create an instance of ML fairness dataset and visualize its Pareto front w.r.t. the order we created. This dataset contains different (200 candidates) hyperparameter selections of ROAD approach on a neural network architecture. The objectives are negative global unfairness measured by disparate impact measure and accuracy of the model. The $x$-axis corresponds to the negative global unfairness and $y$-axis corresponds to the accuracy of the model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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O9eed/z4cTzxxBO45557AAB/+7d/ix/+8If49re/jYceeqjufScialf7YhGM3hFmcjiVpamFU3zKQnzaRCQqFt0KGo6IiE+ZiE9Z6B+U6tKGZ555BuFwGIZhQNd1fOxjH8Njjz2GN954A3/yJ3+Cf/7nf8bCwgIsywIAjI+P4+DBg2vPP3To0NqfT58+jVwut1ZIrdI0De973/tKtmFsbAy6ruPw4cNrf6coCm655RacOXPGqa4SEVEJoihgqJtBzrS9phZO2YwF0wDkEsHTigqkk4WfA+pTON155504fvw4FEXBzp07oSgK0uk0jh49iqNHj+I73/kO+vr6MD4+jmPHjkHTtA3PD4VCa39eLa5+8IMfYHBwcMPP+Xy+km2w7UK42ubi0bZtBk0SERG5SFMLp0BQhCQDhl64PLeZrgGSXPi5egmFQti3b9+Gvzt79izm5ubw6KOPYmhoCADw2muvbftaBw8ehM/nw/j4OI4cOVL0Z9Z/Vcmqffv2QVVVvPjii7j33nsBFL7K5rXXXsPnP//5arpFREREddDUwik2ICLWL2HyXRPdveJVW0FTSQs7hyTEBhp7D/vw8DBUVcVjjz2GBx54AKdOncLDDz+87fMikQgefPBBfOELX4BlWbj99tuRSCTw8ssvIxwO47777sPu3bshCAKeeeYZfPSjH0UgEEA4HMbnPvc5PPTQQ+ju7sbw8DC++tWvIpPJ4DOf+UwDekxERETlaOquOlEUcOsdfgQCAhbmLORzNizLRj5nY2HOQiAg4NYj/obfoNfX14cnnngC//AP/4CDBw/i0UcfxZ//+Z+X9dyHH34YX/rSl/DII4/gPe95D44dO4bvf//72LNnDwBgcHAQX/7yl/GHf/iH2LFjB373d38XAPDoo4/i4x//OD75yU/i5ptvxoULF3DixAl0dXXVrZ9ERERUGcFevcGmSrlcDhcvXsSePXvg9/ureo3xMQOvnMwhPm3CNAqX52IDEm494sfwXgZKupET805USiKRQDQaxfLyMjo6OprdHCKiNa6oSob3yti1J9SU5HAiIiKicrmicAIKl+0KkQP12T1HREREVKumJ4cTEREReQULJyIiIqIysXAiIiIiKhMLJyIiIqIysXAiIiIiKhMLJyIiIqIysXAiIiIiKhMLJyIiIqIytW3hdP/990MQBDz66KMb/v7pp5/e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",
      "text/plain": [
       "<Figure size 600x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "dataset_name = \"Fairness\"\n",
    "dataset = get_dataset_instance(dataset_name)\n",
    "fig_pareto = order.plot_pareto_set(dataset.out_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, there are a lot of hyperparameter combinations that give $0$ unfairness (right end of the plot), but due to our encoded preference, only the one with the highest accuracy is among the Pareto front. There are $3$ candidates that are Pareto."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Algorithms\n",
    "We'll now run both algorithms (Naive Elimination and PaVeBa) and print out their results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "NaiveElimination - epsilon-F1 Score: 1.00\n",
      "NaiveElimination - Number of observations: 1000\n",
      "PaVeBa - epsilon-F1 Score: 1.00\n",
      "PaVeBa - Number of observations: 235\n"
     ]
    }
   ],
   "source": [
    "epsilon = 0.01\n",
    "delta = 0.05\n",
    "noise_var = epsilon\n",
    "\n",
    "alg_names = [\"NaiveElimination\", \"PaVeBa\"]\n",
    "alg_params = {\n",
    "    \"NaiveElimination\": {\"L\": 5},\n",
    "    \"PaVeBa\": {\"conf_contraction\": 8}\n",
    "}\n",
    "\n",
    "for alg_name in alg_names:\n",
    "    set_seed(0)\n",
    "\n",
    "    algorithm = getattr(vopy.algorithms, alg_name)(\n",
    "        epsilon=epsilon, delta=delta,\n",
    "        dataset_name=dataset_name, order=order, noise_var=noise_var, **alg_params[alg_name]\n",
    "    )\n",
    "\n",
    "    while True:\n",
    "        is_done = algorithm.run_one_step()\n",
    "\n",
    "        if is_done:\n",
    "            break\n",
    "\n",
    "    pred_pareto_indices = sorted(list(algorithm.P))\n",
    "    pareto_indices = order.get_pareto_set(dataset.out_data)\n",
    "\n",
    "    eps_f1 = calculate_epsilonF1_score(\n",
    "        dataset, order, pareto_indices, pred_pareto_indices, epsilon\n",
    "    )\n",
    "    print(f\"{alg_name} - epsilon-F1 Score: {eps_f1:.2f}\")\n",
    "    print(f\"{alg_name} - Number of observations: {algorithm.sample_count}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The results show both Naive Elimination and PaVeBa achieve perfect results but with different number of samples. This is expected due to the nature of the algorithms. For details of the algorithms, see documentation for [vopy.algorithms](../algorithms.rst)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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": 2
}