examples/demo_ot_metric.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Measuring bias with Optimal Transport by calculating the Wasserstein distance"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Table of contents\n",
    "\n",
    "- Introduction\n",
    "- General Optimal Transport examples\n",
    "- Usage\n",
    "- Application to Compas Dataset\n",
    "- Application to Adult Dataset\n",
    "- More details\n",
    "   - OT for mapping estimation\n",
    "   - Kantorovich optimal transport problem\n",
    "   - Solving optimal transport\n",
    "   - Necessity and priority of usage"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "\"FlipTest: fairness testing via optimal transport\" https://dl.acm.org/doi/abs/10.1145/3351095.3372845\n",
    "\n",
    "\"Obtaining Fairness using Optimal Transport Theory\" http://proceedings.mlr.press/v97/gordaliza19a.html\n",
    "\n",
    "\"Computational Optimal Transport\" https://arxiv.org/abs/1803.00567\n",
    "\n",
    "\"POT: Python Optimal Transport\" https://jmlr.org/papers/v22/20-451.html"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "\n",
    "Optimal Transport (OT) is a field of mathematics which studies the geometry of probability spaces. Among its many contributions, OT provides a principled way to compare and align probability distributions by taking into account the underlying geometry of the\n",
    "considered metric space.\n",
    "\n",
    "Optimal Transport (OT) is a mathematical problem that was first introduced by Gaspard Monge in 1781. It addresses the task of determining the most efficient method for transporting mass from one distribution to another. In this problem, the cost associated with moving a unit of mass from one position to another is referred to as the ground cost. The primary objective of OT is to minimize the total cost incurred when moving one mass distribution onto another. The optimization problem can be expressed for two distributions $\\mu_s$ and $\\mu_t$ as\n",
    "\n",
    "$$\n",
    "\\min_{m, m_{\\#} \\mu_s=\\mu_t} \\int c(x, m(x)) d \\mu_s(x)\n",
    "$$\n",
    "in the continuous case, and\n",
    "$$\n",
    "\\min_{\\sigma \\in \\text{Perm}(n)} \\frac{1}{n} \\sum_{i=1}^n \\textbf{C}_{i,\\sigma(i)}\n",
    "$$\n",
    "in the discrete case, where $\\textbf{C}_{\\cdot, \\cdot}$ is the ground cost and the constraint $m_{\\#} \\mu_s=\\mu_t$ ensures that $\\mu_s$ is completely transported to $\\mu_t$. Where $T_{\\#} \\mu_s = \\mu_s(T^{-1}(B)) = u_{t}(B)$ with $T$ as a trasportation matrix between $\\mu_s$ and $\\mu_t$ at point $B$. "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "OT can be used to detect **model-induced bias** by calculating the above cost (also known as **Earth Mover's distance** or **Wasserstein distance**) between the distribution of ground truth labels and model predictions for each of the **protected groups**. If its value is close to 1, the model is **biased** towards this group."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## General Optimal Transport examples"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us start with some simple examples of calculating the Earth Mover's distance between two distributions - the basis of Optimal Transport for bias detection. We do this using the `earth_movers_distance` function.\n",
    "\n",
    "For concrete examples of bias detection on real datasets, skip to the next chapter."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1. General Optimal Transport\n",
    "\n",
    "Suppose we have two distributions $a$ and $b$ (as shown in the picture below), and we need to calculate the Wasserstein distance between these two distributions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "# Initial distribution\n",
    "a = np.array([0.,         0.01547988, 0.03095975, 0.04643963,  0.05727554, 0.05417957, 0.04643963, 0.07739938,  \n",
    "              0.10835913, 0.12383901, 0.11764706, 0.10526316, 0.09287926, 0.07739938, 0.04643962, 0.        ])\n",
    "# Required distribution\n",
    "b = np.array([0.,         0.01829787, 0.02702128, 0.04106383,  0.07,       0.10829787, 0.14212766, 0.14468085, \n",
    "              0.13,       0.10808511, 0.08255319, 0.05170213,  0.03361702, 0.02702128, 0.01553191, 0.        ])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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jkbhwoUNm82W+H4knO+jjz5KlulOq/Xt2LHDaN26tZE/f36jQIECRteuXY0zZ84kOT4qKsp47bXXDE9PTyNPnjxG/fr1jd27dydbWSe17/21a9eM119/3fDy8jIcHR2N4sWLGy+88ILx77//Jmnn5eVltGzZMtnruvU9FRERkTtL6borwbVr14zSpUsb5cuXN2JjYw3DMIw9e/YYnTp1Mh544AHD0dHR8PDwMJ544glj6tSpSY795ZdfjFq1ahnOzs6Gh4eH8eqrrxpffPFFspXg7vWa4nar9aV0fWgYhhETE2OMHz8+8Zouf/78RqVKlYx+/foZhw4dSvL8r7zyivHAAw8YLi4uRq1atYzg4OAUr2lScuLECaNDhw6J100dOnQwtm7detfV+oKDg4127doZXl5ehrOzs+Hq6mrUr1/fWL58eZLzr1+/3qhevbrh7OycZAXBhPOdO3cuWabbrdbXsmVLY9GiRcbDDz9sODk5Gd7e3saECROSHX/w4EEjICDAKFiwoFGsWDHjpZdeMlauXJns/b/dNahhpHw9/ueffxqtW7c2ChUqZDg5ORm+vr5J3iPD+O/f+dtvv02yP6VrV5GcwGYYhpF5pTAREREREZHcbfbs2fTu3ZujR4+mufePiEhOojmnRERERERERETEMipOiYiIiIiIiIiIZTSsT0RERERERERELKOeUyIiIiIiIiIiYhkVp0RERERERERExDIqTomIiIiIiIiIiGUcrA6QXuLj4zl16hQFChTAZrNZHUdERETSmWEYXLlyhRIlSmBnp8/Xshtdq4mIiOR8ab1eyzHFqVOnTuHp6Wl1DBEREclgoaGhlCpVyuoYkkq6VhMREck9Unu9lmOKUwUKFADMN6BgwYIWpxEREZH0dvnyZTw9PRP/z5fsRddqIiIiOV9ar9dyTHEqoXt4wYIFdcEjIiKSg2lIWPakazUREZHcI7XXa5qwQURERERERERELKPilIiIiIiIiIiIWEbFKRERERERERERsYyKUyIiIiIiIiIiYhkVp0RERERERERExDIqTomIiIiIiIiIiGVUnBIREREREREREcuoOCUiIiIiIiIiIpZxsDqAiEiOFx8H57bAtdOQpzgU8wc7e6tTiYiIiIiIZAkqTomIZKTQJbBjEESe+G9f3lLgNxE821uXS0REREREJIvQsD4RkYwSugS2dExamAKIPGnuD11iTS4REREREZEsRD2nREQyQnyc2WMKI8nuqBgn9p+qxNnL7kT9/T2FAp6kVGl7vL3BZrMkqYiIiORwly7B0aNw+jQYBuTJA15eULo0OOgvQhHJAvSrSETkPoSEhBAeHp5sf/6r26lwo8dU+BVX5m3tyvzgLmw/WoPoWOf/Go650T5/LH5+EdSvf4knnviXAgXicXNzo3Tp0pnxMkRERCSHOXQIZs2CVavgjz/MotSt8uaF2rWhWTPo1MksVomIWMFmGCn9msp+Ll++TKFChbh06RIFCxa0Oo6I5AIhISFU8qnEtchryR7rUhsm9SrCuBWv8cmal7kWnTfxsSL5LlCiyCnyOF3jwKlCXLnuBdxUsCIC+Apnl4kcPLBOBSqRG/R/ffamfz+RzLFvH7zxBixblnT/Aw9AiRJmT6krV+DYMYiKStqmRQt49VWoX/+mHt1a2EVEUiGt/9+r55SISBqFh4dzLfIa3T/vjnsF9ySPXdnggc+rPTh72dxfzWsXvevNotUjKyhT7GjiBd8U104ctPMm/KgHR371Yf+G6lw47g4MIOp6H4YPv8TUqaC/40REROROYmLgnXdg7FiIjzeLS02bQo8e0LAhFC+etH18vFnI2rABFi+Gn34ye1mtWgWPPgrjxkH9slrYRUQyh4pTIiL3yb2CO56+ngDERtmz+PX6BH9VBQCfEnv5sOvrtKq+IsmcUgYQ4VKYmJq18LbZ4V0Dajx1AMM4wD8/l+L7d6oQsrMC8+Y9wObN8Nln0K6dBS9OREREsrwTJ8zrhO3bza+ffNIsUvn43P4YOzt4+GHz9tJLcPgwTJgAM2fC779Dgwbw1GOxfNTVDq9iNx2YsLCL/yIVqEQk3Wi1PhGRdBIRnofP2rQn+Ksq2GwGTz23gp1jqtPqkeSFKYDNPu0wbEl/DdtsUN7/BE/97wugCZ6e1zl1Ctq3h65d4fLlTHs5IiIikg388QfUqmUWpooUgYULzSF9dypMpaRcOZg0CY4fhxf6x2NnF8e3v3Xi4df/5osNz900Z9WNjR2DzSF/IiLpQD2nRETSwcWT+Zncvh1nDxUlT6Hr9Jy2Gp/Gx1kf9jT19y2lwPWLiW0jXAqz2acdhz1873LW9cyfv49Vq6rzwQcwf7554blwIVSvnqEvR0RERLKB3bvNIXsXL5rFqFWrwNv73o693aIuAIO7bae/12cMnD2Jnw/402/GFyzZ1p6Zzz9LiSKnAQMiQzn4ywwi8tVIdrwWdRGR1FJxSkTkPl05V5DZvTpy/nghCpe4wgtLluJe4V8ADnv4csS9CiUuHCZf1GWuOhfkVNFyyXpM3Y6Li8F775kTlHbpAv/8Y66qM2MGPP10Rr4qERERyVJumZh8X7g/AQH2XLxoXhusXGn2nLoXd1rUBcyFXea9CJtH1eeTNS8zYsFY1vzRjOpv7OKbgd1oVHkDAIGv92N+cPLj8+TNw/59+1WgEpF7puKUiMh9cWXRq/24cLwQbmUuMmDZEop6XknSwrDZcdK1/H09S506sGsX9OoFK1ZA9+7mEtGBgSQZMigiIiI5UGjSicnPXylKy8CdnDvnxSOPwA8/QKFC9366Oy3qAlAuKhTOL8TOzmBw84k0811N508X8EeILwEfrGV0x7d448kx1AvsRElnzyTHnjl4hjn95hAeHq7ilIjcszTNOTV58mTKlCmDi4sLfn5+bNmy5bZtT58+Tbdu3ahYsSJ2dnYMHjw4WZtp06bh7+9PkSJFKFKkCI0bN+b3339PSzQRkUwTFWUDvufCcXcKl7iSYmEqPbm6wnffwWuvmV+/8465Ak9MTIY9pYiIiFgtdIk5AfmNwlRsnD2dPl3I0TNelH3gMGtmrkhVYepmCYu63HqLqVmLKy6FE+fJrFTiAL++U4tn688g3rBn1Lfv0/nzhVyrWjfZsSkVu0RE7ibVxakFCxYwePBgRo4cya5du/D396d58+aEhISk2D4qKopixYoxcuRIfH1Tnl9l06ZNdO3alY0bNxIcHEzp0qUJCAjg5MmTqY0nIpIpDAPGjCkN1MalQCQvLFmaoYWpBHZ28OGHMH06ODjA3Lnm6jzXUu6VLyIiItlZfJzZYyqxTASBi99hw9+NyOccwXdD2+J2dEC6T0xu2OzY7GMuE5zwzHmcrjPj+b583uc5HOxj+HbLU0zq0IGrF1zS9blFJHdK9bC+CRMm0KdPH/r27QtAUFAQa9asYcqUKYwdOzZZe29vbyZOnAjAzJkzUzzn3Llzk3w9bdo0Fi1axI8//kjPnj1TPCYqKoqoqKjEry9rCSsRyUQTJ8KKFa5ALK0Cv8K9QtRdj0lPffpAiRLmKn4rV5pzUi1fDgUKZGoMERERSQe3m5w8/9XtVLjRYwrglwN1+GD5cABmPv8slT3/gkhuOzE5pH1y8sMevqys3jvZwi5dWyzibO2KvD/kJY4ElySoaSf6LfwOtzKXUv0cIiIJUlWcio6OZseOHQwfPjzJ/oCAALZu3ZpuoSIjI4mJiaFo0aK3bTN27FjeeeeddHtOEZF7tXEjvPJKwlev4OXnCHje4YiM0bw5rFkDrVrBpk3QqBGsXg13+NUpIiIiWcydJidPmJgcIOJ6PnpM+Zp4w56e/l/Sqda3ie1uNzE53N/k5Ldb2KWAzY5Blb7liy5tOHe4CJ+0eIoBS5fgUelCqp9DRARSWZwKDw8nLi4Od/ek44jd3d0JCwtLt1DDhw+nZMmSNG7c+LZtRowYwdChQxO/vnz5Mp6emf/HoYjkLufPm5ORx8dDq1bnWbHiE+CVux6XUerVgw0boFkz2LYNmjSB9evvfbUeERERsdadJidPmJgcIHDROxw9VxYvt2N80vPlJO1Smpgc0mdy8tst7FL8ofMMXruAqR3bcXqvG5+16cALS5YCoWl6HhHJ3dI0IbrtlqWhDMNIti+txo0bx7x581iyZAkuLrcfv+zs7EzBggWT3EREMpJhwHPPwalTULEiDB+e8lx7ma1GDdi8GYoVg507oWlTuPRvHJzZBMfmmffpPBeFiGR96b2Azc3mz5+PzWajbdu26RtaJBdLaXLyhInJdx+vysQ1gwCY0vsFCuU1pzQxgCsuhYmpWSvFic0zenLyQh6RvLh8MZ7VzhARnpdJbToQdqBUhj6niORMqSpOubm5YW9vn6yX1NmzZ5P1pkqL8ePHM2bMGNauXUvVqlXv+3wiIulpxgxYuhQcHeGbbyBPHuPuB2WShx+GH380V/Tbtg2a197FlRWtYWs3+LEhLPc2V/sRkVwhIxawSXD8+HGGDRuGv79/RkQXkZsYNjs2VWrHgFlTiIt3oOOj39K82mrzsRttNvu0w7Clqc9BushX9DovLF2CV43TRF504dtX+gGPWJZHRLKnVP0Wc3Jyws/Pj3Xr1iXZv27dOurUqXNfQT766CPeffddVq9eTY0aKU/mJyJilaNHYZD5gSXvvw+PZMFrripVYP2cHymS7wLBB2rQ4qNVRFzPZz4YedJchloFKpFc4eYFbHx8fAgKCsLT05MpU6ak2D5hAZuePXtS6A5r0sfFxfH000/zzjvvULZs2TtmiIqK4vLly0luIpJ6i4I7EnyoDvlcIgjqMThxf4RLYVZW781hjzsXlDND3kLRvLB4KWVrnyT6ah5gNUePahU/Ebl3qS6xDx06lOnTpzNz5kz27dvHkCFDCAkJoX///oA5F9StK+zt3r2b3bt3ExERwblz59i9ezd79+5NfHzcuHGMGjWKmTNn4u3tTVhYGGFhYURERNznyxMRuX+GAf37Q2SkOcfTK9ZNMXVn8XFUu96LdSOaUCjvRX4+4E/r8d9zLdqFxM9XdwzWED+RHC5hAZuAgIAk+9NjAZvRo0dTrFgx+vTpc9e2Y8eOpVChQok3zQ0qknqxUfasfLcuAPUG/0Fws3b84NuDRY8OZFaDt7JEYSqBS4EYnp+3HPeKoUAxBgx4kGPHrE4lItlFqiZEB+jcuTPnz59n9OjRnD59msqVK7Nq1Sq8vLwAc86CW7uMV69ePXF7x44dfPPNN3h5eXHsxm+ryZMnEx0dTceOHZMcFxgYyNtvv53aiCIi6WruXFi7FpydYfp0sLOu5zxw9+Wm/cqcYO3wABqPWc+mfQ3p/OkCFg/qgKNDLESGZshy0yKSdWTUAja//PILM2bMYPfu3ffUXovXiNy/n2dU5fzxQhT0iKDBwF2czJd8YvKsxKVgNO0/nMaUtp05e/ZhmjSBLVvAw8PqZCKS1aW6OAUwYMAABgwYkOJjs2fPTrbPMO48L8sxldRFJIsKD4chQ8ztt96C8hZfE97rctOPltvGimGtaPrhGr7f2YZen8/m6xd6YGdnZNhy0yKStaTnAjZXrlyhe/fuTJs2DTc3t3s6xtnZGWdn5zQ9n4hA1FUH1geZHyY1H/4rzvliLU50b/IWigQCKFHiCP/840zz5maBKn9+q5OJSFaWpuKUiEhuMWyYWaCqUgVefdXqNPe+3DRAPZ8tLBrUkbYfL+ObrU9TOO9FPuv1YoYuNy0i1suIBWwOHz7MsWPHaN26deK++Ph4ABwcHDhw4ADlypVLe2gRSWbrrCpEhOfF1fsij3bbe/cDspRTTJ58iOeeq8zu3dClC3z3HdjbW51LRLIqFadERG7jt9/gyy/N7S++MFfpyyoSlpu+WYxRkiub1pL/+kUS+ka0rL6Kr/r35OnJc5m8fiB5C13D8wt7PC1c1UdEMtbNC9i0a9cucf+6det48skn03TOSpUq8eeffybZN2rUKK5cucLEiRM1XE8knUVHOrDhMz8Amgzdhr1D1lkh+F55ekbz/ffQoAGsXGn2RP/kE6tTiUhWpb9ORERSEB8PL79sbvfqBbVqWRrnnhg2Ozb7mH+I3nwJ27XOfCb1Modij188jB8/04qoIjldei9g4+LiQuXKlZPcChcuTIECBahcuTJOTk6Z/hpFcrKtX1bmytl8FC19iZqd91sdJ80eewzmzDG3P/1UxSkRuT31nBIRScHXX8Pvv0OBAjB2rNVp7t1hD19WVu9N/X1LKXD9YuL+7q0W8Gvhxnz1cUeWB/qTp2AUtZ/527qgIpKhMmIBGxHJHNHX7NnwiflBUpMh27B3jLc40f3p0AHGjYPXXoPBg835O5s3tzqViGQ1Kk6JiNziyhUYPtzcfvPN7LfCzGEPX464V6HEhcPki7rMVeeCnCpajkcanuRE3HY2fFKDhUMb4VIwmurtDlkdV0QySHovYHMv5xCR+7dt/kNcPpOPIqUuU7PrPqvjpIthw+DQIZg2Dbp1g23b4MEHrU4lIlmJhvWJiNzio48gLMy8aEoY2pfdGDY7TrqW52AJP066lse4McdU68BfqP3MnxiGjTn9m3Jgk+aJERERySri42HTFLMXY4OBO3Fwyt69phLYbOawvtq14eJFaNvW/DBQRCSBilMiIjc5cwYmTDC3P/gActoq6DYbPDV+I9WePEhcjD0ze7YidE8xq2OJiIgIsG9dGc79UwSXglE8lu1W6LszZ2dYvBiKF4e//4bevSGVHTZFJAdTcUpE5CZjxsDVq1CzJrRvb3WajGFnb9B96lrK+4cSFeHE553aEn60kNWxREREcr1Nk81eU3We+ROXAjEWp0l/xYubBSpHR/P+gw+sTiQiWYWKUyIiNxw7BlOmmNsffGD2MsqpHJzjePbrFZSofI6Ic3mZ2rEtVy/ktzqWiIhIrnX2nxIc2uKJnX08/s/tsTpOhqldGyZNMrdHjYKffrI2j4hkDSpOiYjcEBgIMTHQpAk88YTVaTJenoLR9Fu4DFevS4QfLcyS4X0BFahERESssOPbegD4PnmIIqUiLE6TsZ57Dnr2NOfY6toVzp2zOpGIWE3FKRER4K+/4Ouvze0xY6zNkpkKeUTSf9Ey8rtFcvZQKWAJMTE5uMuYiIhIllSM/RuqAdDghV3WRskkkyZBpUpw6tR/hSoRyb1UnBIRwexWbhjQsSPUqGF1msxVrNxFnl/wHY4uUUATAgO9dIEoIiKSqZ4lPtYBL7/TePmdsTpMpsifHxYuBBcXWL3aXC1ZRHIvFadEJNfbtQu++w7s7ODdd61OY43S1c/SZvSXQAxr1hRl6FCtoCMiIpIZzA+E+gFQp/eflmbJbFWqwCefmNsjR8Ivv1ibR0Sso+KUiOR6779v3nfpYnYvz628ax4EegEwcSKMG2dpHBERkVzh118LAmVwzh9J9baHrI6T6fr2Needioszr8X+/dfqRCJiBRWnRCRX+/tvcyljgDfesDZL1vANQ4eeAGD4cPjyS4vjiIiI5HCLFrkB8HDT7TjljbU4Teaz2eDzz6F8eThxAgYMAOLj4MwmODbPvI+PsziliGQ0FadEJFdL6DXVoQM8/LC1WbKKp58+y6uvmtt9+pjzQIiIiEj6Cw2FLVsKAVC1TbDFaaxToADMmQP29jB/Psx7dRD82BC2djPvl3tD6BKrY4pIBlJxSkRyrYMHYcECc3vUKGuzZDUffADdu5td7Dt2hG3brE4kIiKS80yfDvHxNmAjrqXPWR3HUo8+Cm++vBeAF6a+R+j5Uv89GHkStnRUgUokB1NxSkRyrbFjzUlIW7eGatWsTpO12NnBjBkQEABXr0LLlvDPP1anEhERyTni42HWrISvvrAyStYQH8fIui14tNxvXIoszDNTv7xRuAO4sUrLjsEa4ieSQzlYHUBEJFPFx8G5LRw9eJmvv24N2NRr6jacnGDRImjQAHbuhGbNYOtWeOABq5OJiIhkfxs2mMP6ChSI5cqVpcCLVkfKcCEhIYSHh6f4WP6r26kQdZw5A7pT7Y3dbNz7BBPXDGJI86AbLQyIDOXgLzOIyFcj2fFubm6ULl0648KLSIZScUpEco/QJbBjEESeYMKXnxAXZ6OJ7088WjwcaG91uiypQAFYuRLq1IHDh80eVBs3Qv78VicTERHJ3mbPNu+bNv2XRYuiLM2SGUJCQqjkU4lrkddSfLxLbZj3IpT3+IcJTw+l/8zPGbFgLE0qr6Oy59+J7QJf78f8FKbnypM3D/v37VeBSiSbUnFKRHKH0CXmXAUYnL9SlJmbnwVgeMt3YMtG8F8EnipQpcTDw5wUvW5d2L7dnIPq++/B0dHqZCIiItnTpUv/rRbcuvV5Fi2yNk9mCA8P51rkNbp/3h33Cu7JHi8XFQrnFwLw/BNf8P3O1qzc3Ypen8/m13dq4WBvDuerF9iJks6eSY49c/AMc/rNITw8XMUpkWxKc06JSM4XH2f2mLoxX8GU9S8QGZWP6t47afjQBrON5jC4owoVYMUKyJsX1qyBvn3BMKxOJSIikj0tXAjXr8NDD8HDD0daHSdTuVdwx9PXM9ktpmYtrrgUxgBsNpjW9zkK5/2XHUdrMH7lMAzgikthYmrWSnZsSsUuEcle1HNKRHKEu85hEHkCgOvRzny69iUAXm35ETYb3G0OA9A8BgCPPWZeTD/5JHz1FZQsCWPGWJ1KREQk+0mYCL1XL25ci4hhs2OzTzta7pqFARQvEkZQj8H0+vxLAhe/Qxu/7zjSqjaGTf0rRHIiFadEJNu71zkMAL7+uQdnL7tT2vU4HR9N2of+dnMYgOYxSNCyJXzxBfTpY652WLIkDBxodSoREZHs48ABCA4Ge3vo3h1On7Y6UdZx2MOXldV7U3/fUgpcv0hP/69Y8GtnftjTgvZzv6df71XYoa7bIjmRilMiku3d6xwG8fE2/rfqFQCGNP8YR4fYJO1SmsMANI/BrZ59Fk6ehLfegpdeguLFob2m6xIREbknCROhN2tm/h+q4lRShz18OeJehRIXDpMv6jJPfrqVjS0bcWDPg2yeWo2GA3dZHVFEMoCKUyKSYyTMYXCrGKMkVzatZcMv/hw4XYlCeS/Sp8GMxMcNICJhDgN1Fb8no0aZBarPP4du3WDdOvD3tzqViIhI1hYXZw6NB+jd29osWZlhs+Oka3nzixLw5LtbWDC4Maver0PlZkcpVu6ipflEJP3przARyfES5jD438phALzQaAoF8kSYj91os9mnneYwSAWbDSZNMuefioqCNm3g778xJ5U/swmOzTPvNcm8iIhIoo0b4dQpKFoUWrWyOk32UavH31SoH0LMdQfmvdyY+HirE4lIetNfYiKSK2w605gtB+rhYB/DS00/Tdwf4VKYldV7c9jD18J02ZO9PcybB3XqwMWL0KxJJCdm1oIfG8LWbub9cm8IXWJ1VBERkSzhm2/M+6eeAmdna7NkJzYbdJ64Hqd80RwJLslvcx62OpKIpDMVp0QkV9jyRTUAfNv9w9am7fnBtweLHh3IrAZvqTB1H/Lkge+/h0oPXubE6bw0f2cmF68W+q9B5EnY0lEFKhERyfWuX4fFi83tbt2szZIduZa+QvPhvwKwPPBxrpzNa3EiEUlPKk6JSI4XEZ6HnUsqAOD/3B+cdC3PwRJ+nHQtr6F86aBo4ThWvxpAiSIn+etEFZ6c8B3XoxM+Dr4xcHLHYA3xExGRXG3VKrh8GUqVgscftzpN9lSv325K+Z7h2iUXlo6sZ3UcEUlHmhBdRHK84K8qExvlQOlHwvCqEWZ1nGwpJCSE8PDwFB/Lf3U7FfL/xg+vNcd/9BZ+2l+fHlO+Zv5LXbC3iwcMiAzl4C8ziMhXI9nxbm5uWgVRRERyvIQhfV27gp0+G0sTeweDzh9vYELjzuxcXJGaXfbi0yjE6lgikg5UnBKRHC0uxo6fZ1QBwP+5PdhsFgfKhkJCQqjkU4lrkddSfLxLbZj3IlQt/SfLhrSl2bjVLPr9KYZ8fZqJPQclvueBr/djfnDy4/PkzcP+fftVoBIRkRzr0iVYscLc1pC+++NZ7Sz+z+3hp8+rs2jYE7z+yxyrI4lIOlBxSkRytD9XluXS6QLkLxZJ9baHrI6TLYWHh3Mt8hrdP++OewX3ZI+XiwqF8wsBaPjwJr7q35Muny3g07UvU7LoSV5vPQ6AeoGdKOnsmeTYMwfPMKffHMLDw1WcEhGRHGvpUnN1Wx8f8NVUl/etxRvB/PH9g5w/Xog14x+l2pNHrY4kIvdJxSkRydF+ujERep1n/sTBWXMe3Q/3Cu54+nom2x9jlOTKprXkv34RG9C59kJOXSzB0DkfM3z+hxQvfIp2TVYQU7MWnprjS0REcqF588z7bt1QL+504FIghg7jNjGje2s2fvYIJatstjqSiNwn/ZUgIjnWiT+KceTXktg5xFG3959Wx8mxDJsdm33amds39g1pHsQrLcYD0GfaTD4+P0qTz4uISK505gysX29ud+1qbZacpEqLI1Rt9Q/xsfas+19HQFU/kexMfymISI71y0xzrinf1v9QqPhVi9PkbIc9fFlZvTcRLoUT943r+hpP+X9LbJwj7w95idDdD1gXUERExCILF0J8PDz2GJQrZ3WanKX9B5twzh/F6b3eQB+r44jIfdCwPhHJka5fdmLH4ooA1H1WvaYyw2EPX464V6HEhcPki7rMVeeC1Gp8ij1dQji4uTSfd36SwWsW4OZ92eqoIiIimSZhlT5NhJ7+Cpe4SvMRv7JsZH1gLBcvnrQ6koikkXpOiUiOtGNJBaKvOvFA+QuUq6MLlcxi2Ow46VqegyX8OOlaHntnePbLlZSscpaIc3mZ2rEdEeF5rI4pIiKSKY4cgV9/BTs76NTJ6jQ5k/9ze3ArcxpwY/LkElbHEZE0UnFKRHIcw4Dg2eaQvjrP/KWJRy3mUjCa5xd8R9HSlwg/UpgvurQh6qo67opktMmTJ1OmTBlcXFzw8/Njy5Ytt217+vRpunXrRsWKFbGzs2Pw4MHJ2kybNg1/f3+KFClCkSJFaNy4Mb///nsGvgKR7C9hIvRGjcDDw9osOZW9g0GjQUsBWLLEje3bLQ4kImmi4pSI5Dihu9w58ccDODjHUrPLPqvjCFDII5J+3y4jX9FrhOz04MtnWxAXo/+CRDLKggULGDx4MCNHjmTXrl34+/vTvHlzQkJCUmwfFRVFsWLFGDlyJL63Wed+06ZNdO3alY0bNxIcHEzp0qUJCAjg5En1ThW5nW+/Ne87d7Y2R05XyvcIMAfDsDFggDnHl4hkL/rLQERynK1fVgbAt80/5Ct63eI0ksC9/EWem7ccxzwx7F1XhoVDn8Aw7n6ciKTehAkT6NOnD3379sXHx4egoCA8PT2ZMmVKiu29vb2ZOHEiPXv2pFChQim2mTt3LgMGDKBatWpUqlSJadOmER8fz48//phi+6ioKC5fvpzkJpKbHDoEe/aAvT20bWt1mtzgVfLli2PbNpgxw+osIpJaaSpOpXc3cYDFixfz0EMP4ezszEMPPcTSpUvTEk1Ecrnrl53YuaQCAHV6aSL0rMa7ZhjPzPgBm108v819mK2zmlodSSTHiY6OZseOHQQEBCTZHxAQwNatW9PteSIjI4mJiaFo0aIpPj527FgKFSqUePP09Ey35xbJDhYtMu8bNQJXV2uz5A5h9O9/CoARI+D8eYvjiEiqpLo4lRHdxIODg+ncuTM9evRgz5499OjRg06dOvHbb7+lNp6I5HLbF1Uk+qoT7hXOU7bWKavjSAoqNztKpwkbAPj16yZAP2sDieQw4eHhxMXF4e7unmS/u7s7YWFh6fY8w4cPp2TJkjRu3DjFx0eMGMGlS5cSb6Ghoen23CLZQUJxqmNHa3PkJp06naNyZbMwNXKk1WlEJDVSXZzKiG7iQUFBNGnShBEjRlCpUiVGjBhBo0aNCAoKSm08EcnFDAO23pgIvbYmQs/Savf8m2av/3rjq0ls3Jjy/w8ikna2W34JGoaRbF9ajRs3jnnz5rFkyRJcXFxSbOPs7EzBggWT3ERyiyNHYOdOc0hfu3ZWp8k9HBxg0iRz+4sv0OToItlIqopTGdVNPDg4ONk5mzZtesdzah4DEblV2H5PTv1VTBOhZxNNX/uNKi1/BewZObIMv/xidSKRnMHNzQ17e/tkvaTOnj2brDdVWowfP54xY8awdu1aqlatet/nE8mJEnpNNWgAbm6WRsl16tWDp582P7QcOFCTo4tkF6kqTmVUN/GwsLBUn1PzGIjIrf74vhYA1doeIl+RKIvTyN3YbNB4yBJgOVFRdrRuDXv3Wp1KJPtzcnLCz8+PdevWJdm/bt066tSpc1/n/uijj3j33XdZvXo1NWrUuK9zieRkCav0PfWUtTlyq48+ggIF4PffYdYsq9OIyL1I04ToGdFNPLXn1DwGIpJUPg5srAZA7Z5/WRtF7pmdfTzQhSpVIvj3X2jWDLQqvcj9Gzp0KNOnT2fmzJns27ePIUOGEBISQv/+/QHzOqpnz55Jjtm9eze7d+8mIiKCc+fOsXv3bvbeVDEeN24co0aNYubMmXh7exMWFkZYWBgRERGZ+tpEsrpjx8zhZHZ2GtJnleLF4e23ze033gANshHJ+lJVnMqobuIeHh6pPqfmMRCRpDoQc90Zt7IXNRF6tnONjz8+TIUKEBoKzZvDxYtWZxLJ3jp37kxQUBCjR4+mWrVq/PTTT6xatQovLy/AXE351sVsqlevTvXq1dmxYwfffPMN1atXp0WLFomPT548mejoaDp27Ejx4sUTb+PHj8/U1yaS1SUM6atfHx54wNosudmLL0KFCnD2LLz7rtVpRORuUlWcyqhu4rVr1052zrVr195313MRyU16AfBo172aCD0bKlIkjjVrwMMD/vzT/KQ5SiMzRe7LgAEDOHbsGFFRUezYsYN69eolPjZ79mw2bdqUpL1hGMlux44dS3z82LFjKbZ5O6F7gogAWqUvq3Bygo8/NrcnToSDB63NIyJ3luphfRnRTXzQoEGsXbuWDz/8kP379/Phhx+yfv16Bg8efH+vTkRyhZMnnYCGYIunZuf9VseRNPL2hh9+MOeI2LQJevbUJKYiIpK9hITAb7+Z8yq2b291GmnRwuyRHRMDr7xidRoRuROH1B7QuXNnzp8/z+jRozl9+jSVK1e+p27iCRK6int5eSV+GlenTh3mz5/PqFGjePPNNylXrhwLFizgscceu4+XJiK5xcqVRQEo/cg/FCl1xeI0cj+qVYOlS80LyYULoUQJmDAB9YYTEZFsYfFi897f3+wNLNb7+GNYtw5WrIDVq835LUUk60l1cQrMbuIDBgxI8bHZs2cn22cYxl3P2bFjRzqq76uIpFJ8PKxY4QpA5abbLE4j6aFRI/jyS+jWDYKCoGRJGDbM6lQiIiJ3p1X6sp6KFeHll80Pu4YMMa8zHB2tTiUit0rTan0iIlnFli1w8qQzcJkH/bVKX07RtSskzLH86qswd661eURERO7mxAkIDtaQvqzozTehWDHYvx8mT7Y6jYikRMUpEcnW/uusuQBHlxgLk0h6e+UV8xNOgN69Yf16a/OIiIjcScKQvrp1zWHpknUULgzvv29uBwbCuXOWxhGRFKg4JSLZVkTEf93nYbaFSSSjjB8PXbqYE5m2awe7dlmdSEREJGVapS9re/ZZc27LS5fgrbesTiMit1JxSkSyrcWL4epV8PS8Dmy1Oo5kADs7s3dcw4ZmMbJ5czh61OpUIiIiSZ06Bb/8Ym536GBtFkmZvT1MnGhuf/EF7NljbR4RSUrFKRHJthKG9LVufcHSHJKxnJ3NFfyqVoUzZ6BpU3XHFxGRrGXJEjAMqF0bSpWyOo3cTr160KmTuaDOoEHmv5mIZA0qTolItnTsGGzaZE462qLFeavjSAYrVAh++AG8vODQIWjZ0uxJJSIikhVolb7sY9w4cHGBzZv/mydMRKyn4pSIZEvz5pn3DRtC8eKaCD03KFEC1qwBV1fYts385DMmBoiPgzOb4Ng88z4+zuKkIiKSm4SFmasHg4b0ZQdeXvD66+b2sGFw7Zq1eUTEpOKUiGRL33xj3j/9tLU5JHNVrAgrVkCePGZPqr5dj2N85w0/NoSt3cz75d4QusTqqCIikkskDOl77DEoXdrqNHIvXnvNHH55/Dh8/LHVaUQEVJwSkWzozz/hr7/AyQnat7c6jWS2WrXM4RP29vF8tdiLEbMGJm0QeRK2dFSBSkREMoVW6ct+8uaFDz4wt8eONXu/iYi1VJwSkWwnoddUy5ZQuLClUcQiLZvHMe2FVwH48PvhTFz98k2P3pjddMdgDfETEZEMdfasOXcRqDiV3XTtCo8+as5h+eabVqcREQerA4iIpEZ8/H/FqW7drM0iGSskJITw8PAUH8t/dTu9a08g7KwTbywcy5A5H+NRKIzOtRfeaGFAZCgHf5lBRL4ayY53c3OjtMZeiIhIWsXHwbktLJ2Rl/j4R6lRw8Db22Z1KkkFOztzSF/dujBjBrz4Ivj6Wp1KJPdScUpEspWtWyEkBAoWNHtOSc4UEhJCJZ9KXItMeZbSLrVh3oswvM0HnLpYgs/WvkTPqV9RrOA5nnh4Y2K7wNf7MT84+fF58uZh/779KlCJiEjqhS6BHYMg8gTffrMOgKceGgOhPuCp+Qaykzp1zAVWFi6EoUMN1s/djO36achTHIr5g5291RFFcg0Vp0QkW0noNdW+vTkptuRM4eHhXIu8RvfPu+NewT3Z4+WiQuH8Qmw2COoxmDOX3Pn2t060nbCMn96sRzXvPQDUC+xESWfPJMeeOXiGOf3mEB4eruKUiIikTugSc15DDM5ddmPTvgYAdKw+E7YcBf9FKlBlMx9+CN99F8eGDfasGP8/Wj+ywnwgbynwm6h/T5FMojmnRCTbiIkxP9kCDenLLdwruOPp65nsFlOzFldcCmMA9nbxfNW/Jw18NnLlekGaf/QDR856c8WlMDE1ayU7NqVil4iIyF3Fx5k9pm7Mbbhse1vi4h14xHsHZR84YrbRfIfZjrf9EoYEfATAsG/GEx3raD6gBVZEMpV6TolItrFuHZw/D+7u0LCh1WnESobNjs0+7Wi5axYG4OIUxbKhban37k/8EeJLsw/XELhoEoZNn8GIiMi9u9t8hxUiTyR+veh3cwb0jo/eWK7vLvMdguY8zHJuFBxHtLnEzM29OXi6IlPWv8CgZp9gFiFtZsGx5JMa4ieSwVScEpFsI2FIX+fO4KDfXrneYQ9fVlbvTf19Sylw/SKF8l7mh9eaU/udXzkUVoE3Xh7BwGVLcM4fY3VUERHJBu51vkOA81eK8uPfjQDo+NiiJO1uN98haM5DK9xLwbFgXnj3qTfpN+ML3lkSSI/Hv6Zo/n9RwVEk8+jPOxHJFq5ehWXLzG0N6ZMEhz18OeJehRIXDpMv6jJXnQvSvcYGJrboTMhOD2b1bsFz33yPvWO81VFFRCSLu9f5DgGW7TCH9PmW3k15j3+StEtpvkPQnIdWSE3BsU+DGXy29kX+DK3K6KVvEdRjSGI7FRxFMp6KUyKSLXz/vVmgKlsWHn3U6jSSlRg2O066lk/8+gHXSzw3/zsmt+3A/h+9mT+oEd0mrcOmFb5FROQeJMx3eKsYoyRXNq0l//WLLPrNHNL31GPfJj5uABEJ8x1qWHmWkJqCo71dPP97+hUCPljHpHUDeaHRFCqWOAio4CiSGVScEpFsYf58875rV1RkkLvyrnGGZ2auYsbTrdk2/yEKukfSOvAXq2OJiEg2ljDfYe0ty1j/d2Pgv+KUcaPNZp92mu8wC7qXgqMNaFJlPS2rrWDl7la8Nm8cy15pq4KjSCbRT5iIZHmXL8Pq1eZ2587WZpHs4+GAY3SeuB6AHyfWYMv0qhYnEhGR7O6why/vhn9EbJwjVTz/oELxQ4DZY2pl9d4c9vC1OKGkRkLBEf4rMI5/ehj2drEs3/kkG/5uqIKjSCbRT5mIZHkrVkBUFFSsCJUrW51GspPHuu2j5aitACwdUZ/9G9TlXkRE7s+6TU8A8FD7EH7w7cGiRwcyq8FbKkxlUwkLrES4FAagUokDvNB4CgB9F3/JoWLVrAsnkotoWJ+IZHnf3pjOoWNHDemT1Gs8ZBtnDxdm27yHmP1sC7p8etDqSCIikk1FXnLiwCbzg44yXS5wsISfxYkkPdy6wMoj750gz2/XOXbAk9+/eYhaPf62OqJIjqeeUyKSpV25Aj/8YG4/9ZS1WSR7stmg84QNlHnsFNcvO7PsjWeBIlbHEhGRbOivH8oSF2OPR6VwPCr+a3UcSUcJC6wcLOHH5QdL0PTV3wFY+X5trl9xtDidSM6n4pSIZGkrV5pD+sqXh6qaMkjSyME5jme/WkERz8tcPFkM+JaYGKtTiYhIdrPnO3N1WN82/1icRDLa43334Fb2IlfO5uPHiTWsjiOS46k4JSJZWsKQvqee0pA+uT8Fil3juXnLccxzHWjE+PHJV+0RERG5nWuXndi/0RzSV+3JQxankYzm4BRPm3e2ALBx0iNcCC1gcSKRnE3FKRHJsiIiYNUqc1tD+iQ9lHjoPC1HfQPEs2hRMWbPtjqRiIhkF3+vLkNctAPuFc5T3OeC1XEkE1RpcYQHHw8lNsqBFaPrWh1HJEdTcUpEsqyVK+H6dShXDny1AI6kk3J19gJvA/DCC7Bnj6VxREQkm9itIX25js0Gbd/bgs1msHNxRY5t87A6kkiOpeKUiGRZGtInGec96ta9xPXr0KEDXLxodR4REcnKrl92Yv8GLwCqtdWQvtykVNVz1Oy6F4ClI+thGBYHEsmhVJwSkSzp6lUN6ZOMZDB69DG8vODwYejVC11siojIbf29tgyxUQ4Ue/BfivuctzqOZLKWo7bilC+a49uLs2tJBavjiORIKk6JSJa0ahVcuwZly0L16lankZyocOE4Fi0CJyf47jv4+GOrE4mISFa1Z/mDgDkRunpz5z6FPCJp9PIOAFa+V4fYKHuLE4nkPCpOiUiWlDCkr2NHDemTjFOjxn9FqREjNP+U5CyTJ0+mTJkyuLi44Ofnx5YtW27b9vTp03Tr1o2KFStiZ2fH4MGDU2y3ePFiHnroIZydnXnooYdYunRpBqUXyTqiIhzZt94bAN82GtKXWzUYsJOCHhGcP16IX2ZVsTqOSI6j4pSIZDnXrpmToYOG9EnGe+EFaNMGoqOhWzfz+08ku1uwYAGDBw9m5MiR7Nq1C39/f5o3b05ISEiK7aOioihWrBgjR47E9zYrUAQHB9O5c2d69OjBnj176NGjB506deK3337LyJciYrm/13oTc90Bt7IXKVk53Oo4YhHnfLE0f/1XANaOf5Rrl50sTiSSs6g4JSJZzrp1EBkJpUuDn5/VaSSns9lg+nTw8IC9e+HVV61OJHL/JkyYQJ8+fejbty8+Pj4EBQXh6enJlClTUmzv7e3NxIkT6dmzJ4UKFUqxTVBQEE2aNGHEiBFUqlSJESNG0KhRI4KCglJsHxUVxeXLl5PcRLKjPTdW6dOQPnn06b08UP4CVy/k4ceJNayOI5KjqDglIlnOsmXmfdu2GtInmaNYMZg929yeNAlWrLA0jsh9iY6OZseOHQQEBCTZHxAQwNatW9N83uDg4GTnbNq06W3POXbsWAoVKpR48/T0TPNzi1gl6qoDezWkT26wdzBo8/bPAGyeUp0r51Iu5otI6qk4JSJZSmwsLF9ubrdta2kUyWWaNoWEaXb69IHzWoxJsqnw8HDi4uJwd3dPst/d3Z2wsLA0nzcsLCxV5xwxYgSXLl1KvIWGhqb5uUWssm+dNzHXHHH1vkipquesjiNZwMPNjlK21klirjuwdVbA3Q8QkXui4pSIZClbt5pFgSJFwN/f6jSS24wdCw89BGfPwtChVqcRuT+2W7qeGoaRbF9GntPZ2ZmCBQsmuYlkN7tvDOnzbfOPenMLYPbqb32j99Tfa2oCD1sbSCSHUHFKRLKUhCF9rVuDg4OlUSQXcnGBGTPMC8+vvoI1a6xOJJJ6bm5u2NvbJ+vRdPbs2WQ9n1LDw8Mj3c8pkpVFRzqwd10ZwJxvSiRBmUfD8G19CCPeDvjA6jgiOYKKUyKSZRhG0vmmRKxQqxYMGmRuP/88XLlibR6R1HJycsLPz49169Yl2b9u3Trq1KmT5vPWrl072TnXrl17X+cUycr2rfcmOtKRoqUv4VntrNVxJItp+eZWbHZxQCt27MhvdRyRbE/FKRHJMv74A44eNXuvBGgIv1jovffA2xtCQmDkSKvTiKTe0KFDmT59OjNnzmTfvn0MGTKEkJAQ+vfvD5jzQfXs2TPJMbt372b37t1ERERw7tw5du/ezd69exMfHzRoEGvXruXDDz9k//79fPjhh6xfv57BCZO1ieQwu797ENCQPknZAw9epGrrXwGYOLEkhmFxIJFsTsUpEckyEnpNBQRAvnyWRpFcLl8+mDbN3P7sM3MuNJHspHPnzgQFBTF69GiqVavGTz/9xKpVq/Dy8gLg9OnThISEJDmmevXqVK9enR07dvDNN99QvXp1WrRokfh4nTp1mD9/PrNmzaJq1arMnj2bBQsW8Nhjj2XqaxPJDNHX7Pl7rYb0yZ3V7rkOuMLff+fj22+tTiOSvWlGFxHJMjSkT7KSxo2hd2+YNQsGDIAdO8De3upUIvduwIABDBgwIMXHZs+enWyfcQ8f+3fs2JGOHTvebzSRLG//j95EX3WiSKnLlH7kjNVxJIvKVzQCGA+8w5tvQvv2mjNVJK3S1HNq8uTJlClTBhcXF/z8/NiyZcsd22/evBk/Pz9cXFwoW7YsU6dOTdYmKCiIihUrkidPHjw9PRkyZAjXr19PSzwRyYaOHYPdu8HODlq1sjqNiGncOHPlyD17IIX/ukREJIfas1xD+uReTaBw4RgOHjQXUxGRtEl1cWrBggUMHjyYkSNHsmvXLvz9/WnevHmyruEJjh49SosWLfD392fXrl288cYbvPzyyyxevDixzdy5cxk+fDiBgYHs27ePGTNmsGDBAkaMGJH2VyYi2cp335n3jz8OxYpZm0UkgZubOf8UwKhRcO6ctXlERCTjxUQ58Ndqc0ifbxsN6ZO7iaBXL7N33TvvQFSUxXFEsqlUF6cmTJhAnz596Nu3Lz4+PgQFBeHp6cmUKVNSbD916lRKly5NUFAQPj4+9O3bl2effZbx48cntgkODqZu3bp069YNb29vAgIC6Nq1K9u3b0/7KxORbCVhSF+7dpbGEEmmXz+oVg0uXoQ33rA6jYiIZLRjv1UiKsKZwiWv4FUjzOo4kg089dQ5SpQwF1JJmLNSRFInVcWp6OhoduzYQcAty2gFBASw9TazxQYHBydr37RpU7Zv305MTAwAjz/+ODt27OD3338H4MiRI6xatYqWLVveNktUVBSXL19OchOR7On8efjpJ3P7ySetzSJyK3t7c1J0gOnTYdcua/OIiEjG2r+xGgDV2x7ETstHyT1wcTEYNcrcfv99iIy0No9IdpSqX7fh4eHExcXh7u6eZL+7uzthYSl/qhAWFpZi+9jYWMLDwwHo0qUL7777Lo8//jiOjo6UK1eOhg0bMnz48NtmGTt2LIUKFUq8eXp6pualiEgWsmIFxMdD1apQpozVaUSSq1sXunY1t199FS0XLSKSY+XlyK8PAVC9nYb0yb3r0we8vSEs7L8PtUTk3qXpswDbLbMCGoaRbN/d2t+8f9OmTbz//vtMnjyZnTt3smTJElasWMG7775723OOGDGCS5cuJd5CQ0PT8lJEJAtYscK8b9PG2hwidzJmDDg5wY8/wpo1VqcREZGM0ZLY6064el/Es7pW6ZN75+QEb79tbn/4IVy6ZGkckWwnVcUpNzc37O3tk/WSOnv2bLLeUQk8PDxSbO/g4ICrqysAb775Jj169KBv375UqVKFdu3aMWbMGMaOHUt8fHyK53V2dqZgwYJJbiKSzcTHER26mbVrogFo1SLO4kAit+ftDS+9ZG6/+qpB3KlNcGwenNkE8freFRHJGToDUK3tIa3SJ6nWvTtUqgQXLsDHH1udRiR7SVVxysnJCT8/P9atW5dk/7p166hTp06Kx9SuXTtZ+7Vr11KjRg0cHR0BiIyMxO6WAd329vYYhpHYy0pEcpjQJbDcm5+nvsPlK04UK3iWmqfLmPtFsqiRI6FIoWj++svGl29/BVu7wY8NYbm3vndFRLK5q1ftgBYAVG930Nowki3Z28Po0eb2hAnmvKoicm9SPaxv6NChTJ8+nZkzZ7Jv3z6GDBlCSEgI/fv3B8zhdj179kxs379/f44fP87QoUPZt28fM2fOZMaMGQwbNiyxTevWrZkyZQrz58/n6NGjrFu3jjfffJM2bdpgb2+fDi9TRLKU0CWwpSNEnmDFrlYAtKy2ErvrJ8z9+iNfsqgiEUsY1WoEAG8veZuoGCfzgciT+t4VEcnmNm8uBOShiOdZSlYOtzqOZFMdOpir/F65Yg7vE5F7k+riVOfOnQkKCmL06NFUq1aNn376iVWrVuHl5QXA6dOnCQkJSWxfpkwZVq1axaZNm6hWrRrvvvsun3zyCR06dEhsM2rUKF555RVGjRrFQw89RJ8+fWjatCmff/55OrxEEclS4uNgxyDA7BWZUJxqVX1F4j52DNYwKcl6bnzvDmg8iRJFThJ6vjQzNvW58aC+d0VEsrt164oAULHBHg3pkzSzs4P33jO3P/sMzp61No9IduGQloMGDBjAgAEDUnxs9uzZyfbVr1+fnTt33j6EgwOBgYEEBgamJY6IZDEhISGJq3HeKv/V7VSIPAHAwdPlORRWAUf7aJpUThj+a0BkKAd/mUFEvhrJjndzc6N06dIZFV1yuXv53nVxgpFPvs/A2ZN5/7uR9K4/izxO17nb9y7o+1dEJKu6eBG2bjXnsK3YcDfgZGUcyeZatICaNWHbNhg/HsaNszqRSNaXpuKUiMjthISEUMmnEtcir6X4eJfaMO9Fczuh11R9n80UzHslSbvA1/sxPzj58Xny5mH/vv36A1/SXWq+d/s0mMGH379OyHkvvtjwPIOafZLY7nbfu6DvXxGRrGrZMoiNtQP+wq3MGcDT4kSSndlsEBgIrVrBpEnw6qtQrJjVqUSyNhWnRCRdhYeHcy3yGt0/7457heSreJaLCoXzC4Fbh/QlVS+wEyWdk14Ynjl4hjn95hAeHq4/7iXdpeZ719kxmlFt3+P5GdMYu3wEzzWcRl5ns6iV0vcu6PtXRCQrW7AgccvKGJKDtGgBfn6wY4e5ct+YMVYnEsnaVJwSkQzhXsEdT9/kf6DHGCW5smktsecNthzwB5IWpwwgwqUwMTVr4WlL9bR4Ivftbt+7+a9fxAb0qjebsctHcPRcWbP3VPOJ+t4VEcmGzp+H9esTvloAtLEwjeQUNhu89RY8+SR8+im88gq4ulqdSiTr0tWziGQqw2bHZp92rP0zgNg4RyqV2Ec59yPmYzfabPZph6E/7iWLSfjeBfN71dEhluFtPgDgf6teITrWUd+7IiLZ0JIlEBsLFStGAoesjiM5SOvW4OsLEREQFGR1GpGsTVfQIpLpDnv48vnxwUDSXlMRLoVZWb03hz18LUomcmeHPXxZWb03ES6FAXjG/0uKFz7FiQuevBYyVd+7IiLZUMKQviZN/rU2iOQ4Cb2nAD75BP7Vt5jIbak4JSKZLj7Oxu8/Vwcgf1dHfvDtwaJHBzKrwVv6416yvMMevsxq8BaLHh3IhhqdadzvNwDmf9WW+DitPS4ikp2cOQMbN5rbKk5JRmjbFqpUgcuXYeJEq9OIZF0qTolIpju+3YOrF/KQp9B1CjSx52AJP066ltdwKMk2DJsdJ13Lc7CEHw8POE2eQtc5e6gof64sZ3U0ERFJhcWLIT4eataEUqWirY4jOZCdHbz5prkdFAQXL1qZRiTr0l+CIpLp9q7zBqBSo+PYO8ZbG0bkPrkUiMG/7x4A1gfVwDDucoCIiGQZCUP6One2NofkbB06wEMPwaVLMGWK1WlEsiYVp0Qk0/29pgwADwcctTiJSPqo128PjnliCN3tzpFfS1gdR0RE7sGpU7Bli7n91FPWZpGczc4Ohg83tydOhGvXrM0jkhWpOCUimeriyfyc+rsYNptBpUbHrY4jki7yu12jxlP7AfhpajVrw4iIyD359lswDKhdG0qXtjqN5HRdupjfZ2fOwJdfWp1GJOtRcUpEMlXCkD6vGqfJ73rd2jAi6aje8+bQvj9WluN8SAGL04iIyN1oSJ9kJkdHeOUVc/ujjyA21to8IlmNilMikqn2rvcG4KEmxyzNIZLeij90ngr1QzDi7fh5uladFBHJyo4dg+BgsNk0pE8yT58+4OoKR46Yk/GLyH9UnBKRTBMbZc/BzZ4A+Kg4JTlQ/f67Afj164eJinC0NoyIiNzW/PnmfYMGUEJTBUomyZcPXn7Z3P7gA7SIishNVJwSkUxzeGtJoq86UdAjglJVz1kdRyTd+TQ5ilvZi1y75MK2BT5WxxERkdv45hvzvls3a3NI7jNwIOTNC7t3w7p1VqcRyTpUnBKRTJMw35RPo+PYbNZmEckIdnZQ7/ndAPz0hS/x8dbmERGR5P7807w5OkKHDlankdzG1RWef97c/uADa7OIZCUqTolIpkmcbyrgqLVBRDLQo1334lIgirOHinJgg5fVcURE5Bbz5pn3LVpAkSLWZpHcaehQcHCAjRvh9x92wLF5cGYTxMdZHU3EMipOiUimOHekEOf+KYKdQxwV64daHUckw7gUiOGxp/cC8PPMqhanERGRmxmGhvSJ9Tw94em2xwEYF3gUtnaDHxvCcm8IXWJtOBGLqDglIpkiYUhfudqncCkYbW0YkQxWp9efAOxd683Fk/ktTiMiIgmCg+H4ccifH1q1sjqN5FqhSxhWw/wGXLq9HUfPepv7I0/Clo4qUEmupOKUiGSKfTeKUw810ZA+yfncK/xLubonMOLt+HXOw1bHERGRGxJ6TbVrZ05KLZLp4uNgxyAqe/5Fk8priTfs+WztizcevLF8347BGuInuY6D1QFEJOeLuurAP7+UAsCnyTFrw4hkkjrP/MXhX0rx69cP0+SV362OIyKS68XEwMKF5raG9ElGCgkJITw8PMXH8l/dToXIEwAMaf4x6/4KYPqmvrzd4W0K5IkADIgM5eAvM4jIVyPFc7i5uVG6dOmMii9iCRWnRCTDHdriSWyUA0VLX8K9wr9WxxHJFFVb/UO+ote4eKoA+3/0pqBHiNWRRERytR9/hHPnoFgxaNTI6jSSU4WEhFDJpxLXIq+l+HiX2jDvRkepplXXULH4fg6crsSszb15udmnie0CX+/H/OCUnyNP3jzs37dfBSrJUVScEpEMlzDf1EMBx7DZrM0iklkcXeKo2WUfmyY/wtbZlWk2/CerI4mI5GoJQ/o6dQJHR2uzSM4VHh7OtchrdP+8O+4V3JM9Xi4qFM6bXfjs7AwGNwvihVlTmbhmEAMDJmFvFw9AvcBOlHT2THb8mYNnmNNvDuHh4SpOSY6iOadEJEMZBuxdWwaAhzSkT3KZ2s/cmBh9nTeXzxayOI3kNpMnT6ZMmTK4uLjg5+fHli1b7th+8+bN+Pn54eLiQtmyZZk6dWqyNkFBQVSsWJE8efLg6enJkCFDuH79eka9BJF0ExkJS5ea2xrSJ5nBvYI7nr6eyW4xNWtxxaVwwuxS9PT/iiL5LnDkbDm+39kaA7jiUpiYmrVSPD6lgpdITqDilIhkqLB9rlw8WQBHl1gerHvC6jgimcq9/MXEidH/WvWY1XEkF1mwYAGDBw9m5MiR7Nq1C39/f5o3b05ISMrDS48ePUqLFi3w9/dn165dvPHGG7z88sssXrw4sc3cuXMZPnw4gYGB7Nu3jxkzZrBgwQJGjBiRWS9LJM1WrICICPD2htq1rU4juZlhs2OzTztzG8jrfI1+T3wOQNDqwQBs9mmHYdOf6pK76DteRDLU3vXeAJT3D8Upb6y1YUQsUKeX2Xvqz5WPov92JbNMmDCBPn360LdvX3x8fAgKCsLT05MpU6ak2H7q1KmULl2aoKAgfHx86Nu3L88++yzjx49PbBMcHEzdunXp1q0b3t7eBAQE0LVrV7Zv355ZL0skzRKG9HXtiqYYEMsd9vBlZfXeRLgUBmBgk0k42MeweV8DPnEO5LCHr7UBRSygq2QRyVB713oDWqVPci/fVofJW+QaEeGFgcZWx5FcIDo6mh07dhAQEJBkf0BAAFu3bk3xmODg4GTtmzZtyvbt24mJiQHg8ccfZ8eOHfz+u7n65JEjR1i1ahUtW7ZM8ZxRUVFcvnw5yU3ECv/+C6tWmdtdu1qbRSTBYQ9fZjV4i0WPDuTPJ57gseZ7AJi7qJPFyUSsoeKUiGSYyEtOHP2tBKD5piT3cnCO45EOB2989YylWSR3CA8PJy4uDnf3pPOSuLu7ExYWluIxYWFhKbaPjY1NXA69S5cuvPvuuzz++OM4OjpSrlw5GjZsyPDhw1M859ixYylUqFDizdMz+cS+Iplh8WKIiYHKlaFKFavTiPzHsNlx0rU8B0v48djgfwDYubgil8/ktTiZSOZTcUpEMszBjaWJj7PDvcJ5XL30ibnkXo922Xdjqx1Xrui/XskctlvGLhmGkWzf3drfvH/Tpk28//77TJ48mZ07d7JkyRJWrFjBu+++m+L5RowYwaVLlxJvoaGh9/NyRNJs3jzzXhOhS1ZW+pEzeNc8RVyMPb9+/bDVcUQyna6QRSTD/L1Oq/SJAHhWP0NRrzNAHtavL2J1HMnh3NzcsLe3T9ZL6uzZs8l6RyXw8PBIsb2DgwOurq4AvPnmm/To0YO+fftSpUoV2rVrx5gxYxg7dizx8fHJzuns7EzBggWT3EQy28mTsHGjud2li7VZRO7m8b5/APDLrCrExWpyNMldVJwSkQxhxNvYd2My9IcCjlmaRcRqNhs83NScNHrFCleL00hO5+TkhJ+fH+vWrUuyf926ddSpUyfFY2rXrp2s/dq1a6lRowaOjo4AREZGYmeX9NLR3t4ewzASe1mJZDXffAOGAXXrQpkyVqcRubNqbf4hv1skl04X4K9V5ayOI5KpVJwSkQxx5lBJIs7lxTl/FGUeO2V1HBHL+TTeAcSxe3d+/vnH6jSS0w0dOpTp06czc+ZM9u3bx5AhQwgJCaF///6AOeSuZ8+eie379+/P8ePHGTp0KPv27WPmzJnMmDGDYcOGJbZp3bo1U6ZMYf78+Rw9epR169bx5ptv0qZNG+zt7TP9NYrcjWHAV1+Z2zd9u4tkWQ7OcdR+5i8Afp5R1eI0IpnLweoAIpIzHfnVB4CKDUJxcEo+3EMktylQ7DKwHmjKV1/B6NFWJ5KcrHPnzpw/f57Ro0dz+vRpKleuzKpVq/Dy8gLg9OnThISEJLYvU6YMq1atYsiQIUyaNIkSJUrwySef0KFDh8Q2o0aNwmazMWrUKE6ePEmxYsVo3bo177//fqa/PpF7sWcP/PUXODnBU09ZnUbk3tR55k/Wf1yDQ1s8Ob2vKMV9LlgdSSRTqDglIhni6I3ilOabErnZbBKKU2+/DXbqvywZaMCAAQwYMCDFx2bPnp1sX/369dm5c+dtz+fg4EBgYCCBgYHpFVEkQyX0mmrTBopouj/JJoqUiqBKiyP8seJBfplZlY4fbbI6kkim0GWxiGSA4oTtLw3AQwFHLc4ikpUsI1++OI4fh59+sjqLiEjOFRtrzjcF0KOHtVlEUuvxvnsA2LbAh+uXnSxOI5I5VJwSkQzQEgAvv9MUdI+0OItIVnKdJk3+BWDOHIujiIjkYOvXw5kz4OYGzZpZnUYkdcr7n8C9wnmiIpzYtqCS1XFEMoWKUyKSAdoAULm5ek2J3KpZM3PuiMWLISrK4jAiIjlUwpC+Ll3MOadEshObDR7v8wdgToyuBVElN1BxSkTS1bVrdkBjACo3O2JtGJEs6JFHIiheHC5ehDVrrE4jIpLzXL4My5aZ21qlT7Krmp3345w/mjMHXTm0pZTVcUQynIpTIpKufvutAJCHQsXP4+Fz3uo4IlmOvT107mxuz5tnbRYRkZxo8WK4dg0qVoQaNaxOI5I2LgWjqdl5HwA/T/e1OI1IxlNxSkTS1U8/FQKgbO292GwWhxHJorp2Ne+/+w4iIqzNIiKS03z9tXnfsye6FpFsre6z5tC+P1eV5d8T+S1OI5KxVJwSkXQTF/dfcapcnb8tTiOSddWsCeXKmZ/sL19udRoRkZwjJAQ2bTK3n37a0igi9624zwXK+4dixNsR/GVlq+OIZCgVp0Qk3fz+O/z7ryNwkVK+mm9K5HZsNnOSXtDQPhGR9DR3LhgGNGgAXl5WpxG5fwm9p4K/rkxstP58l5xL390ikm7+6wHyA/YO8VZGEcnyEob2rVkDFy5Ym0VEJCcwjP+G9PXoYW0WkfRSpcURChWP4MrZfPzx/YNWxxHJMGkqTk2ePJkyZcrg4uKCn58fW7ZsuWP7zZs34+fnh4uLC2XLlmXq1KnJ2ly8eJGBAwdSvHhxXFxc8PHxYdWqVWmJJyIW+f77hC2NUxK5m4cfhipVICbGnLxXRETuz44dsG8fuLhAx45WpxFJH/aO8dTu+RcAP8+sanEakYyT6uLUggULGDx4MCNHjmTXrl34+/vTvHlzQkJCUmx/9OhRWrRogb+/P7t27eKNN97g5ZdfZvFNV+LR0dE0adKEY8eOsWjRIg4cOMC0adMoWbJk2l+ZiGSqw4fh77/B3t4AVlsdRyRbSOg9paF9IiL3IT4Ozmxi9icHAWj7ZDwFC1qcSSQd1e75F3b28RwJLsm5Ix5WxxHJEKkuTk2YMIE+ffrQt29ffHx8CAoKwtPTkylTpqTYfurUqZQuXZqgoCB8fHzo27cvzz77LOPHj09sM3PmTC5cuMCyZcuoW7cuXl5ePP744/j63n7JzKioKC5fvpzkJiLWWbrUvH/kkSvARSujiGQbCfNObdoEYWGWRhERyZ5Cl8Byb67/0IxvlrgB8Gyl7uZ+kRyiUPGrVGl5GIA939WxOI1IxkhVcSo6OpodO3YQEBCQZH9AQABbt25N8Zjg4OBk7Zs2bcr27duJiYkBYPny5dSuXZuBAwfi7u5O5cqVGTNmDHFxcbfNMnbsWAoVKpR48/T0TM1LEZF0ltAZ8oknLlqaQyQ7KVPGXLnPMGDZMqvTiIhkM6FLYEtHiDzBdzue5N+rRfF0DeGJBxea+1Wgkhzk8b57ANi71g8oYG0YkQyQquJUeHg4cXFxuLu7J9nv7u5O2G0+8g0LC0uxfWxsLOHh4QAcOXKERYsWERcXx6pVqxg1ahT/+9//eP/992+bZcSIEVy6dCnxFhoampqXIiLp6MQJ+PVXc7thw0vWhhHJZhLmRVm0yNocIiLZSnwc7BgEGADM+qk3AL3qzcbe7sYH3DsGm+1EcoAH657EvcJ5Yq47A5rxX3Ieh7QcZLPZknxtGEayfXdrf/P++Ph4HnjgAb744gvs7e3x8/Pj1KlTfPTRR7z11lspntPZ2RlnZ+e0xBe5d/FxcG4LXDsNeYpDMX+ws7c6VZaTMKSvTh0oVizG2jAi2UyHDvD66+bQvvBwcHOzOpGISNYQEhKS+GH2rfJf3U6FyBMAhJ4vxdo/zZEaverNvtHCgMhQDv4yg4h8NVI8h5ubG6VLl07v2CIZwmaDx/v8weLXGwIDMIwoqyOJpKtUFafc3Nywt7dP1kvq7NmzyXpHJfDw8EixvYODA66urgAUL14cR0dH7O3/+6Pfx8eHsLAwoqOjcXJySk1MkfQRusT8RO7GhQ8AeUuB30TwbG9drixoyY1e8x06WJtDJDsqVw6qVYPdu+G776BPH6sTiYhYLyQkhEo+lbgWeS3Fx7vUhnkvmttf/vQMhmFHA5+NlH3gaJJ2ga/3Y35wys+RJ28e9u/brwKVZBs1Ou9neWAdYq4/zI4dB/HzszqRSPpJVXHKyckJPz8/1q1bR7t27RL3r1u3jieffDLFY2rXrs33/60vD8DatWupUaMGjo6OANStW5dvvvmG+Ph47OzMkYYHDx6kePHiKkyJNRLmMLjRVTxR5EnY0pEjpVex6WAz/vgD/vkHzpyByEizSeHCULw4PPQQPPIINGhg7supzp2Dn34yt9u3hwsXrM0jkh117GgWpxYtUnFKRATM6USuRV6j++fdca+Q/EPwclGhcH4h8fG2xCF9vevPStauXmAnSjonn5v2zMEzzOk3h/DwcBWnJNvIUzCahwJ2sGd5Hb79thjPP291IpH0k+phfUOHDqVHjx7UqFGD2rVr88UXXxASEkL//v0Bcy6okydP8tVXXwHQv39/PvvsM4YOHcpzzz1HcHAwM2bMYN5N62a/8MILfPrppwwaNIiXXnqJQ4cOMWbMGF5++eV0epkiqXDLHAYJ9p7wYcamPny/qzWHwirc9TQJE4Tb2YG/P/ToAZ07Q/78GZDZQsuWQXw8+PmBt7eKUyJp0bEjjBoF69fDv/9CkSJWJxIRyRrcK7jj6Zu8uBRjlOTKprXs2FWVI2fLUcDlMh1qLk583AAiXAoTU7MWnrZUL1AukmX5tglmz/I6bNxYmFOnoEQJqxOJpI9UF6c6d+7M+fPnGT16NKdPn6Zy5cqsWrUKLy8vAE6fPk1ISEhi+zJlyrBq1SqGDBnCpEmTKFGiBJ988gkdbhr/4+npydq1axkyZAhVq1alZMmSDBo0iNdffz0dXqJIym43j8HNcxgYBizf0YaPVw9h874GiW0c7GOoXvkcFSrb4+19HTe3WPLkicMwbFy5Yk9ERBFOnCjC1q2wfz9s3mzehg2DF1+EoUNzzh+fCUU4DekTSbuKFeHhh+Hvv+H776FnT6sTiYhkbYbNjs0+7VgUVA+AzrUWkM/F7Mae8PHiZp92GCpMSQ5TrNxpYAtxcf5Mnw63maJZJNtJ04ToAwYMYMCAASk+Nnv27GT76tevz86dO+94ztq1a/NrwnJfIhnsTvMYJMxhsGlvfYbP/4DfDtcCwM4WRxu/5fR4/GsaP7yefjOvMHduyue/eQ6D48dh3jyYMcMcAvjeezB5MgQGwsCBYJ+N51cPD4cffzS3VZwSuT8dO5rFqUWLVJwSEbkXf+etyfztXQF4tsHMxP0RLoXZ7NOOwx6+VkUTyWCTAX8+/xxGjIAbs+WIZGtpKk6JZHd3msegWNhlOgc1YuFvnQHI63yVlwM+YWCTSZRyPZnY7l7nMPDyguHD4dVXzcmOAwPhr79g0CCYOxdmzTLnp8qOFi2C2Fhzbq0Kdx/pKCJ30LEjvPMOrFkDly9DwYJWJxIRydp2LStP1DVnHnjwAie6+fFDdHmuOhfkVNFy6jElOdxiihaN4dQpR5Yv14fEkjOoOCW52s3zGBgGbF9YiSkj6hN50QV7u1j6PfE5b7Z7F4/CZxKPSescBvb25oThbdrA9Olmwer336FGDZg2DZ5+Or1fXcb75hvzvls3a3OI5AQPP2wWeQ8ehBUr9HMlInI3v39jfrr3WPe9nHIrb3EakcwUQ7t24cyYUZzJk1WckpxBHymIANevODKnX1PmvtCUyIsulPU5zm+jH+Wz3i8mK0zB/c1h4OAA/fubw3cCAuDaNejeHQYPhpiY+38tmSUkBLZsAZvNnOhdRO6PzfbfxeXSpdZmERHJ6s4cLMLR30tgZx9PjU77rI4jkunatQvHzg42bIB9+hGQHEDFKcn1Tu115X+NurJjUSXs7ONpMXIrAzct53T7akS4FE7SNsKlMCur906XOQxKloRVq8wVugAmToRWrSAyIg7ObIJj88z7+Lj7fq6MMH++eV+vHpQqZW0WkZyibVvzfvVqiIqyNIqISJb2+zyz15RP42MU8oi0OI1I5itePIbWrc3tKVOszSKSHjSsT3K1w8E+/DCmE1ERThQucYWe03+gbK3T5mMevhxxr0KJC4fJF3U5Q+YwsLeHd981h/Z16wZr10LTR3ewYuiTFMp72WyUtxT4TQTP9un2vOlh3jzzXkOPRNJPjRpQvDicPm1+Etq8udWJRESynthoO35LGNL39F6L04hYZ+BAc07bL7+EMWMgf36rE4mknXpOSa5kGACDWTayN1ERTpSvF8qwzd8kFqYS29nsOOlanoMl/DjpWj7DJtd88klYN2cThfJe5Od9j/LE+xu4EFHEfDDyJGzpCKFLMuS502LvXti921wZRGPcRdKPnZ05Lx2YF5siIpLcXz+UJeJcXgq6X+XhpketjiNimUaNoHx5cyGVhLlgRbIrFack1zEMCAoqCXwMhh21n/mT/t8uI7/rdetCxcdRx9aDTSMbUKzgWXYe86P1+O+JjMpD4kxXOwZnmSF+c+ea982agaurtVlEcpqEoX3Ll0N8vKVRRESypK2zqwDwWPe/sXfUL0rJvezs4IUXzO1JkxI+gBfJnjSsT3KVuDjzF/icOe4A1Ov/Pe3eP4LNljnPHxISQnh4eLL9+a9up0LkCap5n2DDG0/gP3oLWw/VpfOnC1gyuD2ODrEQGcrBX2YQka9Giud2c3OjdOnSGf0SiI2F2bPN7e7dM/zpRHKdhg2hQAFzaN/27fDoo1YnEhHJOsKPFuLg5tLYbAa1evxldRwRy/XqBSNHwh9/wNatULeu1YlE0kbFKck1YmLgmWfMuZLs7Azi4/tQs3NRbDbPTHn+kJAQKvlU4lrktWSPdakN8140tyt7/s33w1rTZOw6VuxqTf+ZU5n+XF9sNgh8vR/zg1M+f568edi/b3+GF6h++AFOnQI3N3M4ooikL2dns1fit9+aQ/tUnBIR+U/w1w8DUPGJ47iWvmJxGhHrFSlizgE7YwZMnqzilGRfKk5JrhATA506wbJl4OAA7757lBEjZgGvZFqG8PBwrkVeo/vn3XGv4J7ksXJRoXB+YeLXj1f8hQUvdabdx0uZubkPVTz/ZHDzidQL7ERJ5+TFtDMHzzCn3xzCw8MzvDg1fbp5/8wz5h/RIpL+nnzSLE4tWwbvv291GhGRrCE22o7f5prFqTrPqNeUSIIBA8zi1LffwscfwwMPWJ1IJPU055TkeHFx0LOn+Uees7PZEyEg4KJledwruOPp65nkFlOzFldcCnPzMPE2ft/zv6fN4tmwb8bz/cE2xNSslexYT1/PZMWujHLqFKxcaW736ZMpTymSK7VoYa7muXcv/POP1WlERLIGTYQukrJHHoHHHjM/kJ8xw+o0Immj4pTkaPHx8PzzMH++ubLckiXmH31ZjWGzY7NPO3P7pv2Dmk2kp/+XxMU78HTQXMJDCluSL8Hs2Waxr25d8PGxNIpIjlakCNSvb25r1T4REZMmQhe5vQEDzPupU83rdZHsRsUpybEMAwYPhpkzzZUs5s3LmoWpBIc9fFlZvTcRLoUT99ls8NELw3mw8lGuXMrPjO6tiIpwtCRffPx/n8Q895wlEURylYQ53VScEhHRROgid9Opk7mKdkjIfyMdRLITFackx3r3Xfj0U7PAM3s2dOhgdaK7O+zhy6wGb7Ho0YH84NuDRY8OZH7T1+g+bwMFHrjKqb+LMX9QI0uWiV27Fo4cgYIFoWPHzH9+kdwmoTj1yy9w/ry1WSR7mjx5MmXKlMHFxQU/Pz+2bNlyx/abN2/Gz88PFxcXypYty9SpU5O1uXjxIgMHDqR48eK4uLjg4+PDqlWrMuoliCTSROgid+bi8t+0G5MnW5tFJC1UnJIc6csvITDQ3J40CXr0sDZPahg2O066ludgCT9OupbHsNlRuGQEvWevws4hjl1LK7JpUvVMz/Xxx+Z9796QL1+mP71IruPlBVWqmL0WV6+2Oo1kNwsWLGDw4MGMHDmSXbt24e/vT/PmzQkJCUmx/dGjR2nRogX+/v7s2rWLN954g5dffpnFixcntomOjqZJkyYcO3aMRYsWceDAAaZNm0bJkiUz62VJLqWJ0EXuTb9+5gfza9ZozkrJflSckhznxx+hb19ze/hweOEFa/Okl7K1TtFuzE8ALH/7cQ7+VCrTnvvvv82eU3Z28PLLmfa0Irley5bmvTqmSGpNmDCBPn360LdvX3x8fAgKCsLT05MpU6ak2H7q1KmULl2aoKAgfHx86Nu3L88++yzjx49PbDNz5kwuXLjAsmXLqFu3Ll5eXjz++OP4+vpm1suSXGrP9w+aE6F7RGgidJE7KFsWmjc3t2/z614ky1JxSnKUP/+E9u0hNha6ds15S7A/3ucPanbZixFvx5d9mvPviQKZ8rxBQeZ927bmf3oikjkS5slbvVqTm8q9i46OZseOHQQEBCTZHxAQwNatW1M8Jjg4OFn7pk2bsn37dmJiYgBYvnw5tWvXZuDAgbi7u1O5cmXGjBlD3G2+OaOiorh8+XKSm0ha/DzNLIDW6fWnJkIXuYuBA837WbMgMtLaLCKpoeKU5BgnT5p/yF2+DPXqmb+Q7XLYd7jNBk/9bwOlqp7l6vm8zHymJTHX7TP0OU+ehK+/NreHDMnQpxKRW9Suba7cd+EC/Pab1WkkuwgPDycuLg53d/ck+93d3QkLC0vxmLCwsBTbx8bGEh4eDsCRI0dYtGgRcXFxrFq1ilGjRvG///2P92/zSdDYsWMpVKhQ4s3T0zMdXp3kNmcOluTo7yWwd4zTkD6Re9C0KZQpA//+a65YLpJd5LA/3SW3ioyE1q3hxAmoVAmWLgVnZ6tTZQynPHH0/moF+YpeI3SXO4tebZihE6R/+CFERYG/P9Stm3HPIyLJOTiYF5mglXck9Ww2W5KvDcNItu9u7W/eHx8fzwMPPMAXX3yBn58fXbp0YeTIkbcdKjhixAguXbqUeAsNDb2flyO51O5ldQDwbfMPBd3VDUTkbuzt/5vWJCgISxZSEkkLFack2zMMePZZ2LULihUz52YpWtTqVBnLtfQVek7/AZtdPL/NfZg/vq+VIc9z8iR88YW5HRho9twSkcyVMLRP807JvXJzc8Pe3j5ZL6mzZ88m6x2VwMPDI8X2Dg4OuLq6AlC8eHEqVKiAvf1/PXZ9fHwICwsjOjo62TmdnZ0pWLBgkptI6hRl/4+PAOD/3G5ro4hkI889Zy5g9Oef5ny8ItmBilOS7X34ISxYYPYwWLTI7MaaG1RsEEqrt8y5QzZ82hZI/wLVmDFmr6nHH4cnnkj304vIPWjWzCwM795tFoxF7sbJyQk/Pz/WrVuXZP+6deuoU6dOisfUrl07Wfu1a9dSo0YNHB0dAahbty7//PMP8fH/zflz8OBBihcvjpOTUzq/ChGAZ4mNdqSU7xm8a6Y8JFVEkitc2PzwHmDCBEujiNwzFackW1u5Et54w9z+9FNzrqnc5ImXduDb5hDxsQ7AIs6dc0i3c//1F3z+ubk9erR6TYlYpVgxePRRc1u9p+ReDR06lOnTpzNz5kz27dvHkCFDCAkJoX///oA55K5nz56J7fv378/x48cZOnQo+/btY+bMmcyYMYNhw4YltnnhhRc4f/48gwYN4uDBg6xcuZIxY8YwMGH2XZF0ZM6zPwAA/75/6DpEJJUGDTKv33/4AfbtszqNyN2pOCXZ1v790K2bOayvXz+4cb2dq9hs0PXTdbh6hQElGTToQS5duv/zGob5H1pcHLRrBw0b3v85RSTtWrY071WcknvVuXNngoKCGD16NNWqVeOnn35i1apVeHl5AXD69GlCQkIS25cpU4ZVq1axadMmqlWrxrvvvssnn3xChw4dEtt4enqydu1atm3bRtWqVXn55ZcZNGgQw4cPz/TXJznfL78UAsrgUvAq1dsfsDqOSLZTrpy50jb8t/K2SFaWft0sRDJafByc2wLXTnMpphRPPvk4ly/b8PeHTz6xOpx1XArE0Pb9Wczo3psDBzxo29b8hMTFJZUnuun9XbimKhs2PIyzM/zvfxmRWkRSo2VLeOstWLc2jqgDi3Au7A7F/MEuY1frlOxtwIABDBgwIMXHZs+enWxf/fr12blz5x3PWbt2bX799df0iCdyRwsWFAOgSovfccoTZ3Eakexp6FBzoaivvoL33jN7Y4tkVeo5JdlD6BJY7g0/NsT4pRu9uoVz8KANzxKRLFoEuX2qi8IlzwPNyZcvjk2bzB5lMTGpOMFN72/o96/Rf2gJAIa/sC/XzOElkpVVc12CR5EzXI20Z8uX0+DHhubPbOgSq6OJiKS7Awfg118LAvH4PrnV6jgi2VbdulCzJly/DlOnWp1G5M5UnJKsL3QJbOkIkScA+N+qV1i2vR1ODlEs7t+AB6L0x5lpN//732GcnMxPSNq3h2vX7uGwm97f2Dh7ek75iouRRahZ9ndGVvfVH78iVgtdgt0vHWlRdQUAK3fdGOMXedL82dXPqIjkMP/1iF9BIY9/rYwikq3ZbDBkiLn92WdmkUokq1JxSrK2+DjYMQgwAPhpnz/D538AQFCPwdQstx12DDbbCTVrRrBsmTmkb8UKCAiAsDstbnPT+xsfb6PvtOls2teQfM4RfDOwG44OsXp/Rax0089oy+orAVi5+0Zx6sbvRf2MikhOcv48zJqV8NXHVkYRyRE6doRSpeDsWZg3z+o0IrenOafEciEhIYSHh6f4WP6r26lwo8dU2EV3On+2gLh4B56uO4f+jW70TY0M5eAvM4jIVyPFc7i5uVG6dOkMyZ4VNW8Oq1dDmzbw889QrVosb799hEcfjUjWNuH9jY2z56UvP+XLLb2wt4tl7oCnedDjsNnoDu9vbntvRTLCvf4ObPzwehztozkUVoFDYQ9S3uMfwNDvQBHJUT7/3Oz5XbFiJAcObAL8rI4kkq05OsLLL8Nrr8GECfDMM2CnLiqSBak4JZYKCQmhkk8lrkWmPP6sS22Y9yLExtnT5bP5hF0szsOl/uLzZ/slWVI48PV+zA9O+Tny5M3D/n37c9UfZ/Xrw++/Q6tWMfzzjyMvvFABmAd8COxJbNelNrzeypeXvvqUnw/4AzC7Xy+erLE8yflu9/7mxvdWJD3d6+9AgIJ5r+BfaQsb/m7ED7ubU77Zp4nt9DtQRHKCqCj49Mavtu7dz/Lmm9bmEckpnnsO3n0X/voLVq6E1q2tTiSSnIpTYqnw8HCuRV6j++fdca/gnuzxclGhcH4ho759j837GpDf5QqLB3Ugn0tkknb1AjtR0tkz2fFnDp5hTr85hIeH57o/zCpWhJkz/6ZevS3YbAMxjK5AV4p6ncHNOwwH5xh+PuzK/JHmjOf5nCOY1a83Tz22KNm5Unp/c/N7K5Je7vV3YIJmVVez4e9GrP0zgJdvKk7pd6CI5ATz5pnTEZQsCU2a/KvilEg6KVwYBgyADz+EMWOgVSuSfNAvkhWoOCVZgnsFdzx9k/9hFWOUZMFH9nz4/XAAZjzXh4olDiY+bgARLoWJqVkLT5v6p94qX7544GWenhrL36tb8MeKB7lw3J0Lx//7I9jOLo5Ojy3kg87D8SoWkuR4vb8imeNOvwOvbFpL/usXsQFNq67htXkfsXFfQ6JinHByjNbPqIjkCIZhDjkCeOklcHQ0rA0kksMMGQITJ8Kvv8Lmpbtp8Mg+yFMcivmDnb3V8URUnJKsLTykMG9Mmg7AS00n0qnWt4mPJVyybPZph6E/yu7IvcJJajy1mojzLhzf4cHZg0WIi7WnaOlLNKm4hqdDPkl2jN5fEesZNjs2+7Sj5a5ZGEAVzz9xLxTGmUse/HKwDg0f3qSfURHJEdavhz//hHz54Pnn4ehRqxOJ5Czu7tCn82EmfVmOMYFnaTCim/lA3lLgNxE821sbUHI9Xc1KlhUXa+Pr55ty9UpeKvr+Q2Dv95M8HuFSmJXVe3PYw9eihNlPftfrPBxwjIYv7qLx4O080v4Q5x8uy8rqvYlwKZykrd5fkazhsIdv4s+ozQYBVdYCsHJfG/2MikiO8b//mffPPgtFilibRSRHCl3Cq9Ub4WAfw7q/Ath2+MZCKpEnYUtHCF1ibT7J9dRzSrKstR89xrFtJXApEEWnL39irucISlw4TL6oy1x1LsipouXUWyCdHPbw5Yh7Fb2/IlnUzT+j7iGR8DMsPNyN0h7zrY4mInLfdu+GNWvMFcQGDbI6jUgOFB8HOwbhVewET9eZy5dbejF2+QiWDOmAOV7CBjsGQ8knNcRPLKPilGRJh4NLsPZ/NQF4asIGXEtfwcCOk67lLU6Wcxk2vb8iWVnCz2ihdvYwAk784c6Vc3koUCzllf5ERLKLDz4w7zt1gnLlrM0ikp2FhIQQHh6ebH/+q9upEHkCgNdbf8hXP/dk6fb2/H3iIR4utRcwIDKUg7/MICJfjRTP7ebmpsVVJEOpOCVZTuQlJ+b0a4oRb0eNzvvw63Dw7geJiOQSBR6IpGSVs5z88wEObi6NX8cDVkcSEUmzQ4fg2xtTig4fbm0WkewsJCSESj6VuBaZ/EOrLrVh3ovmtk/J/bSvsYTF2zoyeslbLHi5S2K7wNf7MT845fPnyZuH/fv2q0AlGUbFKclSDAO+feUJ/j1REFfvi3T8cJPVkUREspyKDUM4+ecD7N+g4pSIZG/jxkF8PLRsCb6aQk8kzcLDw7kWeY3un3fHvYJ7ksfKRYXC+YWJXwe2f4cl29uz8LfOvHF8DL5efwBQL7ATJZ2Trx585uAZ5vSbQ3h4uIpTkmFUnJIsZduCSuxaUhE7+3h6fLEal4LRVkcSEclyKj1xnA2f1ODARi8MA2w2qxOJiKTeyZPw5Zfm9ogR1mYRySncK7jj6Zu0wBRjlOTKprXkv34RG1Cl9F90qTWfecHdeGvRaJa90pYIl8LE1KyFp+acFYvoO0+yjPCjhVj8WkMAmr3+K941zlicSEQkayr72Gkc88Rw+Uw+Tu9ztTqOiEiaTJgAMTFQrx7UrWt1GpGcy7DZsdmnnbl9Y19g+3ews8WxfOeT/H64Jpt92mkxJLGUvvskS4iLtePr55sSFeFE2donaTxku9WRRESyLAfnOB6sexKA/T96WZxGRCT1zp+Hzz83t994w9osIrnBYQ9fVlbvTYRLYQAqljhIT/+vAOi/eiaHPTSuVqyl4pRkCcFfBnB8R3FcCkbR4/M12Nkbdz9IRCQXq/TEcQAObNTcDyKS/QQFwdWrUL06BARYnUYkdzjs4cusBm+x6NGB/ODbgxpvH8POIY7dWyvzzy8lrY4nuVyailOTJ0+mTJkyuLi44Ofnx5YtW+7YfvPmzfj5+eHi4kLZsmWZOnXqbdvOnz8fm81G27Zt0xJNsiV/fpv7BACdP/6RIqWuWJxHRCTrq9jQLE4dDi5J9DV7i9OIiNy78+fN4hTAqFGaN08kMxk2O066ludgCT9iqxWlVo+/AVj5Xh0M9Q8QC6W6OLVgwQIGDx7MyJEj2bVrF/7+/jRv3pyQkJAU2x89epQWLVrg7+/Prl27eOONN3j55ZdZvHhxsrbHjx9n2LBh+Pv7p/6VSLZ0+bI9MAcMOx7tupfq7Q5ZHUlEJFtwr/AvhUtcITbKgcNb9WmniGQf48dDRITZa6pdO6vTiORuAUO34egSy9HfSvDnynJWx5FcLNXFqQkTJtCnTx/69u2Lj48PQUFBeHp6MmXKlBTbT506ldKlSxMUFISPjw99+/bl2WefZfz48UnaxcXF8fTTT/POO+9QtmzZtL0ayVYMA8aMKQ2UpnCJcNp/sMnqSCIi2YbNdvPQPs07JSLZw9mz8Omn5vY776jXlIjVCpeMoOHAHQAsD3yc2Cj1xhZrpKo4FR0dzY4dOwi4ZWB4QEAAW7duTfGY4ODgZO2bNm3K9u3biYmJSdw3evRoihUrRp8+fe4pS1RUFJcvX05yk+zlyy9h3boiQAwtRs3FpUDMXY8REZH/VGxo9lrWvFMikl189JE511SNGtCqldVpRASg0aAdFHS/SvjRwmyZXtXqOJJLpao4FR4eTlxcHO7u7kn2u7u7ExYWluIxYWFhKbaPjY0lPDwcgF9++YUZM2Ywbdq0e84yduxYChUqlHjz9PRMzUsRi/3zD7z4YsJXgRT3CbUyjohItlS+nvm78/Q+N66czWtxGhGROwsLg0mTzO3Ro9VrSiSrcM4fQ4uRZmeTNR89RsR5F4sTSW6UpgnRbbf8T2IYRrJ9d2ufsP/KlSt0796dadOm4ebmds8ZRowYwaVLlxJvoaEqbmQXMTHQrZv5qZmf3xXgQ6sjiYhkS/ldr1OyylkADm0pZXEaEZE7+/BDuHYNatWCZs2sTiMiN3u06z5KVD7H9cvOrPnoMavjSC6UquKUm5sb9vb2yXpJnT17NlnvqAQeHh4ptndwcMDV1ZXDhw9z7NgxWrdujYODAw4ODnz11VcsX74cBwcHDh8+nOJ5nZ2dKViwYJKbZA+BgbBtGxQuDKNHHwPiLU4kIpJ9lfc/AcDBn9SDWESyruPHIWGKWvWaEsl67OwN2r73EwC/zKhK2IEiFieS3CZVxSknJyf8/PxYt25dkv3r1q2jTp06KR5Tu3btZO3Xrl1LjRo1cHR0pFKlSvz555/s3r078damTRsaNmzI7t27NVwvh9m0CT74wNyeNg08PDTPlIjI/ahQ3+w5fEjFKRHJwkaOhKgoaNgQGjf+f3t3HlZF3b9x/M2O4i4JoqJorplLYIWKZpmmLeaSW2LlkmTmVv5cy7LUMvOhHkNTMTOTrDTTspRMcC0Tl3pcy1QQRcMdIUCY3x+jJIELBgycc7+u61wMc+acc4/gnA+fM/P9Wp1GRHJTp9VRGnY4SGaGI0tHt+HyBU8ihSLPl/WNHDmSefPmMX/+fPbu3cuIESOIjY0lJCQEMC+369u3b9b2ISEhHDlyhJEjR7J3717mz59PeHg4L730EgDu7u40bNgw261cuXKULl2ahg0b4urqmk+7KlY7fRqCg81Z+vr1g27drE4kIlL81bw3HkfnDE4dKcupIzqLWESKnpgY+OQTc/ntt3XWlEhR1nnKelzcL/Hb+mps+6ye1XHEjuS5OdWjRw9CQ0OZNGkSTZo0Yf369axatYrq1c1prI8fP05sbGzW9n5+fqxatYqoqCiaNGnC66+/znvvvUfXrl3zby+kyDMMGDQIjh6F2rXh3XetTiQiYhvcS6dT/a4TgM6eEpGixzBg1Chz+cknwd/f2jwicn0Vq5+n3aifAPjq5SAunnGzOJHYC+dbedDgwYMZPHhwrvctWLAgx7rWrVuzffv2m37+3J5DircPP4QvvgBnZ/OTs1KlrE4kImI7areK49BWHw6sr8a9wbutjiMikmXVKli3DtzcYPJkq9OIyM1o8/x2Yj6rR8L+inz9WguaP/O71ZHEDtzSbH0iefHbbzB0qLn8+uvQrJm1eUREbE3WuFMbqmp8CBEpMi5dgv/7P3N56FC4fKGFiBRxzq6ZPDHjBwC2LLyT+F9rWBtI7IKaU1Kg0tKgd2+4eNEcAPPKad0iIpJ/agQk4FIinQsnPUjYV8HqOCIiAISHw549UKECjBtndRoRyYtagce450nzbOzIGd0AjQUtBUvNKSlQr7wC27ZB+fKwcCE4OVmdSETE9ji7ZVDznmMAHNC4UyJipcwMOBHFqR1LGTfWnJX5lVegXDlrY4lI3j322kZKeSZz6rA38KrVccTGqTklBWbdOpg2zVyeNw+qVrU2j4iILat95dI+NadExCpxy2BFDVjbhgmjTnL6jAsNfffx/GNfWp1MRG6BR4W/6H758j74P379taSlecS2qTklBeLUKQgONmdoGTAAunSxOpGIiG2rE3QUgN83ViXjkuZpF5FCFrcMNnSD5KPEHLqLD34YBMDMviE4b+lq3i8ixU6jRw5S/8EYwImJE2uQnGx1IrFVak5JvjMMePZZiI+HOnUgNNTqRCIitq9q45OUKPsXf11w4+iuSlbHkSIgLCwMPz8/3N3d8ff3Z8OGDdfdPjo6Gn9/f9zd3alZsyazZ8++5raffvopDg4OPP744/mcWoqlzAyIGQYYZGY6MGTBTAzDkV6Bi2ldP9rcJma4uZ2IFDv3v7AciOfIEfesSQ5E8puz1QHE9oSHw7Jl4OICixeDh4fViUREbJ+jk8HtLY/y6ze3c2B9Nar7n7A6klhoyZIlDB8+nLCwMFq0aMEHH3xAhw4d2LNnD76+vjm2P3ToEB07dmTgwIEsWrSITZs2MXjwYG677Ta6du2abdsjR47w0ksvERQUVFi7I0VAbGwsiYmJud5X6uI26iSbZ2/OXhvCj78HUsr9Am/3vjITjgHJcRzYFE6SR0COx3t6eub6eykiRYN76RSgH7Ca99+HBx6Azp2tTiW2Rs0pyVf798OwYeby5Mng729tHhERe1I7yGxO/ba+Gg+O2GZ1HLHQjBkz6N+/PwMGDAAgNDSU1atXM2vWLKZOnZpj+9mzZ+Pr60vo5dOd69evz7Zt25g+fXq25lRGRgZPPvkkr732Ghs2bODs2bOFsTtisdjYWOrVr0dKckqu9/cMhIghEHeqKmM+fROAKd3HUaXCsWzbTRw9iE+35Hx8iZIl2Ld3nxpUIkXaGoKDT/Dxx1706wd33QXVq1udSWyJmlOSb9LSoHdvSE42u+kvvmh1IhER+1KnlTko+qGffEj/S9Oj2qu0tDRiYmIYM2ZMtvXt2rVj8+bNuT5my5YttGvXLtu69u3bEx4eTnp6Oi4uLgBMmjSJ2267jf79+9/wMsHU1FRSU1Ozvj9//vyt7I4UAYmJiaQkp9Dngz541fHKcX+t1DiMxM8Y/GEYF/4qQ2DtzQx+MCzHdq0mdqeKW/ZJG04cOMGiQYtITExUc0qkiHv++WPs3+/F1q3m331RUebVMiL5Qc0pyTcTJsD27VChAnz0EThqRDMRkULlVfc0Zbwucv6EB4e3eeNe+rDVkcQCiYmJZGRk4OWVvYng5eVFQkJCro9JSEjIdftLly6RmJhI5cqV2bRpE+Hh4ezcufOmckydOpXXXnvtlvZBiiavOl5Ua5xzRtB0owoL3ijF1zsexdU5lXkDBuDkmJl1vwEkuZcjvdm9VHNQgShSXLm4GEREQNOmsHkzvPQSvPuu1anEVujdQfLF2rXw9tvmcng4VKlibR4REXvk4AC1WpjjvhzcVNXiNGI1B4fsszYahpFj3Y22v7L+woUL9OnTh7lz5+Lp6XlTrz927FjOnTuXdYuLi8vjHkhxcTahNMPmm3+hjus0mQZV92bdZ1z+Gl2/M4YaUyLFXs2asHChufzee+ZJCSL5QWdOya3JzIA/N0DKcU6lVKNv3xaAA88+C5q4R0TEOre3iGfHsrr8vqkKdzxkdRqxgqenJ05OTjnOkjp58mSOs6Ou8Pb2znV7Z2dnKlasyO7duzl8+DCPPvpo1v2ZmeaZMc7Ozuzfv59atWple7ybmxtubm75sUtShBkGRLzQlgvnSlGrwWGGPDEbrpqUL8m9HNH1O3PQu7F1IUUkX3XqBK+8ApMmwaBB0KABNGtmdSop7tSckryLW2ZOF5x8FMOAAaHLOHbMgbq1LjBjRmmr04mI2LXbL585dWRbZS6l6W3eHrm6uuLv709kZCSdr5pOKTIykk6dOuX6mMDAQFauXJlt3Zo1awgICMDFxYV69erx66+/Zrt/woQJXLhwgXfffZdq1XJe6iX2YeO8Ruz7oQYu7pd4Inw9n9QZi8/pg3iknueiWxmOVailM6ZEbNDEibBjB6xcaTarfvwRNGyc/BuqWiVv4pbBhm5cOUl77rqBLN/WGRenNCL6tcbj9ATw6GJtRhERO1ap9hlKV7rIhZMeJOxVlWivRo4cSXBwMAEBAQQGBjJnzhxiY2MJCQkBzEvu4uPjWXj52oyQkBBmzpzJyJEjGThwIFu2bCE8PJyIiAgA3N3dadiwYbbXKFeuHECO9WI/EvZVYMXEIAAee20D3nXPYOBIfMXaFicTkYLm6AgffwwtWsDu3dChA2zcCOXLW51Miit9jCE3LzPDPGPqcmNq37G6DP84FICpPcbStMZOiBlubiciIpZwcIBazeMBiNtV0+I0YpUePXoQGhrKpEmTaNKkCevXr2fVqlVUvzzv9/Hjx4mNjc3a3s/Pj1WrVhEVFUWTJk14/fXXee+99+jatatVuyBFXOpFZz58uiPpfzlTt80RWvT/xepIIlLIypaFb78FHx/Ys8cc3uWqSVpF8kRnTkk2sbGxJCYm5npfqYvbqJNsXi6Smu5Kr5kRpKSV5MGGaxjR4T+AAclxHNgUTpJHQK7P4enpqWmCRUQK2O0tj7JzeR2O7qx1443FZg0ePJjBgwfnet+CBQtyrGvdujXbt2+/6efP7TnEPhgGfP7S/Zw4UJEy3kn0mbVGszSL2Klq1cwGVcuWsH49dO8On38Orq5WJ5PiRs0pyRIbG0u9+vVISU7J9f6egRAxxFwe/9lkdh5pSsVSiSwIeRpHRyNru4mjB/Hpltxfo0TJEuzbu08NKhGRAnT75TOnju2pDqg6FJH89ePHd7BtSX0cnTJ5at63lK6UbHUkEbFQo0awfDl07AgrVkDv3vDpp+CsboPkgX5dJEtiYiIpySn0+aAPXnVyzuZTKzUOTn1G5K9teWfVSwDMf7YfPuWPZ9uu1cTuVHHLOTDqiQMnWDRoEYmJiWpOiYgUIK+6pynlmUxSYklA0+eISP45vM2LpaPvA6DjhM3Uan7M2kAiUiTcfz98+aV5ad/SpRAcDAsXgouL1cmkuFBzSnLwquNFtcY5m0vpRhUOr9jGU7M/AuC5tmE85v/3zD4G5nTB6c3upZpmZRERscyVcad2ragNtLY6jojYiAt/luXTFx7lUqozDTse5P4XYqyOJCJFSIcO5iV9XbuaZ04lJcGSJVDSPQP+3AApx6FEZbgtCBydrI4rRYw6CHLTMnGk58IvOH7Wh/o+e5je+6Ws+65c1Bddv7OmCxYRKQJub3n08tJ9VsYQEZvhzlcTnub8CQ8q10+kz6zVGmdKRHJ47DHzDCp3d/j6a2h/XyJnIxrB2jawubf5dUUNcxZ4kavoLUVu2uYFd/LTuqY4u6Qz78VBlHT7e2yqJPdyfNP0GQ56N7YwoYiIXHFl3CloTnq6g6VZRKR4y8gA+JgTB6rhUSGFAYtX4l463epYIlJEPfIIREZC2TJpbPzZk8D/+4IDx2v/vUFyPGzopgaVZKPL+uSmJOyrwPIJQQA8MnEL257uwrHTjfFIPc9FtzIcq1BLZ0yJiBQhXvVOUaJsEinnSrFnT0nuucfqRCJSHBkGTJtWDbgLJ5dLPPPRN1Ssft7qWCJSxLVsnsH61x6m46QP2XesPne/spVPh/TkocarMa+7cYCY4VClky7xE0DNKbkJ6X85sXDgQ6SnuFC3zRFahezAcHAkvmLtGz9YREQs4egIVRv9wW8bGhETU4pnnrE6kYgUR2+8AV98cRuQSYexEdze4rTVkUSkCImNjSUxMTHH+lIXt9Go0vdseyOArqFL2fxbCx5++xvGdZrCK50n4eJ8CZLjOLApnCSPgFyf29PTUxNp2RE1p+SGVr7agmO7b6OUZzJPhq3R+AIiIsVE1SYHLzenSlsdRUSKoTlz4JVXrnw3lLpt3IGck+aIiH2KjY2lXv16pCSn5LivZyBEDAHvcif4Yfz9DF34HnN+GMQby19mza/tWDS4D7W9f2fi6EF8uiX35y9RsgT79u5Tg8pOqDkl17V7TQ3Wz2kKQO/3IynjlWxxIhERuVnVGv8BwK5dHqSnazpnEbl5H38Mzz1nLvfvf5zw8PeBFy3NJCJFS2JiIinJKfT5oA9edbyy3VcrNQ5OfQaAm0saH/QP4YE71jIo/AO2HryHxmN38UrnSbQYH0sVD58cz33iwAkWDVpEYmKimlN2Qs0puaZzCSWJGPIgAK0G7aDBg4etDSQiInni6ZcAnCIlpSIxMXDvvVYnEpHiYMEC6NfPHG8qJAQGDDhOeLjVqUSkqPKq40W1xtnPqkw3qnAhag2l/jrLlWlZut/7OYG1t/DMBx+ydndbxi55E+9diXR5M5o6rY7mfGKxK7pAS3KVmQmLn29HUmJJfBr+yWOvbrI6koiI5JGDowGsByAqytIoIlJMzJ//d2Pquefg/ffBQRN+ikgeGQ6ORNfvbC5ftb5axaOsGfsgH4UEU6b8BRL2eRL2eFdmdX2co7/cZk1YKRLUnJJcRYc1Zf+66riUSKfv3G9xdsuwOpKIiNySaAA2bLA4hogUebNmQf/+ZmPq+efNxpTGGhWRW3XQuzHfNH2GJPdy2dZfLFGOCkNdGP3zYoIG7sTJJYP966oz/b7efDTgIeL/52lNYLGULuuTHE7sr8LXr7cAoPPk9XjXPWNxIhERuXVmV2rTJsjIACfN1iwi/2AY8PLLMHmy+f3QoRAaqjOmROTfO+jdmD+87sTn9EE8Us9z0a0MxyrUwnBwxIO/6PpWNK2f28G3UwKJ+aIeO5bVZceyutS42x+IwTBu+BJiI/RZiPyDB9+80YeMdCcaPfI7gU/9z+pAIiLyr+yiZMkMzp2D/+mQLiL/kJ5uXsZ3pTH16qtqTIlI/jIcHImvWJsDPv7EV6yN4ZC9DeFZ4zzBc1bzUvQnNO28HwfHTA5vrQeso2/fukREmMcqsW1qTsk/vMuZo7dRtvIFerz7vQoTEZFiL4NGjS4CsHGjxVFEpEg5dw4efdQcAN3JCebOhYkT1ZgSEWtUvTORp8K/Y/zPC2ncaROQwp49HvTuDX5+MGUKJCZanVIKippTkmXNmnJAf3DIpM8Hq/Eon2p1JBERyQdNmyYBGndKRP62bx/ccw+sXg0lS8JXX8GAAVanEhEBT79ztB3+JeDLoEHH8PKC+HgYPx6qVYOBA3U2uC1Sc0oAOHIEJk/2BeCeJ3+gdst4ixOJiEh+adLk7+aUxm4QkZUr4e67Yf9+qFoV1q+Hhx+2OpWIyD8l8uyzCRw5AgsXwl13wV9/wbx5cOed0LateTzLzLQ6p+QHNaeES5fgySchKckZ+JHAp9ZYHUlERPJRw4YXcXGBY8fg0CGr04hIocnMgBNRcDgCTkRxKS2DV16Bxx6DCxegVSuIiQF/f6uDiohcm5sbBAfDtm3mB21du5ozia5dax7P6tSB994zj2vZ/OMYSKZmoC/K1JwSJk82Z3Hy8MgAeuPkrNaziIgtcXc3CAgwlzXulIidiFsGK2rA2jawuTdxnwXTpkkMr79u3v388/D991CpkqUpRURumoMDtGwJX3wBf/wBo0ZBuXJw8CAMGwZVqsCIEeZ9/zwGsraN+X3cMmt3Qq5JzSk7t2kTTJpkLo8ZEwvoI3UREVvUsqX5VeNOidiBuGWwoRskHwXgq22P0XjsLjbuvZvS7udZ/N+tzJwJLi4W5xQRuUXVq8O0aXD0KISFQb165plToaFw++0Gj3d2JGb3P7rvyfHmsVENqiJJzSk7dvYs9O5tXqMbHAwdO56xOpKIiBSQoCDzq5pTIjYuMwNihgEGZy+Wpd+ccB7/z1ecuViBgJo/s2PKXfSq2k2Xt4iITfDwgOeeg9274dtv4aH2BobhwFcxjxMwIYbgsIXEJla7vPXlgTdjhusYWAQ5Wx1ArGEYMGgQxMZCzZrw/vvw229WpxIRkYLSooX5df9++PNPuO02a/OIyK2LjY0l8RrzqZe6uI06yUf5bld7BsydR/yZqjg4ZPJix3eY3H08rs7pkAwHNoWT5BGQ4/Genp74+voW9C6IiNyyax0DK1WCd8dvI7PtDCYvH8+iTcEs2hTM51ufYGSHGUx4/A1KuqVAcpyOgUWQmlN2asEC+OwzcHaGiAgoXdrqRCIiUpAqVICGDc2plzduhM6drU4kIrciNjaWevXrkZKckuv9XZqVoYLHHOZFDQTgdq/fWDDoaVrU3Zxtu4mjB/HplpyPL1GyBPv27tMfZyJSJN3oGNgzECKGwMeD+zK8QygvfTKdqL1tmLpiHJ/91J05/Z/l/jvW6RhYBKk5ZYcOHIAXXjCXX3/dnEpYRERsX8uWZnNqwwY1p0SKq8TERFKSU+jzQR+86nhlrTcM2L+uCd/PfJjzZ8oDMOyhUKZ0H2eeKfAPrSZ2p4pbtWzrThw4waJBi0hMTNQfZiJSJF3rGHhFrdQ4OPUZAP5+2/lh/P2siHmMIR/N5OCJ23lgyg/0ax1OwIsbqVKxYrbH6hhoLTWn7ExaGvTqBRcvQps25gwHIiJiH4KCYPZsjTslYgu86nhRrbHZXDr5ezm+GNWGA9HmH1O3+/zG3H4DuK/++hyPM4Ak93KkN7uXag4aflZEiqerj4FXSzeqcCFqDaX+OosD5gx/nQJW0KbBOsZ9NoWw7wczP7o/5Q8+QfCc76h57/HCDy+5uqV3pLCwMPz8/HB3d8ff358NN6hyo6Oj8ff3x93dnZo1azJ79uxs98+dO5egoCDKly9P+fLladu2LVu3br2VaHID48fD9u3m5R0ffwxOTlYnEhGRwnJlUPQdOyApydosIvLvpaU4sWrKvbzV8kkORPvi7HaJDmO3MG3V27Suv/7K0L9ZrnwfXb8zhhpTImKDDAdHouubp4dffQwsU/IC/336Bda/HERl3xOcOVqG/z7Sje+m3U1mhoM1YSWbPL8rLVmyhOHDhzN+/Hh27NhBUFAQHTp0IDY2NtftDx06RMeOHQkKCmLHjh2MGzeOoUOHsnTp0qxtoqKi6NWrF+vWrWPLli34+vrSrl074uPjb33PJIfISJg+3VyePx+qVLE2j4iIFK5q1cyplzMy4McfrU4jIv/Goa11mdayD2um30NGmjP1HjjMmM2LaD9qK7G+d/BN02dIci+X7TFJ7uX4pukzHPRubE1oEZFCcNC78TWPgWd71mXYhqU067kHI9OR794M5P1OXTh/oqQ1YSVLni/rmzFjBv3792fAgAEAhIaGsnr1ambNmsXUqVNzbD979mx8fX0JDQ0FoH79+mzbto3p06fTtWtXAD755JNsj5k7dy5ffPEFa9eupW/fvnmNKLn480+48k/53HPQqZO1eURExBotW8KRI+alfW3bWp1GRPLq5EkXYAnLRncHoGzlJDpPiabxY7/jcNWH/we9G/OH1534nD6IR+p5LrqV4ViFWjpjSkTswvWOge6k82RYJHXvi+Xzl+7n4OaqvHN/Tx5+eb7Vse1anppTaWlpxMTEMGbMmGzr27Vrx+bNm3N9zJYtW2jXrl22de3btyc8PJz09HRcXFxyPCY5OZn09HQqVKhwzSypqamkpqZmfX/+/Pm87IpdMQx45hlISIAGDf4+e0pEROxPUBB88onGnRIpbi5dgpkzYfz4BsCdODhm0GrQLjqM+RH30um5PsZwcCS+Yu3CDSoiUkTc6BgY0H0/vnedILzPI5w4UJElw54HdhVeQMkmTx+dJCYmkpGRgZdX9lHxvby8SEhIyPUxCQkJuW5/6dIlEhMTc33MmDFjqFKlCm2v85Hu1KlTKVu2bNatWrWcg6GJaeZM+OYbcHODiAgoqTMWRUTs1pVxp378EdJz/3tWRIqYn382Z1ceMQKSk52ALfT5IJTOkzdcszElIiI3Vun2s4xY8xl3Pvw7GenOwHzeeacKGRlWJ7M/t3Rer4ND9gHDDMPIse5G2+e2HmDatGlERESwbNky3N3dr/mcY8eO5dy5c1m3uLi4vOyC3di1C156yVx++21o1MjaPCIiYq169aB8eUhJMd8jRKToOncOhgyBe+4xJzIoXx7Gjz8CtKDS7ZphSkQkP7iXSeOZj76h+TPfAbB4sRfdu5u1khSePDWnPD09cXJyynGW1MmTJ3OcHXWFt7d3rts7OztTsWLFbOunT5/OlClTWLNmDY1u0EVxc3OjTJky2W6S3cWL0LMnpKXBI4+YxY2IiNg3R0cIDDSXr3FFvohYzDDgs8+gfn14/33z+z59YN8+6NLlFOSYh09ERP4NR0cI7Ps90AMXl0yWLYMHHoBrXOwlBSBPzSlXV1f8/f2JjIzMtj4yMpLmzZvn+pjAwMAc269Zs4aAgIBs4029/fbbvP7663z33XcEBATkJZZcw4gRZhFTuTJ8+CFc5+Q2ERGxI1festWcEil6YmPh4YehRw84fhxq14bvv4ePP4ZKlaxOJyJi6z4jLOx3ypWDLVvMmungQasz2Yc8X9Y3cuRI5s2bx/z589m7dy8jRowgNjaWkJAQwLzc7uoZ9kJCQjhy5AgjR45k7969zJ8/n/DwcF66cq0Z5qV8EyZMYP78+dSoUYOEhAQSEhJISkrKh120T59/DnPnmg2pRYvA09PqRCIiUlSoOWUfwsLC8PPzw93dHX9/fzbcYBT86Oho/P39cXd3p2bNmsyePTvb/XPnziUoKIjy5ctTvnx52rZty9atWwtyF+yKYUB4ODRsCN9+C66uMHEi/PKL+em9iIgUjrvuSmLzZqheHX77zaybfvnF6lS2L8/NqR49ehAaGsqkSZNo0qQJ69evZ9WqVVSvXh2A48ePExsbm7W9n58fq1atIioqiiZNmvD666/z3nvv0bVr16xtwsLCSEtLo1u3blSuXDnrNl3Tyt2SI0dg4EBzeexYuP9+a/OIiEjRcvfd4OQEcXHmTWzPkiVLGD58OOPHj2fHjh0EBQXRoUOHbDXa1Q4dOkTHjh0JCgpix44djBs3jqFDh7J06dKsbaKioujVqxfr1q1jy5Yt+Pr60q5dO+Lj4wtrt2xWfLx5ttSAAXDhgnnp7S+/wKuvwnWGYBURkQJSv7555lSTJnDyJNx3H+jzmILlfCsPGjx4MIMHD871vgULFuRY17p1a7Zv337N5zt8+PCtxJBcXLoEvXubA2jee69Z1IiIiFzNw8MstmJizMJLE97anhkzZtC/f38GDBgAQGhoKKtXr2bWrFlMnTo1x/azZ8/G19eX0NBQAOrXr8+2bduYPn161geKn3zySbbHzJ07ly+++IK1a9dmO2te8iYiAgYPhrNnzZmV33jDHJrBycnqZCIi9q1yZVi3Djp2NOultm3h66+hVSurk9mmW5qtT4qYzAw4EQWHI5j0f4fZvBnKlIHFi+GqYb1ERESy6NI+25WWlkZMTAzt2rXLtr5du3ZsvsYPfMuWLTm2b9++Pdu2bSM9PT3XxyQnJ5Oenk6FChVyvT81NZXz589nu9mtq2o1TkRBZgYXL0L//uaHimfPQrNmsH27OcuyGlMiIkVDuXKwZg20aWOe2frQQ+b3kv/UnCru4pbBihqwtg1R8z7gjVBfAOZM+Qk/P2ujiYhI0aXmlO1KTEwkIyMjx0zKXl5eOWZQviIhISHX7S9dukTiNaYqGjNmDFWqVKFt27a53j916lTKli2bdatmr6foXVWrsbk3rG3D//7bnmZNzjN/vjk+6CuvmP8XGzSwOqyIiPxTqVLwzTfmGVQpKfDoo+b3kr/UnCrO4pbBhm6QfJRTFyrQJ2wRhuFIv9bz6VE+0LxfREQkF1eaUzt2QHKytVmkYDj8Y5pewzByrLvR9rmtB3Mym4iICJYtW4b7NQZFGjt2LOfOncu6xdnjAGdX1WpXLN7Ui2ajVrL39zJUrpTC2rXw2mvgfEuDbYiISGEoUQK+/BK6doW0NOjSBVavtjqVbVFzqrjKzICYYYCBYcCAefOIP1OVOpX3817fF8xtYoab24mIiPxDtWpQpYo5VuHPP1udRvKTp6cnTk5OOc6SOnnyZI6zo67w9vbOdXtnZ2cqVqyYbf306dOZMmUKa9asoVGjRtfM4ebmRpkyZbLd7MpVtRpARqYjoyPe5MmwxfyVXoL2jb5j51vNadNatZqISHHg6mqOE9ili9mgevxxWLvW6lS2Q5/RFGGxsbHXPJW+1MVt1Ln8KdzstSEs39YZV+dUPh3SEw/3yx+BJ8dxYFM4SR4BOR7v6emJr69vgWUXEZGizcHBPHvq88/Ny4lat7Y6keQXV1dX/P39iYyMpHPnzlnrIyMj6dSpU66PCQwMZOXKldnWrVmzhoCAAFyuGsDy7bff5o033mD16tUEBOSsL+zRteq1q2u1sxfL0vv9xXy7qyMAYx+bwutPvIyTY+Y1azVQvSYiUtS4uJgNqm7dYOVK8xK/b79VHZUf1JwqomJjY6lXvx4pySm53t8zECKGwK+xDRmx6D8AvNVzNE1r7My23cTRg/h0S87HlyhZgn1796ngERGxY1c3p8S2jBw5kuDgYAICAggMDGTOnDnExsYSEhICmJfcxcfHs3DhQgBCQkKYOXMmI0eOZODAgWzZsoXw8HAiIiKynnPatGm8/PLLLF68mBo1amSdaVWqVClKlSpV+DtZBFyvXrtSqx09VYX2b61mT/wdlHBNZv6z/egZuCRru2vVaqB6TUSkKHJ1NeunLl1g1Sp4+GHzEr8WLaxOVrypOVVEJSYmkpKcQp8P+uBVJ+cp+LVS40g+tpJe70eQmu5OxybfMOyhd3Ns12pid6q4ZR+A9MSBEywatIjExEQVOyIiduzqQdENwzybSmxDjx49OHXqFJMmTeL48eM0bNiQVatWUb16dQCOHz9ObGxs1vZ+fn6sWrWKESNG8P777+Pj48N7771H165ds7YJCwsjLS2Nbt26ZXutiRMn8uqrrxbKfhU116vXaqXGsfeXX2j/1mriTvniUz6elS8+yl1+O7Jtl1utBqrXRESKMjc3WLoUOnUyZ+/r2BGio6FJowz4cwOkHIcSleG2IHDUFKw3Q82pIs6rjhfVGucsWNKNKgzt1Z7dRxviXe44Hz77TLY/Kgwgyb0c6c3upZqDhhYTEZGcmjQBd3c4fRoOHIC6da1OJPlp8ODBDB48ONf7FixYkGNd69at2b59+zWf7/Dhw/mUzPbkVq8d2BrA+EmzOJNUgbqV97F6dHuq3/Z3Q1C1mohI8ebuDsuXw0MPwfr10P7Bv9j42oPULrfx741KVgX/d6FaF8tyFhd6Jyymdn5dm/A1/XBwyGThc8FUKvtn1n3G5a/R9TtjqNgREZFrcHWFZs3MZV3aJ5J/Dqyvyvudu3ImqQL31PqRDRNb5mhMgWo1EZHirkQJWLECmjY8y8lEdx6c+DHxp33+3iA53py1NW6ZdSGLCb0bFkNnjpbm06FtAejS/zvuDYjJdn+Sezm+afoMB70bWxFPRESKkasv7RORf+/3TVWY2+sx0lNcqPfAYV5asgD327LPyKdaTUTEdpQtncF3L95Hbe8DHEmsQbs313A6qfzley9/HBEz3JzFVa5Jl/UVMxmXHPh4UHtSzrnje1cCzScf5EPnV/A5fRCP1PNcdCvDsQq19CmciIjcFDWnRPLPwS0+zOlpNqYaPHiIfgu/Id6tPh/6qVYTESnOrjUzK1yendV1F2vGtKPlaxvZE38HHaet4vtxbSnlfhEwIDlOs7PegJpTxUzkO3fzx5YquJVKpe/c73ByycTAkfiKta2OJiIixVBgoPl1zx44cwbKl7/+9iKSu0NbvZnToxNpF12p2+YIz3z0Dc5u5qfkhoNqNRGR4up6M7PC37Oz1rjtCGvGtCPo9Q38dPBeuvxnGV+PegRX53RAs7PeiJpTxcgfP/qw+u27Aeg+Yx2efucsTiQiIsXdbbdB7drw22/w44/QoYPViUSKn1OHvVgyvBOpSa7UaR1L/0UrcXHX5RsiIrbgejOzgjk7K6c+A6BB1b18+38duH/yD0T+rx0D581lwaCncXDQ7Kw3ouZUMZF81o2FAx/CyHSkWa89+Hfbb3UkERGxEc2bm82pzZvVnBLJOx+Wjh5Ayjl3ajQ7xoBPVuJaQo0pERFbk9vMrADpRhUuRK2h1F9ncQDurvUzXwzrxiPTv2bhhqeoVjGW0cEzNDvrDehfphgwDFgy7AHOxpfmtlpn6PpmlNWRRETEhmjcKZFbk5TkCKziwsnyVKp9moERK3EtecnqWCIiUogMB0ei63c2ly+ve6jxaj7oPwiAyctfZtz//qOxBm9A/zrFwJaPGrJrZW2cXDLoO/c73EunWx1JRERsyJXm1E8/wSX9XS1yUzIyYPx4P6AxHhXOM+jz5XhU+MvqWCIiYoGD3o35pukzJLmXy1rX/775jH7iLQDCJvVlT2R1i9IVD7qsr4hLPOTFl+NaA/DIy5uo1uSkxYlERMTWNGgAZcvCuXPwyy9w111WJxIp+iZMgI0bywIpdJ4STkVffeYrImLPDno35g+vO7PNzlq5vSt3O+9ha0QDFvTryAsrl+pv+mvQu2iR5s43bzxJ+l/O1Lv/MK0H77A6kIiI2CBHR7jnHnP5xx+tzSJSHEREwJtvXvmuH151462MIyIiRcSV2VkP+Pibs7Q6OtIjdC117ztC2kVX5vR8jFOxpa2OWSSpOVWkvU3iHz6Uui2ZJ8MicdRPS0RECsi995pff/rJ2hwiRd3//gf9+5vLTz2VAHxqaR4RESnanFwyeWbBKnwa/smFkx588MTjJJ91szpWkaN2RxEVFVUWGALAk2GrKV0p2dpAIiJi03TmlMiNXbwI3btDSgq0awfPP3/M6kgiIlIMuJdJ49lPv6JclQuc/K0CHz79MBnpasdcTf8aRVB8PEyaZA6WFtAjivoPxFqcSEREbN2V5tSBA3D6tLVZRIqqIUNg716oXBk+/hicnKxOJCIixUU5n4s8++kK3Eql8dv6anwx6j4M48aPsxdqThUxGRnQpw+cO+cMbKNl/2+tjiQiInagYkW4/XZzeetWa7OIFEUffwwLFphjtEVEQKVKVicSEZHixueORPrO+xYHx0y2LLyTqLCmVkcqMtScKmLefBOioqBkyQygF04uGVZHEhERO6Fxp0Ryd+QIPP+8uTxxIrRubW0eEREpvu5od5jH39gAwIpXgvh9UwOLExUNak4VIZs3mwUPwJgxccDvluYRERH7onGnRHLKzIR+/eDCBWjeHMaPtzqRiIgUd60G7aT5M79gGA6seuNJoLHVkSyn5lQRcfYs9O7992V9Dz+sAT9ERKRwXX3mlMZAEDG9/z788AOULAkffaRxpkRE5N9zcICub0ZT974jpP/lBqzkzz+drY5lKTWnigDDgGefNU8Zr1XLLIJEREQKW6NG4OYGZ87Ab79ZnUbEer/9BqNHm8tvv/33uGwiIiL/lpNLJk99uIoK1U8A1Rg5shbJyVanso6aU0XAhx/C55+Ds7M5wGaZMlYnEhERe+TqCv7+5rLGnRJ7ZxgQEgIpKdC2LTz3nNWJRETE1pQsm0bnKeFAInv2eNC3r3k5uT1Sc8piBw7ACy+Yy5MnQ7Nm1uYRERH7pnGnREwff2xezleiBHzwgXkJhoiISH4r53MaeBwXl0yWLoUJE6xOZA01pyyUlmaOM5WcDPffDy+9ZHUiERGxd5qxTwQSE2HkSHN54kSoWdPaPCIiYus28fLLsQBMnQoLFlibxgpqTlnolVcgJgYqVICFC8FRPw0REbHYlTOndu0yL2cSsUejRsGpU3DnnX83qURERArSww+fzpoR9tlnYcMGa/MUNrVDLLJuHUybZi7PmwdVqlibR0REBMDXF7y94dIl2L7d6jQihe/HH81PrB0czMv5XFysTiQiIvZi0iR44glIT4fOneGPP6xOVHjUnLLAqVMQHPz3LH2dO1udSERExOTgoHGnxH5lZsKwYeby009DYKClcURExM44OpofkPj7m32DRx+Fc+esTlU41JwqZIYBAwdCfDzUrQszZlidSEREJLsr406pOSX2ZtEi2LoVSpWCKVOsTiMiIvaoZEn46ivw8YE9e6BnT/OMdlun5lQhmzcPvvzSPEU8IgI8PKxOJCIikt2VM6c0KLrYk6QkGDPGXJ4wwby8VURExApVqsCKFeaMsd99Zx+Tp6k5VYj274fhw83lKVOgaVNL44iIiOQqIMA8rTwuDo4dszqNSOGYNg2OHzdn5rtSr4mIiFjF39+cOA3g3XfNcRBtmZpThSQ1FXr1guRkaNtWM7+IiEjRVbo03HGHuayzp8QenDgB77xjLk+bBm5u1uYREREB6NYN3njDXB4yBH74wdo8BUnNqUIyYQLs2AEVK8JHH5mfSIuIiBRVGndK7Mkbb5gfIN59N3TpYnUaERGRv40bB08+aY471a0bHDhgdaKCoRZJIfj+e5g+3VwODzcHNhMRESnKNO6U2ItDh/6+VGLqVHPGShERkaLCwcEcu/ree+HMGXMGvzNnrE6V/9ScKmCJidC3r7kcEgKdOlmbR0RE5GZcOXPq55/tY4YYsV8TJ0J6ujnswv33W51GREQkJ3d3WL4cfH3NM6eeeMJ877Ilak4VIMOAAQPMwTXr1/97LAMREZGirl49c+yp5GTYvdvqNCIFY88eWLTIXJ4yxdosIiIi1+PlBStXgocHrF0LQ4eaPQdboeZUfsrMgBNRcDgCTkQxZ3YmX30Frq6weDGULGl1QBERkZvj5AR3321WPD9+s9V8f8vMsDaUSH64ql57Y8IJDAM6d4ZmzawOJiIicn2NGkFEhHmp3+zZMHMmOfoQxbVec7Y6gM2IWwYxwyD5KAB74+sxYsJ2oARTp0KTJpamExERyZu4ZdxTLp61vMDWNb8yqMYAKFkV/N+FahoxWoqpq+q1A8drs2R5dwBeHrgWeMDabCIiIjfh0UfNmWVHjYLhww1q//k0D9Vb9PcGxbReu6Uzp8LCwvDz88Pd3R1/f382bNhw3e2jo6Px9/fH3d2dmjVrMnv27BzbLF26lAYNGuDm5kaDBg348ssvbyWaNeKWwYZuWY2p1HRXes2MICWtBO3uXM3wrsssDigiIpIHl9/X7qkeCcDWg3eb65Pjzfe7OL2vFQeq1/7hH/XalK/GkWk48UjTlTQ986B+r0VEpNh48UV4pvthMjMd6DF9JnuO1v/7zmJar+W5ObVkyRKGDx/O+PHj2bFjB0FBQXTo0IHY2Nhctz906BAdO3YkKCiIHTt2MG7cOIYOHcrSpUuzttmyZQs9evQgODiYXbt2ERwcTPfu3fmpOEwRlJlhfgLH3xd7jlsyhV2xTfAs/ScLBj2D447hxfbUOhERsTNXva81q/kzALvj7+BCSimy3utihut9rYhTvfYP/6jX/jjpx6JNfQB4ufPr5jb6vRYRkWLCwchgdrf7aVUvmvMpZXn0nZUkXqh4+d7iWa/l+bK+GTNm0L9/fwYMGABAaGgoq1evZtasWUydOjXH9rNnz8bX15fQ0FAA6tevz7Zt25g+fTpdu3bNeo4HH3yQsWPHAjB27Fiio6MJDQ0lIiIi1xypqamkpqZmfX/u3DkAzp8/n9dduikJCQkkJCTkWF8qeQe3Jx7N+n7t7jbM+HYgcJ7/9u2Lh9txzifC72tmklSyaa7P7e3tjbe3d7Z1SUlJAMTtiiP1YmpuD7tlJ38/mfUaV/97FeRrXut1rXjNgn5dvaZtvaZVr6vXtK3XvNbrWvW7Czf3vubhlkCV8ruJP1ON9fsaE1R3E2BAclye39fyw5V9MGxp9M8CUhTqtcKu1eDm67XXvxxKRmYy9zf4nnqVf+Z8Mrf0e21rxyp7ec1rva7qCb1mfryufo/0mvn1utd6T4PL72vnDrFgUGfun/wDf5ysyWPTP+arFzvh5pxOsazXjDxITU01nJycjGXLlmVbP3ToUKNVq1a5PiYoKMgYOnRotnXLli0znJ2djbS0NMMwDKNatWrGjBkzsm0zY8YMw9fX95pZJk6caGC2BHXTTTfddNNNNzu6xcXF5aV8sTtFpV5Traabbrrppptu9nvLa72WpzOnEhMTycjIwMvLK9t6Ly+va3b0EhISct3+0qVLJCYmUrly5Wtuc63nBPPTupEjR2Z9n5mZyenTp6lYsSIODg552a18df78eapVq0ZcXBxlypSxLEdhsJd9tZf9BPvZV+2n7bGXfbWX/YTc99UwDC5cuICPj4/F6Yq2olKvFdVaDfR/yRZpP22Pveyr9tP22Mu+Xms/b7Veu6XZ+v5ZUBiGcd0iI7ft/7k+r8/p5uaGm5tbtnXlypW7bu7CVKZMGZv+Rbyaveyrvewn2M++aj9tj73sq73sJ+Tc17Jly1qYpnixul4r6rUa2Pf/JVul/bQ99rKv2k/bYy/7mtt+3kq9lqcB0T09PXFycsrxCdnJkydzfJJ2hbe3d67bOzs7U7Fixetuc63nFBEREZHcqV4TERGR4iZPzSlXV1f8/f2JjIzMtj4yMpLmzZvn+pjAwMAc269Zs4aAgABcXFyuu821nlNEREREcqd6TURERIqbPF/WN3LkSIKDgwkICCAwMJA5c+YQGxtLSEgIYI4vEB8fz8KFCwEICQlh5syZjBw5koEDB7JlyxbCw8OzzeoybNgwWrVqxVtvvUWnTp346quv+P7779m4cWM+7WbhcXNzY+LEiTlOY7dF9rKv9rKfYD/7qv20Pfayr/ayn2Bf+1oQVK9dnz39ftnLvmo/bY+97Kv20/bYy77m9346GEbe52MOCwtj2rRpHD9+nIYNG/Kf//yHVq1aAfD0009z+PBhoqKisraPjo5mxIgR7N69Gx8fH0aPHp1VHF3xxRdfMGHCBP744w9q1arF5MmT6dKly7/bOxERERE7pXpNREREiotbak6JiIiIiIiIiIjkhzyNOSUiIiIiIiIiIpKf1JwSERERERERERHLqDklIiIiIiIiIiKWUXNKREREREREREQso+ZUPgsLC8PPzw93d3f8/f3ZsGGD1ZHy1dSpU2nWrBmlS5emUqVKPP744+zfv9/qWAVu6tSpODg4MHz4cKujFIj4+Hj69OlDxYoVKVmyJE2aNCEmJsbqWPnu0qVLTJgwAT8/P0qUKEHNmjWZNGkSmZmZVkf7V9avX8+jjz6Kj48PDg4OLF++PNv9hmHw6quv4uPjQ4kSJbjvvvvYvXu3NWH/hevtZ3p6OqNHj+bOO+/Ew8MDHx8f+vbty7Fjx6wL/C/c6Gd6tUGDBuHg4EBoaGih5csvN7Ofe/fu5bHHHqNs2bKULl2ae++9l9jY2MIPKzZF9ZptUr1W/NlqrQaq10D1muq161NzKh8tWbKE4cOHM378eHbs2EFQUBAdOnSwqSI6Ojqa559/nh9//JHIyEguXbpEu3btuHjxotXRCszPP//MnDlzaNSokdVRCsSZM2do0aIFLi4ufPvtt+zZs4d33nmHcuXKWR0t37311lvMnj2bmTNnsnfvXqZNm8bbb7/Nf//7X6uj/SsXL16kcePGzJw5M9f7p02bxowZM5g5cyY///wz3t7ePPjgg1y4cKGQk/4719vP5ORktm/fzssvv8z27dtZtmwZBw4c4LHHHrMg6b93o5/pFcuXL+enn37Cx8enkJLlrxvt58GDB2nZsiX16tUjKiqKXbt28fLLL+Pu7l7IScWWqF6zTarXbIOt1mqgeg1Ur6leuwFD8s3dd99thISEZFtXr149Y8yYMRYlKngnT540ACM6OtrqKAXiwoULRu3atY3IyEijdevWxrBhw6yOlO9Gjx5ttGzZ0uoYheLhhx82+vXrl21dly5djD59+liUKP8Bxpdffpn1fWZmpuHt7W28+eabWev++usvo2zZssbs2bMtSJg//rmfudm6dasBGEeOHCmcUAXkWvt69OhRo0qVKsb//vc/o3r16sZ//vOfQs+Wn3Lbzx49etjU/08pGlSv2R7Va7bDHmo1w1C9djXVa8VLQdZrOnMqn6SlpRETE0O7du2yrW/Xrh2bN2+2KFXBO3fuHAAVKlSwOEnBeP7553n44Ydp27at1VEKzIoVKwgICOCJJ56gUqVKNG3alLlz51odq0C0bNmStWvXcuDAAQB27drFxo0b6dixo8XJCs6hQ4dISEjIdmxyc3OjdevWNn1sAvP45ODgYHOfKgNkZmYSHBzMqFGjuOOOO6yOUyAyMzP55ptvqFOnDu3bt6dSpUrcc8891z1lXuRGVK+pXiuu7KVes8daDVSvqV4rvvKzXlNzKp8kJiaSkZGBl5dXtvVeXl4kJCRYlKpgGYbByJEjadmyJQ0bNrQ6Tr779NNPiYmJYerUqVZHKVB//PEHs2bNonbt2qxevZqQkBCGDh3KwoULrY6W70aPHk2vXr2oV68eLi4uNG3alOHDh9OrVy+roxWYK8cfezo2Afz111+MGTOG3r17U6ZMGavj5Lu33noLZ2dnhg4danWUAnPy5EmSkpJ48803eeihh1izZg2dO3emS5cuREdHWx1PiinVa6rXiit7qdfssVYD1Wuq14qv/KzXnAsoo91ycHDI9r1hGDnW2YohQ4bwyy+/sHHjRquj5Lu4uDiGDRvGmjVrbH5sk8zMTAICApgyZQoATZs2Zffu3cyaNYu+fftanC5/LVmyhEWLFrF48WLuuOMOdu7cyfDhw/Hx8eGpp56yOl6BsqdjU3p6Oj179iQzM5OwsDCr4+S7mJgY3n33XbZv326zP0Mga/DbTp06MWLECACaNGnC5s2bmT17Nq1bt7YynhRz9nRMVL1mG+ylXrPnWg3s69ikes025Ge9pjOn8omnpydOTk45OtsnT57M0QG3BS+88AIrVqxg3bp1VK1a1eo4+S4mJoaTJ0/i7++Ps7Mzzs7OREdH89577+Hs7ExGRobVEfNN5cqVadCgQbZ19evXt6mBYa8YNWoUY8aMoWfPntx5550EBwczYsQIm/601dvbG8Bujk3p6el0796dQ4cOERkZaZOfwm3YsIGTJ0/i6+ubdXw6cuQIL774IjVq1LA6Xr7x9PTE2dnZbo5PUjhUr9kW1Wu2dzy0x1oNVK+pXiu+8rNeU3Mqn7i6uuLv709kZGS29ZGRkTRv3tyiVPnPMAyGDBnCsmXL+OGHH/Dz87M6UoF44IEH+PXXX9m5c2fWLSAggCeffJKdO3fi5ORkdcR806JFixzTSx84cIDq1atblKjgJCcn4+iY/bDn5ORkE9MTX4ufnx/e3t7Zjk1paWlER0fb1LEJ/i50fvvtN77//nsqVqxodaQCERwczC+//JLt+OTj48OoUaNYvXq11fHyjaurK82aNbOb45MUDtVrtkX1mu0dD+2xVgPVa7ZI9Vrej0+6rC8fjRw5kuDgYAICAggMDGTOnDnExsYSEhJidbR88/zzz7N48WK++uorSpcundXdL1u2LCVKlLA4Xf4pXbp0jnEZPDw8qFixos2N1zBixAiaN2/OlClT6N69O1u3bmXOnDnMmTPH6mj57tFHH2Xy5Mn4+vpyxx13sGPHDmbMmEG/fv2sjvavJCUl8fvvv2d9f+jQIXbu3EmFChXw9fVl+PDhTJkyhdq1a1O7dm2mTJlCyZIl6d27t4Wp8+56++nj40O3bt3Yvn07X3/9NRkZGVnHpwoVKuDq6mpV7Ftyo5/pPws5FxcXvL29qVu3bmFH/VdutJ+jRo2iR48etGrVijZt2vDdd9+xcuVKoqKirAstxZ7qNdVrxZG91Gu2WquB6jXVa6rXbuhfz/cn2bz//vtG9erVDVdXV+Ouu+6yuSl7gVxvH374odXRCpytTk1sGIaxcuVKo2HDhoabm5tRr149Y86cOVZHKhDnz583hg0bZvj6+hru7u5GzZo1jfHjxxupqalWR/tX1q1bl+v/y6eeesowDHN64okTJxre3t6Gm5ub0apVK+PXX3+1NvQtuN5+Hjp06JrHp3Xr1lkdPc9u9DP9p+I6NfHN7Gd4eLhx++23G+7u7kbjxo2N5cuXWxdYbIbqNduleq14s9VazTBUr6leU712Iw6GYRh5a2eJiIiIiIiIiIjkD405JSIiIiIiIiIillFzSkRERERERERELKPmlIiIiIiIiIiIWEbNKRERERERERERsYyaUyIiIiIiIiIiYhk1p0RERERERERExDJqTomIiIiIiIiIiGXUnBIREREREREREcuoOSUiIiIiIiIiIpZRc0pERERERERERCyj5pSIiIiIiIiIiFjm/wEQlDvJOgiVrgAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 1200x400 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "from scipy.interpolate import make_interp_spline\n",
    "\n",
    "# Drawing both of them\n",
    "figure, axis = plt.subplots(1, 2)\n",
    "figure.set_figheight(4)\n",
    "figure.set_figwidth(12)\n",
    "figure.tight_layout(w_pad = 5)\n",
    "\n",
    "def draw(y, id):\n",
    "    x = np.array(range(0, np.size(y)))\n",
    "    XYSpline = make_interp_spline(x, y) \n",
    "    X = np.linspace(x.min(), x.max(), 500)\n",
    "    Y = XYSpline(X)\n",
    "    axis[id].bar(x, y, color=\"lightgreen\", ec='black')\n",
    "    axis[id].scatter(x, y, color=\"orange\")\n",
    "    axis[id].plot(X, Y, color='blue')\n",
    "\n",
    "axis[0].title.set_text(\"Initial distribution\")\n",
    "axis[1].title.set_text(\"Required distribution\")\n",
    "draw(a, 0)\n",
    "draw(b, 1)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to better understand how Optimal Transport works, below is presented the code considering the case when the matrix cost distance is presented and defined as the absolute difference between positions of each part of the distribution. That is $\\text{distance}[i][j] = abs(i - j)$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "_a = pd.Series(a)\n",
    "_b = pd.Series(b)\n",
    "distance = np.zeros((np.size(a), np.size(b)))\n",
    "for i in range(np.size(a)):\n",
    "    for j in range(np.size(b)):\n",
    "        distance[i][j] = abs(i - j)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Wasserstein distance is equal to 1.3773703499999999.\n"
     ]
    }
   ],
   "source": [
    "from aif360.sklearn.metrics import ot_distance\n",
    "c0 = ot_distance(y_true=_a, y_pred=_b, cost_matrix=distance, mode='continuous')\n",
    "\n",
    "print(\"Wasserstein distance is equal to \", c0, \".\", sep=\"\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2. Randomly distributed samples\n",
    "\n",
    "Suppose we have two distributions $a$ and $b$ with length $N$, that are generated randomly, and we need to calculate earth_movers_distance for them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "N = 1000\n",
    "np.random.seed(seed=1)\n",
    "\n",
    "# Initial distribution\n",
    "a = np.random.rand(N)\n",
    "a /= np.sum(a)\n",
    "\n",
    "# Required distribution\n",
    "b = np.random.rand(N)\n",
    "b /= np.sum(b)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAABeAAAAGUCAYAAABdvoLAAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjUuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/NK7nSAAAACXBIWXMAAA9hAAAPYQGoP6dpAABPVUlEQVR4nO3dfZhVZb0//vfIwwCeEQFzBhKU+kKWmA9oFJZgPJj5GJUZktqxwoN2JDWSTB08CUVFnDQ1rYQyss5Ry04nE8Owwn4BPpSAWicSKkfCLwLKyOP6/cGXfRgBZWA2MzCv13XtS/da917rs242a6/15t73riiKoggAAAAAANCk9mvuAgAAAAAAYF8kgAcAAAAAgDIQwAMAAAAAQBkI4AEAAAAAoAwE8AAAAAAAUAYCeAAAAAAAKAMBPAAAAAAAlIEAHgAAAAAAykAADwAAAAAAZSCAB/Y606ZNS0VFRebNm7dLr6+oqEhtbW3p+cKFC1NbW5u//OUv27S94IILcthhh+3SfnbntUkyePDgDB48uPT8L3/5SyoqKjJt2rRGbWfGjBmZOnVqo16zvX3V1tamoqIiy5cvb9S2Xk25+h4AgJZry/X8lkfbtm3TvXv3nHPOOfnjH//Y3OWV/PKXv0xFRUV++ctf7pH9HXbYYbngggt26bWvdv3eGGvWrEltbW2jj3l7+zrssMNy2mmnNWo7r+XV7m1eeZ8H0FII4IFW5+GHH87HPvax0vOFCxdmwoQJ2w2Br7766txzzz17sLod6969ex5++OGceuqpjXrdrgTwu7qvxtpb+h4AgKZ3++235+GHH84DDzyQSy65JPfee2/e+c53ZsWKFc1dWpLk2GOPzcMPP5xjjz22uUvZJR/72Mfy8MMPN+o1a9asyYQJExodwO/KvnbFq93bvPI+D6ClaNvcBQDsaW9/+9t3uu0b3/jGMlbSOJWVlY2qfVds3LgxGzZs2CP7ei0tqe8BAGh6/fr1y3HHHZdk87c/N27cmGuvvTY/+tGP8tGPfrSZq0sOOOCAnbomXrNmTTp16rQHKmqcQw45JIccckhZ97Hl2PfEvl5Lc9+/AOyIEfDAPuGCCy7IP/3TP+VPf/pT3vve9+af/umf0rNnz1x++eVZu3Ztg7ZbfzVx2rRp+eAHP5gkOemkk0pfg93y1c3tTYPy9a9/PSeeeGIOPvjg7L///jnyyCMzefLkrF+/fpdqL4oikydPzqGHHpoOHTrk2GOPzc9+9rNt2m3va6X/+Mc/8olPfCI9e/ZMZWVlXve61+WEE07IAw88kGTzjcxPf/rTPPPMMw2+5rv19iZPnpzPf/7z6d27dyorK/Pggw++6nQ3S5cuzYgRI3LAAQekc+fOGTVqVP7xj380aLOjr39u/bXaXen7l19+OePHj0/v3r3Tvn37vP71r8/FF1+cF154YZv9nHbaabnvvvty7LHHpmPHjjn88MPz7W9/ewd/CgAANLctYfxzzz3XYPm8efNyxhlnpGvXrunQoUOOOeaY/PCHP9zm9b/97W9zwgknpEOHDunRo0fGjx+f2267LRUVFQ2+cbkz16rJ9qeg2XLf8Yc//CHDhw9PVVVVhgwZkiRZt25dPv/5z+fwww8vXZt/9KMf3eZaef369Rk3blxqamrSqVOnvPOd78zvfve7ne6nv//97zn77LNTVVWVzp0750Mf+lDq6uq2abe9aWFmzZqVwYMHp1u3bunYsWN69eqV97///VmzZk3+8pe/5HWve12SZMKECaXr8y19smV7jzzySD7wgQ+kS5cupUEzrzbdzT333JO3vvWt6dChQ97whjfka1/7WoP1W6YkeuW3Yl/Z/692b5Ns/8/1iSeeyJlnnpkuXbqkQ4cOOfroozN9+vTt7uf73/9+rrrqqvTo0SMHHHBAhg4dmqeeemq7xwTQGEbAA/uM9evX54wzzsiFF16Yyy+/PA899FD+7d/+LZ07d84111yz3deceuqpmThxYj772c/m61//eunrpa82+vp//ud/MnLkyFII/Pjjj+f666/Pk08+uUsB74QJEzJhwoRceOGF+cAHPpClS5fm4x//eDZu3Jg3velNr/raj3zkI3nkkUdy/fXXp2/fvnnhhRfyyCOP5Pnnn0+S3HTTTfnEJz6R//mf/9nhdC5f+9rX0rdv33z5y1/OAQcckD59+rzqPt/3vvfl7LPPzkUXXZQFCxbk6quvzsKFC/P//X//X9q1a7fTx93Yvi+KImeddVZ+8YtfZPz48XnXu96V3//+97n22mvz8MMP5+GHH05lZWWp/eOPP57LL788V155Zaqrq/PNb34zF154Yf7P//k/OfHEE3e6TgAA9ozFixcnSfr27Vta9uCDD+Y973lPBgwYkFtuuSWdO3fOnXfemQ996ENZs2ZNKRxeuHBhhgwZksMOOyzTpk1Lp06dctNNN2XGjBlNXue6detyxhlnZPTo0bnyyiuzYcOGbNq0KWeeeWZ+9atfZdy4cRk4cGCeeeaZXHvttRk8eHDmzZuXjh07Jkk+/vGP5zvf+U6uuOKKDBs2LE888URGjBiR1atXv+a+6+vrM3To0Pz973/PpEmT0rdv3/z0pz/Nhz70odd87V/+8peceuqpede73pVvf/vbOfDAA/O3v/0t9913X9atW5fu3bvnvvvuy3ve855ceOGFpelctoTyW4wYMSLnnHNOLrroorz00kuvus/HHnssY8eOTW1tbWpqavK9730vl156adatW5crrrjiNWve2s7c22ztqaeeysCBA3PwwQfna1/7Wrp165Y77rgjF1xwQZ577rmMGzeuQfvPfvazOeGEE/LNb34zq1atymc+85mcfvrpWbRoUdq0adOoWgG2JoAH9hnr1q3LhAkTSqOqhwwZknnz5mXGjBk7DOBf97rXlQLnt7zlLTv1tcUpU6aU/n/Tpk1517velW7duuWjH/1ovvKVr6RLly47XfMLL7yQL37xi3nf+96Xb37zm6XlRxxxRE444YTXDOB/85vf5GMf+1g+/vGPl5adeeaZpf9/y1vekgMPPPBVp5Tp0KFDfv7znzcIz7c3J/sWI0aMyOTJk5Mkw4cPT3V1dc4999z88Ic/zLnnnvuq9W6tsX1///335+c//3kmT56cT3/600mSYcOGpWfPnvnQhz6U73znOw36Yfny5fnNb36TXr16JUlOPPHE/OIXv8iMGTME8AAALcCW6Q9ffvnl/OY3v8nnP//5nHjiiTnjjDNKbcaMGZMjjjgis2bNStu2myOMk08+OcuXL89nP/vZnHfeedlvv/1y3XXXpSiKzJo1K9XV1Uk2D/jo169fk9e9fv36XHPNNQ2mybnzzjtz33335a677sqIESNKy4866qgcf/zxmTZtWv7lX/4lTz75ZKZPn55PfepTpWvqYcOGla6pX8v06dOzaNGi/PjHPy710/Dhw1NfX5/bbrvtVV87f/78vPzyy/nSl76Uo446qrR85MiRpf/v379/ks3T1+zo+vz888/PhAkTXrPWZPNo/UcffbS0v1NOOSXLli3Lv/3bv2XMmDGNmrpnZ+5ttlZbW5t169blwQcfTM+ePZMk733ve/PCCy9kwoQJGT16dDp37txg+3fccUfpeZs2bXL22Wdn7ty5prcBdospaIB9RkVFRU4//fQGy9761rfmmWeeadL9PProoznjjDPSrVu3tGnTJu3atct5552XjRs35umnn27Uth5++OG8/PLL21xsDxw4MIceeuhrvv5tb3tbpk2bls9//vP57W9/u0vT4JxxxhmNGrn+ylrPPvvstG3bNg8++GCj990Ys2bNSpIGXwtOkg9+8IPZf//984tf/KLB8qOPProUvieb/6Ghb9++Tf5+AABg17z97W9Pu3btUlVVlfe85z3p0qVLfvzjH5eC9j/96U958sknS9efGzZsKD3e+9735tlnny1NEfLggw9myJAhpfA92Ryg7szI8F3x/ve/v8Hz//qv/8qBBx6Y008/vUGdRx99dGpqakrTqGy5Zt7RNfVrefDBB1NVVdXgHymShiH6jhx99NFp3759PvGJT2T69On585///Jqv2Z5XHvurOeKIIxqE/cnmWletWpVHHnlkl/a/s2bNmpUhQ4aUwvctLrjggqxZs2abH419ZZ++9a1vTRL3D8BuE8AD+4xOnTqlQ4cODZZVVlbm5ZdfbrJ9LFmyJO9617vyt7/9Lf/+7/+eX/3qV5k7d26+/vWvJ9n8ldDG2DJVTE1NzTbrtrfslX7wgx/k/PPPzze/+c284x3vSNeuXXPeeedtdw7IHenevfvOF7ydutq2bZtu3bqVjqVcnn/++bRt23abr8BWVFSkpqZmm/1369Ztm21UVlY2+s8IAIDy+M53vpO5c+dm1qxZGT16dBYtWpQPf/jDpfVb5oK/4oor0q5duwaPMWPGJNn8rcdk87Xirl5TN1anTp1ywAEHNFj23HPP5YUXXkj79u23qbWurq5Bndura8s19Wt5/vnnG/wjwxY7c5xvfOMb88ADD+Tggw/OxRdfnDe+8Y154xvfmH//939/zddurTH3D6/2Z7In7h+2V2uPHj22u/9X9v+W6S3dPwC7yxQ0AI3wox/9KC+99FLuvvvuBiPUH3vssV3a3paLvO0F5nV1ddv8COkrHXTQQZk6dWqmTp2aJUuW5N57782VV16ZZcuW5b777tupGnb0Y0k7UldXl9e//vWl5xs2bMjzzz/f4IK1srJymx+/TXbvIrtbt27ZsGFD/vGPfzQI4YuiSF1dXY4//vhd3jYAAHvem9/85tIPr5500knZuHFjvvnNb+Y///M/84EPfCAHHXRQkmT8+PENpnXZ2pYpG7t167bDa+pX2t1r1e1dPx900EHp1q3bDq/Bq6qqSnVuqWt719SvpVu3btv9wdadHYDzrne9K+9617uycePGzJs3LzfccEPGjh2b6urqnHPOOTu1jcbcP7zan8mWvtgyiOqVfyZb/tFiV3Xr1i3PPvvsNsv//ve/J0np/QVQbkbAA61eY0Y2bLnY3PrHPouieM35Fnfk7W9/ezp06JDvfe97DZbPmTOn0V917NWrVy655JIMGzaswdc5m3rU9ytr/eEPf5gNGzZk8ODBpWWHHXZYfv/73zdoN2vWrLz44osNljWm74cMGZIkDeZlTJK77rorL730Umk9AAB7p8mTJ6dLly655pprsmnTprzpTW9Knz598vjjj+e4447b7mNLsH3SSSflF7/4RWnUfLJ5jvkf/OAH2+xnZ69VG+O0007L888/n40bN263zi3/ULDlmnlH19Sv5aSTTsrq1atz7733Nlje2B+bbdOmTQYMGFD6Ju+W+4emHvW9YMGCPP744w2WzZgxI1VVVTn22GOTpDTo6JV/Jq88xi317WxtQ4YMyaxZs0qB+xbf+c530qlTJ/O6A3uMEfBAq7flh5luvfXWVFVVpUOHDundu/d2vwI6bNiwtG/fPh/+8Iczbty4vPzyy7n55puzYsWKXdp3ly5dcsUVV+Tzn/98Pvaxj+WDH/xgli5dmtra2tf8GunKlStz0kknZeTIkTn88MNTVVWVuXPn5r777mswQujII4/M3XffnZtvvjn9+/fPfvvtVxpptCvuvvvutG3bNsOGDcuCBQty9dVX56ijjsrZZ59davORj3wkV199da655poMGjQoCxcuzI033tjgR46Sxvf9ySefnM985jNZtWpVTjjhhPz+97/Ptddem2OOOSYf+chHdvmYAABofl26dMn48eMzbty4zJgxI6NGjco3vvGNnHLKKTn55JNzwQUX5PWvf33+7//9v1m0aFEeeeSR/Md//EeS5HOf+1zuvffevPvd784111yTTp065etf/3peeumlbfazs9eqjXHOOefke9/7Xt773vfm0ksvzdve9ra0a9cuf/3rX/Pggw/mzDPPzPve9768+c1vzqhRozJ16tS0a9cuQ4cOzRNPPJEvf/nL20xrsz3nnXdevvrVr+a8887L9ddfnz59+uS///u/8/Of//w1X3vLLbdk1qxZOfXUU9OrV6+8/PLL+fa3v50kGTp0aJLNI/UPPfTQ/PjHP86QIUPStWvXHHTQQa/5zdwd6dGjR84444zU1tame/fuueOOOzJz5sx88YtfLP0A6/HHH583velNueKKK7Jhw4Z06dIl99xzT379619vs73G3Ntce+21+a//+q+cdNJJueaaa9K1a9d873vfy09/+tNMnjx5t/68ARrDCHig1evdu3emTp2axx9/PIMHD87xxx+fn/zkJ9tte/jhh+euu+7KihUrMmLEiHzyk5/M0Ucfna997Wu7vP/rrrsukyZNyv33358zzjgjN9xwQ2655ZbSKJkd6dChQwYMGJDvfve7Offcc3PKKafkm9/8Zj7zmc80GJF/6aWX5gMf+EA++9nP5u1vf/tuT9Vy991358knn8yIESNyzTXX5PTTT8/999+f9u3bl9p8+tOfzqc//elMmzYtp59+eu6666788Ic/zIEHHthgW43p+4qKivzoRz/KZZddlttvvz3vfe978+Uvfzkf+chHMmvWrAbfSgAAYO/0yU9+Mr169cp1112XjRs35qSTTsrvfve7HHjggRk7dmyGDh2af/mXf8kDDzxQCo2TzQM7HnjggRxwwAE5//zz84lPfCJvfetbc/XVV2+zj529Vm2MNm3a5N57781nP/vZ3H333Xnf+96Xs846K1/4whfSoUOHHHnkkaW23/rWt3LZZZdl2rRpOeOMM/LDH/4wd911V7p06fKa++nUqVNmzZqVoUOH5sorr8wHPvCB/PWvf82dd975mq89+uijs2HDhlx77bU55ZRT8pGPfCT/+Mc/cu+992b48OEN6uvUqVPOOOOMHH/88amtrd2lPtmyzylTpuQrX/lKzjzzzPzmN7/JlClTMm7cuFKbNm3a5Cc/+UkOP/zwXHTRRTnvvPNSWVmZG2+8cZvtNebe5k1velPmzJmTN73pTbn44otz1lln5Yknnsjtt9+eT3/607t8TACNVVEURdHcRQAAAAA0tWnTpuWjH/1oFi9evMujuAFgdxgBDwAAAAAAZSCABwAAAACAMjAFDQAAAAAAlIER8AAAAAAAUAYCeAAAAAAAKAMBPAAAAAAAlEHb5i5gV2zatCl///vfU1VVlYqKiuYuBwCAvURRFFm9enV69OiR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0CH9+/fPr371q1dtP3v27PTv3z8dOnTIG97whtxyyy3btLnrrrvylre8JZWVlXnLW96Se+65p9H7LYoitbW16dGjRzp27JjBgwdnwYIFDdqsXbs2n/zkJ3PQQQdl//33zxlnnJG//vWvu9ALO6cl9tX69evzmc98JkceeWT233//9OjRI+edd17+/ve/N9jG4MGDU1FR0eBxzjnn7GJPvLaW2FdJcsEFF2zTD29/+9sbtPG+2uyV/bTl8aUvfanUpjW8rx566KGcfvrp6dGjRyoqKvKjH/1om204X232Wn3lfPW/duZ95Xy12c70lfPVZpMmTcrxxx+fqqqqHHzwwTnrrLPy1FNPNWjTEs9XNJ+Weg3Skt+nLbHPWurn687Wvz2t+d5gZ2t/pdZ8j9CY+l+pNd8vbNES+8x5bd+6h9haS+23lnxua/X3FcU+4M477yzatWtX3HbbbcXChQuLSy+9tNh///2LZ555Zrvt//znPxedOnUqLr300mLhwoXFbbfdVrRr1674z//8z1KbOXPmFG3atCkmTpxYLFq0qJg4cWLRtm3b4re//W2j9vuFL3yhqKqqKu66667iD3/4Q/GhD32o6N69e7Fq1apSm4suuqh4/etfX8ycObN45JFHipNOOqk46qijig0bNrSavnrhhReKoUOHFj/4wQ+KJ598snj44YeLAQMGFP37929Qz6BBg4qPf/zjxbPPPlt6vPDCC03eTztT8yvtyffV+eefX7znPe9p0A/PP/98g3q8rzbbuo+effbZ4tvf/nZRUVFR/M///E+pTWt4X/33f/93cdVVVxV33XVXkaS45557ttmX89Vmr9VXzleNe185X222M33lfLXZySefXNx+++3FE088UTz22GPFqaeeWvTq1at48cUXS21a2vmK5tOSr0Fa6vu0pfZZS/x83VpL7beiaHmftY2pfWut+R5hay35WsV5be+/b9haS+23omi557WiaNn91lLPbe4rimKfCODf9ra3FRdddFGDZYcffnhx5ZVXbrf9uHHjisMPP7zBstGjRxdvf/vbS8/PPvvs4j3veU+DNieffHJxzjnn7PR+N23aVNTU1BRf+MIXSutffvnlonPnzsUtt9xSFMXmE3K7du2KO++8s9Tmb3/7W7HffvsV991332see2O11L7ant/97ndFkgZ/IQcNGlRceumlO3xNU2rJfXX++ecXZ5555g5r977a8fvqzDPPLN797nc3WNYa3ldb296HtfPVzvfV9rTW89XWXu3i2fmqoZ19XzlfbbZs2bIiSTF79uyiKFrm+Yrm01KvQVry+7Sl9tn2NPfn69Zacr+1tM/aLVpyn71Sc3/mbq0lfP7uLfcLW7TUPtse57WG9pZ7iK215H57pZZybmsJfVYUzXtfsddPQbNu3brMnz8/w4cPb7B8+PDhmTNnznZf8/DDD2/T/uSTT868efOyfv36V22zZZs7s9/Fixenrq6uQZvKysoMGjSo1Gb+/PlZv359gzY9evRIv379dlj/rmrJfbU9K1euTEVFRQ488MAGy7/3ve/loIMOyhFHHJErrrgiq1ev3vFB76K9oa9++ctf5uCDD07fvn3z8Y9/PMuWLSut877a/n6fe+65/PSnP82FF164zbp9+X21M5yvdq/+1ni+aozWfr7aFc5X/2vlypVJkq5duyZpeecrmk9LvgZpqe/Tltxn29Ocn69b2xv6raV81m6xN/TZFs39mbu1lvT5+0rOa3v/fcPW9oZ+a2nntWTv6LctWsq5rSX1WXPeV7Td6ZYt1PLly7Nx48ZUV1c3WF5dXZ26urrtvqaurm677Tds2JDly5ene/fuO2yzZZs7s98t/91em2eeeabUpn379unSpctO17+rWnJfvdLLL7+cK6+8MiNHjswBBxxQWn7uueemd+/eqampyRNPPJHx48fn8ccfz8yZM3euE3ZSS++rU045JR/84Adz6KGHZvHixbn66qvz7ne/O/Pnz09lZaX31Q72O3369FRVVWXEiBENlu/r76ud4Xy16/W31vPVznK+2jXOV5sVRZHLLrss73znO9OvX7/Sfra87pXbaY7zFc2nJV+DtNT3aUvus1dq7s/XrbX0fmtJn7VbtPQ+21pzf+ZuraV8/u5oP1te98rttMbz2q5wXtt5LfG8lrT8fttaSzm3tZQ+a+77ir0+gN+ioqKiwfOiKLZZ9lrtX7l8Z7bZVG1eaWfa7KqW3FfJ5h8qOeecc7Jp06bcdNNNDdZ9/OMfL/1/v3790qdPnxx33HF55JFHcuyxx+7wGHZVS+2rD33oQ6X/79evX4477rgceuih+elPf7rNybUx9e+OltpXW/v2t7+dc889Nx06dGiwvLW8r8pR2+7sqxz17Mm+Spyvdobz1a5xvtrskksuye9///v8+te/3u3adrYNe5+WfA3SUt+nLbnPkpb1+bq1ltpvLfGzdouW2mdbaymfuVtr7s/fpqxtd/bVGC25zxLntX3hHmJrLbXfttbSzm3N3WfNfV+x109Bc9BBB6VNmzbb/KvDsmXLtvkXjC1qamq2275t27bp1q3bq7bZss2d2W9NTU2SvGabdevWZcWKFTtd/65qyX21xfr163P22Wdn8eLFmTlzZoN/Fd6eY489Nu3atcsf//jHV23XWHtDX22te/fuOfTQQ0v94H217X5/9atf5amnnsrHPvax1zymfe19tTOcrxpff2s/X+2q1ni+aiznq80++clP5t57782DDz6YQw45pMF+kpZzvqL5tORrkJb6Pm3JfbZFS/l83dre0G9ba87P2i32lj5rCZ+5W2sJn7874ry29983bG1v6LettYTzWrL39FtLOre1hD5rCfcVe30A3759+/Tv33+br0rMnDkzAwcO3O5r3vGOd2zT/v77789xxx2Xdu3avWqbLdvcmf1u+UrH1m3WrVuX2bNnl9r0798/7dq1a9Dm2WefzRNPPLHD+ndVS+6r5H8/lP74xz/mgQceKP2lejULFizI+vXr071799ds2xgtva9e6fnnn8/SpUtL/eB9te1+v/Wtb6V///456qijXvOY9rX31c5wvmpc/c5Xu641nq8aq7Wfr4qiyCWXXJK77747s2bNSu/evRu0b2nnK5pPS74Gaanv05bcZ0nL+nzdWkvvt1dqzs/aLfaWPmsJn7lba8nXKs5re/99w9Zaer+9Uks4ryV7T7+1pHOb+4r/LWavd+eddxbt2rUrvvWtbxULFy4sxo4dW+y///7FX/7yl6IoiuLKK68sPvKRj5Ta//nPfy46depUfOpTnyoWLlxYfOtb3yratWtX/Od//mepzW9+85uiTZs2xRe+8IVi0aJFxRe+8IWibdu2xW9/+9ud3m9RFMUXvvCFonPnzsXdd99d/OEPfyg+/OEPF927dy9WrVpVanPRRRcVhxxySPHAAw8UjzzySPHud7+7OOqoo4oNGza0mr5av359ccYZZxSHHHJI8dhjjxXPPvts6bF27dqiKIriT3/6UzFhwoRi7ty5xeLFi4uf/vSnxeGHH14cc8wxraqvVq9eXVx++eXFnDlzisWLFxcPPvhg8Y53vKN4/etf7321nb+DRVEUK1euLDp16lTcfPPN29TeWt5Xq1evLh599NHi0UcfLZIUU6ZMKR599NHimWeeKbVxvtq5vnK+2vm+cr5q3N/BonC+Koqi+Jd/+Zeic+fOxS9/+csGf7/WrFlTatPSzlc0n5Z8DdJS36cttc9a4ufr3tBvLfGztqX32RYt6TN3ay35WsV5be+/b9gb+q0ln9dacr9t0RLPbe4rimKfCOCLoii+/vWvF4ceemjRvn374thjjy1mz55dWnf++ecXgwYNatD+l7/8ZXHMMccU7du3Lw477LDtvjH/4z/+o3jTm95UtGvXrjj88MOLu+66q1H7LYqi2LRpU3HttdcWNTU1RWVlZXHiiScWf/jDHxq0qa+vLy655JKia9euRceOHYvTTjutWLJkyW70xqtriX21ePHiIsl2Hw8++GBRFEWxZMmS4sQTTyy6du1atG/fvnjjG99Y/Ou//mvx/PPPN03HbEdL7Ks1a9YUw4cPL173utcV7dq1K3r16lWcf/7527xnvK/+1ze+8Y2iY8eOxQsvvLDNutbyvnrwwQe3+/fr/PPPL7VxvtrstfrK+ep/vVZfOV/9r535O1gUzldFUezw79ftt99eatMSz1c0n5Z6DdKS36ctsc9a6ufrztbv3mD7WmKfbdHSPnO31lKvVZzX9o37hq21xH5r6ee1omiZ/bZFSz23tfb7ior/VxAAAAAAANCE9vo54AEAAAAAoCUSwAMAAAAAQBkI4AEAAAAAoAwE8AAAAAAAUAYCeAAAAAAAKAMBPAAAAAAAlIEAHgAAAAAAykAADwAAAAAAZSCABwAAAACAMhDAAwAAAABAGQjgAQAAAACgDP5/Z7Rf8h6lGGIAAAAASUVORK5CYII=",
      "text/plain": [
       "<Figure size 1500x400 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# Drawing both of them\n",
    "figure, axis = plt.subplots(1, 2)\n",
    "figure.set_figheight(4)\n",
    "figure.set_figwidth(15)\n",
    "figure.tight_layout(w_pad = 5)\n",
    "\n",
    "def draw(y, id):\n",
    "    axis[id].hist(y, color='lightgreen', ec='black', bins=10)\n",
    "\n",
    "axis[0].title.set_text(\"Initial distribution\")\n",
    "axis[1].title.set_text(\"Required distribution\")\n",
    "draw(a, 0)\n",
    "draw(b, 1)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case the Wasserstein distance tends to zero as the size of the samples increase."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Wasserstein distance is: 2.003382269162742e-05.\n"
     ]
    }
   ],
   "source": [
    "import pandas as pd\n",
    "from aif360.sklearn.metrics import ot_distance\n",
    "\n",
    "_a = pd.Series(a)\n",
    "_b = pd.Series(b)\n",
    "c = ot_distance(y_true=_a, y_pred=_b, mode='continuous')\n",
    "\n",
    "print(\"Wasserstein distance is: \", c, \".\", sep=\"\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3. Permutations\n",
    "\n",
    "Another example that shows clearly what the permutations in the first formula refer to is the one presented below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "# Initial distribution\n",
    "a = np.array([0., 0.1, 0.1, 0.1, 0.08, 0., 0.1, 0.1, 0.08, 0.08, 0., 0.1, 0.08, 0.08, 0.08, 0.])\n",
    "# Required distribution\n",
    "b = np.array([0., 0.08, 0.08, 0.08, 0.1, 0., 0.08, 0.08, 0.1, 0.1, 0., 0.08, 0.1, 0.1, 0.1, 0.])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAABKcAAAGUCAYAAADgVkHZAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjUuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/NK7nSAAAACXBIWXMAAA9hAAAPYQGoP6dpAABEFElEQVR4nO3deXxTVf7/8XftkoBCgVa6MG0pDEsVWSwqW0FGKQKCCwjICC6gdsAvtBUFBCw4AiPDMB1GoF82GR9uOIKKIyJFlsGhLqxuKKMCRaRCcSlr1/v7g2/zMySFpqScNnk9H488tCfn5p6Te0g+j3ducgMsy7IEAAAAAAAAGHCZ6QEAAAAAAADAfxFOAQAAAAAAwBjCKQAAAAAAABhDOAUAAAAAAABjCKcAAAAAAABgDOEUAAAAAAAAjCGcAgAAAAAAgDGEUwAAAAAAADCGcAoAAAAAAADGEE4BNdjy5csVEBCgbdu2VWn7gIAATZs2zfH3F198oWnTpmn//v0ufe+77z41bdq0Svu5mG0l6cYbb9SNN97o+Hv//v0KCAjQ8uXLPXqcl156SZmZmR5t425f06ZNU0BAgPLz8z16rPOpruceAAB4R3ndVX4LCgpSVFSUhg4dqv/+97+mh+ewadMmBQQEaNOmTZdkf02bNtV9991XpW3PV2d54tSpU5o2bZrHc3a3r6ZNm+rWW2/16HEu5Hw16Ln1OAD3CKcAH5aTk6NRo0Y5/v7iiy80ffp0twHJ1KlT9frrr1/C0VUsKipKOTk56tevn0fbVSWcquq+PFVbnnsAAPzdc889p5ycHK1fv16PPPKIVq9erW7duumnn34yPTRJ0rXXXqucnBxde+21podSJaNGjVJOTo5H25w6dUrTp0/3OJyqyr6q4nw16Ln1OAD3gkwPAED16dSpU6X7Nm/evBpH4hmbzebR2KuitLRUJSUll2RfF1KTnnsAAPxdmzZt1LFjR0lnz+4uLS1VRkaG3njjDd1///2GRyfVr1+/UrXLqVOnVLdu3UswIs/85je/0W9+85tq3Uf53C/Fvi7EdJ0J1BacOQXUMvfdd5+uuOIKff311+rbt6+uuOIKxcTE6NFHH1VhYaFT31+fRrx8+XLdddddkqSePXs6TlkvP83a3VfL5s+fr+7du6tx48a6/PLLdc0112j27NkqLi6u0tgty9Ls2bMVFxcnu92ua6+9Vu+8845LP3engB89elQPPfSQYmJiZLPZdOWVV6pr165av369pLPF49tvv60DBw44nZL/68ebPXu2nn76acXHx8tms2njxo3n/QrhwYMHdeedd6p+/foKDQ3VPffco6NHjzr1qehU7V+fAl+V5/7MmTOaNGmS4uPjFRISoiZNmmjMmDH6+eefXfZz6623au3atbr22mtVp04dtW7dWsuWLavgKAAAAE+UB1U//PCDU/u2bds0YMAANWrUSHa7XR06dNCrr77qsv0HH3ygrl27ym63Kzo6WpMmTdLixYsVEBDgdEZ1ZWoKyf3X+srrw08//VTJycmqV6+ebrrpJklSUVGRnn76abVu3dpRQ91///0uNU1xcbEef/xxRUZGqm7duurWrZs++uijSj9P33//vQYPHqx69eopNDRUQ4YMUV5enks/d1+127Bhg2688UaFhYWpTp06io2N1cCBA3Xq1Cnt379fV155pSRp+vTpjjqq/Dkpf7wdO3Zo0KBBatiwoeODv/N9hfD1119X27ZtZbfb1axZM82bN8/p/vKveZ571vu5z//5alDJ/XH97LPPdNttt6lhw4ay2+1q3769/vGPf7jdz8svv6zJkycrOjpa9evX180336yvvvrK7ZyA2owzp4BaqLi4WAMGDNDIkSP16KOP6t///rf++Mc/KjQ0VE8++aTbbfr166eZM2fqiSee0Pz58x2ngp/vrJ1vvvlGw4YNcwQku3fv1owZM/Tll19WKfyYPn26pk+frpEjR2rQoEE6ePCgHnzwQZWWlqpVq1bn3Xb48OHasWOHZsyYoZYtW+rnn3/Wjh07dOzYMUnSggUL9NBDD+mbb76p8Cty8+bNU8uWLTVnzhzVr19fLVq0OO8+77jjDg0ePFgpKSn6/PPPNXXqVH3xxRf68MMPFRwcXOl5e/rcW5al22+/Xe+9954mTZqkpKQkffLJJ8rIyFBOTo5ycnJks9kc/Xfv3q1HH31UEydOVEREhJYsWaKRI0fqt7/9rbp3717pcQIAAFf79u2TJLVs2dLRtnHjRt1yyy264YYblJWVpdDQUL3yyisaMmSITp065QhOvvjiC910001q2rSpli9frrp162rBggV66aWXvD7OoqIiDRgwQA8//LAmTpyokpISlZWV6bbbbtOWLVv0+OOPq0uXLjpw4IAyMjJ04403atu2bapTp44k6cEHH9Tzzz+v8ePHq1evXvrss89055136vjx4xfc9+nTp3XzzTfr+++/16xZs9SyZUu9/fbbGjJkyAW33b9/v/r166ekpCQtW7ZMDRo00KFDh7R27VoVFRUpKipKa9eu1S233KKRI0c6viJXHliVu/POOzV06FClpKTo5MmT593nrl27lJqaqmnTpikyMlIvvviixo0bp6KiIo0fP/6CY/61ytSgv/bVV1+pS5cuaty4sebNm6ewsDC98MILuu+++/TDDz/o8ccfd+r/xBNPqGvXrlqyZIkKCgo0YcIE9e/fX3v27FFgYKBHYwVqNAtAjfXcc89ZkqyPP/7Y0XbvvfdakqxXX33VqW/fvn2tVq1aObVJsjIyMhx///Of/7QkWRs3bnTZ17333mvFxcVVOJbS0lKruLjYev75563AwEDrxx9/rPS2lmVZP/30k2W326077rjDqf0///mPJcnq0aOHo23fvn2WJOu5555ztF1xxRVWamrqeffRr18/t+Mof7zmzZtbRUVFbu/79b4yMjIsSVZaWppT3xdffNGSZL3wwguOtnOf43JxcXHWvffe6/jbk+d+7dq1liRr9uzZTv1WrFhhSbIWLVrktB+73W4dOHDA0Xb69GmrUaNG1sMPP+yyLwAA4F553fXBBx9YxcXF1vHjx621a9dakZGRVvfu3a3i4mJH39atW1sdOnRwarMsy7r11lutqKgoq7S01LIsyxoyZIhVp04dKy8vz9GnpKTEat26tSXJ2rdvn6O9sjXFxo0bXWqK8vpw2bJlTtu+/PLLliRr5cqVTu0ff/yxJclasGCBZVmWtWfPnvPWPr/evzsLFy60JFlvvvmmU/uDDz5YYZ1V7rXXXrMkWbt27arw8Y8ePVrh81P+eE8++WSF9/1aXFycFRAQ4LK/Xr16WfXr17dOnjxpWdb/Xw+/PkaW5f75r6gGtSzX4zp06FDLZrNZubm5Tv369Olj1a1b1/r555+d9tO3b1+nfq+++qolycrJyXG7P6C24mt9QC0UEBCg/v37O7W1bdtWBw4c8Op+du7cqQEDBigsLEyBgYEKDg7WiBEjVFpaqr1793r0WDk5OTpz5ox+//vfO7V36dJFcXFxF9z++uuv1/Lly/X000/rgw8+qNJXCwcMGODRGU/njnXw4MEKCgrSxo0bPd63JzZs2CBJLlfGueuuu3T55Zfrvffec2pv3769YmNjHX/b7Xa1bNnS6+sBAAB/0KlTJwUHB6tevXq65ZZb1LBhQ7355psKCjr7pZOvv/5aX375paNOKCkpcdz69u2rw4cPO752tXHjRt10002KiIhwPH5gYGClziiqioEDBzr9/a9//UsNGjRQ//79ncbZvn17RUZGOr6aVl7bVFT7XMjGjRtVr149DRgwwKl92LBhF9y2ffv2CgkJ0UMPPaR//OMf+vbbby+4jTvnzv18rr76arVr186pbdiwYSooKNCOHTuqtP/K2rBhg2666SbFxMQ4td933306deqUyw+4n/uctm3bVpKo8+BzCKeAWqhu3bqy2+1ObTabTWfOnPHaPnJzc5WUlKRDhw7pb3/7m7Zs2aKPP/5Y8+fPl3T29G1PlH/9LjIy0uU+d23nWrFihe69914tWbJEnTt3VqNGjTRixAi3v2VQkaioqMoP2M24goKCFBYW5phLdTl27JiCgoJcTlcPCAhQZGSky/7DwsJcHsNms3l8jAAAgPT888/r448/1oYNG/Twww9rz549uvvuux33l//21Pjx4xUcHOx0Gz16tCQpPz9f0tn39KrWPp6qW7eu6tev79T2ww8/6Oeff1ZISIjLWPPy8pzG6W5c5bXPhRw7dswpgCtXmXk2b95c69evV+PGjTVmzBg1b95czZs319/+9rcLbvtrntR55zsml6LOczfW6Ohot/s/9/kv/2kH6jz4Gn5zCoBbb7zxhk6ePKlVq1Y5ndm0a9euKj1e+RuruzApLy/P5QfBzxUeHq7MzExlZmYqNzdXq1ev1sSJE3XkyBGtXbu2UmOo6AcxK5KXl6cmTZo4/i4pKdGxY8ecigSbzebyQ/TSxRU2YWFhKikp0dGjR50CKsuylJeXp+uuu67Kjw0AAM4vISHB8SPoPXv2VGlpqZYsWaLXXntNgwYNUnh4uCRp0qRJuvPOO90+RvlvaYaFhVVY+5zrYmsKd3VOeHi4wsLCKqyV6tWr5xhn+bjc1T4XEhYW5vbH0yv7IWJSUpKSkpJUWlqqbdu26e9//7tSU1MVERGhoUOHVuoxPKnzzndMyp+L8g+Czz0m5YFeVYWFhenw4cMu7d9//70kOdYX4G84cwrwI5580lL+Bv/rH962LEuLFy+u0r47deoku92uF1980al969atHp+WHBsbq0ceeUS9evVyOvXa22cLnTvWV199VSUlJbrxxhsdbU2bNtUnn3zi1G/Dhg06ceKEU5snz3351XVeeOEFp/aVK1fq5MmTjvsBAED1mz17tho2bKgnn3xSZWVlatWqlVq0aKHdu3erY8eObm/loU/Pnj313nvvOV3pr7S0VCtWrHDZT2VrCk/ceuutOnbsmEpLS92OszxEK69tKqp9LqRnz546fvy4Vq9e7dTu6Q+/BwYG6oYbbnCcqV9e53n7bKHPP/9cu3fvdmp76aWXVK9ePceFa8o/OD33mJw7x/LxVXZsN910kzZs2OAIo8o9//zzqlu3rjp16lTZaQA+hTOnAD/Spk0bSdKiRYtUr1492e12xcfHuz1du1evXgoJCdHdd9+txx9/XGfOnNHChQv1008/VWnfDRs21Pjx4/X0009r1KhRuuuuu3Tw4EHHVVLO55dfflHPnj01bNgwtW7dWvXq1dPHH3+stWvXOn1iec0112jVqlVauHChEhMTddlllzk++ayKVatWKSgoSL169XJcra9du3YaPHiwo8/w4cM1depUPfnkk+rRo4e++OILPfvsswoNDXV6LE+f+969e2vChAkqKChQ165dHVfr69Chg4YPH17lOQEAAM80bNhQkyZN0uOPP66XXnpJ99xzj/73f/9Xffr0Ue/evXXfffepSZMm+vHHH7Vnzx7t2LFD//znPyVJU6ZM0erVq/W73/1OTz75pOrWrav58+e7vZpcZWsKTwwdOlQvvvii+vbtq3Hjxun6669XcHCwvvvuO23cuFG33Xab7rjjDiUkJOiee+5RZmamgoODdfPNN+uzzz5zXOH4QkaMGKG//vWvGjFihGbMmKEWLVpozZo1evfddy+4bVZWljZs2KB+/fopNjZWZ86ccVwV+uabb5Z09gyvuLg4vfnmm7rpppvUqFEjhYeHX/DM+4pER0drwIABmjZtmqKiovTCCy8oOztbzzzzjOrWrStJuu6669SqVSuNHz9eJSUlatiwoV5//XW9//77Lo/nSQ2akZGhf/3rX+rZs6eefPJJNWrUSC+++KLefvttzZ49+6KON1Crmf5FdgAVq+hqfZdffrlLX3dXI5Gbq5pkZmZa8fHxVmBgoNPVU9xdce+tt96y2rVrZ9ntdqtJkybWY489Zr3zzjturxBzoav1WZZllZWVWbNmzbJiYmKs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H35YAQEByszMvGTj85bKzHPPnj0aMGCAQkNDVa9ePXXq1Em5ubmXfrDwKdRrvol6rfbz1VpNol6TqNeo186PcMqLVqxYodTUVE2ePFk7d+5UUlKS+vTp41NF9ObNmzVmzBh98MEHys7OVklJiZKTk3Xy5EnTQ6s2H3/8sRYtWqS2bduaHkq1+Omnn9S1a1cFBwfrnXfe0RdffKG//OUvatCggemhed0zzzyjrKwsPfvss9qzZ49mz56tP//5z/r73/9uemgX5eTJk2rXrp2effZZt/fPnj1bc+fO1bPPPquPP/5YkZGR6tWrl44fP36JR3pxzjfPU6dOaceOHZo6dap27NihVatWae/evRowYICBkV68Cx3Tcm+88YY+/PBDRUdHX6KRedeF5vnNN9+oW7duat26tTZt2qTdu3dr6tSpstvtl3ik8CXUa76Jes03+GqtJlGvSdRr1GsXYMFrrr/+eislJcWprXXr1tbEiRMNjaj6HTlyxJJkbd682fRQqsXx48etFi1aWNnZ2VaPHj2scePGmR6S102YMMHq1q2b6WFcEv369bMeeOABp7Y777zTuueeewyNyPskWa+//rrj77KyMisyMtL605/+5Gg7c+aMFRoaamVlZRkYoXecO093PvroI0uSdeDAgUszqGpS0Vy/++47q0mTJtZnn31mxcXFWX/9618v+di8yd08hwwZ4lP/PlEzUK/5Huo13+EPtZplUa/9GvVa7VKd9RpnTnlJUVGRtm/fruTkZKf25ORkbd261dCoqt8vv/wiSWrUqJHhkVSPMWPGqF+/frr55ptND6XarF69Wh07dtRdd92lxo0bq0OHDlq8eLHpYVWLbt266b333tPevXslSbt379b777+vvn37Gh5Z9dm3b5/y8vKcXptsNpt69Ojh069N0tnXp4CAAJ/7VFmSysrKNHz4cD322GO6+uqrTQ+nWpSVlentt99Wy5Yt1bt3bzVu3Fg33HDDeU+ZBy6Eeo16rbbyl3rNH2s1iXqNeq328ma9RjjlJfn5+SotLVVERIRTe0REhPLy8gyNqnpZlqX09HR169ZNbdq0MT0cr3vllVe0fft2zZo1y/RQqtW3336rhQsXqkWLFnr33XeVkpKisWPH6vnnnzc9NK+bMGGC7r77brVu3VrBwcHq0KGDUlNTdffdd5seWrUpf/3xp9cmSTpz5owmTpyoYcOGqX79+qaH43XPPPOMgoKCNHbsWNNDqTZHjhzRiRMn9Kc//Um33HKL1q1bpzvuuEN33nmnNm/ebHp4qKWo16jXait/qdf8sVaTqNeo12ovb9ZrQdU0Rr8VEBDg9LdlWS5tvuKRRx7RJ598ovfff9/0ULzu4MGDGjdunNatW+fzv21SVlamjh07aubMmZKkDh066PPPP9fChQs1YsQIw6PzrhUrVuiFF17QSy+9pKuvvlq7du1SamqqoqOjde+995oeXrXyp9em4uJiDR06VGVlZVqwYIHp4Xjd9u3b9be//U07duzw2WMoyfHjt7fddpvS0tIkSe3bt9fWrVuVlZWlHj16mBweajl/ek2kXvMN/lKv+XOtJvnXaxP1mm/wZr3GmVNeEh4ersDAQJdk+8iRIy4JuC/4n//5H61evVobN27Ub37zG9PD8brt27fryJEjSkxMVFBQkIKCgrR582bNmzdPQUFBKi0tNT1Er4mKitJVV13l1JaQkOBTPwxb7rHHHtPEiRM1dOhQXXPNNRo+fLjS0tJ8+tPWyMhISfKb16bi4mINHjxY+/btU3Z2tk9+CrdlyxYdOXJEsbGxjtenAwcO6NFHH1XTpk1ND89rwsPDFRQU5DevT7g0qNd8C/Wa770e+mOtJlGvUa/VXt6s1winvCQkJESJiYnKzs52as/OzlaXLl0Mjcr7LMvSI488olWrVmnDhg2Kj483PaRqcdNNN+nTTz/Vrl27HLeOHTvq97//vXbt2qXAwEDTQ/Sarl27ulxeeu/evYqLizM0oupz6tQpXXaZ88teYGCgT1yeuCLx8fGKjIx0em0qKirS5s2bfeq1Sfr/hc5///tfrV+/XmFhYaaHVC2GDx+uTz75xOn1KTo6Wo899pjeffdd08PzmpCQEF133XV+8/qES4N6zbdQr/ne66E/1moS9Zovol7z/PWJr/V5UXp6uoYPH66OHTuqc+fOWrRokXJzc5WSkmJ6aF4zZswYvfTSS3rzzTdVr149R7ofGhqqOnXqGB6d99SrV8/ldxkuv/xyhYWF+dzvNaSlpalLly6aOXOmBg8erI8++kiLFi3SokWLTA/N6/r3768ZM2YoNjZWV199tXbu3Km5c+fqgQceMD20i3LixAl9/fXXjr/37dunXbt2qVGjRoqNjVVqaqpmzpypFi1aqEWLFpo5c6bq1q2rYcOGGRy15843z+joaA0aNEg7duzQv/71L5WWljpenxo1aqSQkBBTw66SCx3Tcwu54OBgRUZGqlWrVpd6qBflQvN87LHHNGTIEHXv3l09e/bU2rVr9dZbb2nTpk3mBo1aj3qNeq028pd6zVdrNYl6jXqNeu2CLvp6f3Ayf/58Ky4uzgoJCbGuvfZan7tkryS3t+eee8700Kqdr16a2LIs66233rLatGlj2Ww2q3Xr1taiRYtMD6laFBQUWOPGjbNiY2Mtu91uNWvWzJo8ebJVWFhoemgXZePGjW7/Xd57772WZZ29PHFGRoYVGRlp2Ww2q3v37tann35qdtBVcL557tu3r8LXp40bN5oeuscudEzPVVsvTVyZeS5dutT67W9/a9ntdqtdu3bWG2+8YW7A8BnUa76Leq1289VazbKo16jXqNcuJMCyLMuzOAsAAAAAAADwDn5zCgAAAAAAAMYQTgEAAAAAAMAYwikAAAAAAAAYQzgFAAAAAAAAYwinAAAAAAAAYAzhFAAAAAAAAIwhnAIAAAAAAIAxhFMAAAAAAAAwhnAKAAAAAAAAxhBOAQAAAAAAwBjCKQAAAAAAABjz/wAcfxIVwbXtywAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 1200x400 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# Drawing both of them\n",
    "figure, axis = plt.subplots(1, 2)\n",
    "figure.set_figheight(4)\n",
    "figure.set_figwidth(12)\n",
    "figure.tight_layout(w_pad = 5)\n",
    "\n",
    "def draw(y, id):\n",
    "    x = np.array(range(0, np.size(y)))\n",
    "    axis[id].bar(x, y, color=\"lightgreen\", ec='black')\n",
    "    axis[id].scatter(x, y, color=\"orange\")\n",
    "\n",
    "axis[0].title.set_text(\"Initial distribution\")\n",
    "axis[1].title.set_text(\"Required distribution\")\n",
    "draw(a, 0)\n",
    "draw(b, 1)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There, since we can go from the initial distribution to the desired one just using permutations, the Wasserstein distance is zero."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.0\n"
     ]
    }
   ],
   "source": [
    "import pandas as pd\n",
    "from aif360.sklearn.metrics import ot_distance\n",
    "\n",
    "_a = pd.Series(a)\n",
    "_b = pd.Series(b)\n",
    "c = ot_distance(_a, _b, mode='continuous')\n",
    "\n",
    "print(c)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4. Extreme case\n",
    "\n",
    "One more example that is closer to our case is \"normalization\". It's an explanation of why the maximum Wasserstein distance we can get in our case is approaching 1 (with increasing the size of the sample), that is, it is normalized. We get this in the case that all our population has a value 0 of the 2-year recidivism (which is presented in the paragraph \"Compas Dataset\") and the classifier fails massively in all the cases labeling all with a 1. That would be the worst-case scenario."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "# Initial distribution\n",
    "a = np.array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.001])\n",
    "# Required distribution\n",
    "b = np.array([0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625, 0.0625])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAABLgAAAGUCAYAAAA285u8AAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjUuMywgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy/NK7nSAAAACXBIWXMAAA9hAAAPYQGoP6dpAABVNklEQVR4nO3de1yUdd7/8TdxmNFSSlxBChDdCsxSg1ahEL1NTC076Eq1YaVW3NQqkKVopnlXpLkuax74WZrrr1La0LKNNbGUtZXa5GAnN6slMYM1rEQzOV6/P/wxd+MMyCA6Xszr+Xhcj73nO5/r+ny/w0if+8N18DIMwxAAAAAAAABgUue5ewIAAAAAAADA6aDBBQAAAAAAAFOjwQUAAAAAAABTo8EFAAAAAAAAU6PBBQAAAAAAAFOjwQUAAAAAAABTo8EFAAAAAAAAU6PBBQAAAAAAAFOjwQUAAAAAAABTo8EFeIA1a9bIy8tLu3btatP+Xl5emjdvnu31Z599pnnz5unrr792iL3nnnvUq1evNuU5nX0laejQoRo6dKjt9ddffy0vLy+tWbPGpeO88sorysrKcmkfZ7nmzZsnLy8vVVVVuXSslpypzx4AALSPprqrafPx8VHPnj11++2364svvnD39Gy2b98uLy8vbd++/azk69Wrl+6555427dtSneWKY8eOad68eS6v2VmuXr166cYbb3TpOKfSUg16cj0OwBENLgCnVFhYqClTpthef/bZZ3riiSecNlnmzJmjjRs3nsXZNa9nz54qLCzUmDFjXNqvLQ2utuZylVk+ewAAPN2LL76owsJCbd26VQ899JA2bdqk6667Tj/88IO7pyZJuvrqq1VYWKirr77a3VNpkylTpqiwsNClfY4dO6YnnnjC5QZXW3K1RUs16Mn1OABHPu6eAIBz3+DBg1sd26dPnzM4E9dYLBaX5t4WDQ0Nqq+vPyu5TuVc+uwBAPB0/fr1U3R0tKQTZ5k3NDRo7ty5ev3113Xvvfe6eXZS165dW1W7HDt2TJ07dz4LM3LNJZdcoksuueSM5mha+9nIdSrurjMBM+AMLsBD3XPPPbrgggv05ZdfavTo0brgggsUEhKihx9+WDU1NXaxvzwles2aNfrtb38rSRo2bJjt9PumU8adXSa3bNkyDRkyRD169ND555+vK6+8UgsXLlRdXV2b5m4YhhYuXKiwsDBZrVZdffXV+tvf/uYQ5+x09u+++07333+/QkJCZLFY9Ktf/UrXXnuttm7dKulEAfrWW29p3759dpcX/PJ4Cxcu1JNPPqnw8HBZLBZt27atxcsh9+/fr9tuu01du3aVv7+/7rrrLn333Xd2Mc2ddv7L0/nb8tkfP35cGRkZCg8Pl5+fny6++GI9+OCD+vHHHx3y3Hjjjdq8ebOuvvpqderUSREREVq9enUzPwUAAOCKpmbXf/7zH7vxXbt2aezYserWrZusVqsGDhyoV1991WH/999/X9dee62sVquCg4OVkZGh559/Xl5eXnZndremppCcX6LYVB9+/PHHSkhIUJcuXTR8+HBJUm1trZ588klFRETYaqh7773Xoaapq6vTo48+qqCgIHXu3FnXXXed/vnPf7b6c/r22281YcIEdenSRf7+/kpMTFRlZaVDnLPLBt99910NHTpUAQEB6tSpk0JDQzVu3DgdO3ZMX3/9tX71q19Jkp544glbHdX0mTQdr7i4WOPHj9dFF11k++NhS5dDbty4UVdddZWsVqt69+6tJUuW2L3fdMnqyWffn/z5t1SDSs5/rp988oluvvlmXXTRRbJarRowYID+/Oc/O82zbt06zZ49W8HBweratauuv/56ff75507XBJgVZ3ABHqyurk5jx47V5MmT9fDDD+vvf/+7/ud//kf+/v56/PHHne4zZswYPf3005o1a5aWLVtmO629pbOHvvrqK9155522Jsvu3bv11FNP6V//+lebGihPPPGEnnjiCU2ePFnjx4/X/v37dd9996mhoUGXX355i/smJSWpuLhYTz31lC677DL9+OOPKi4u1qFDhyRJy5cv1/3336+vvvqq2cv9lixZossuu0yLFi1S165ddemll7aY89Zbb9WECROUnJysTz/9VHPmzNFnn32mDz74QL6+vq1et6ufvWEYuuWWW/TOO+8oIyNDcXFx+uijjzR37lwVFhaqsLBQFovFFr979249/PDDmjlzpgIDA/XCCy9o8uTJ+vWvf60hQ4a0ep4AAMBRWVmZJOmyyy6zjW3btk033HCDBg0apOzsbPn7+2v9+vVKTEzUsWPHbM2Xzz77TMOHD1evXr20Zs0ade7cWcuXL9crr7zS7vOsra3V2LFj9cADD2jmzJmqr69XY2Ojbr75Zu3YsUOPPvqoYmNjtW/fPs2dO1dDhw7Vrl271KlTJ0nSfffdp7Vr12r69OkaMWKEPvnkE9122206cuTIKXP//PPPuv766/Xtt98qMzNTl112md566y0lJiaect+vv/5aY8aMUVxcnFavXq0LL7xQBw4c0ObNm1VbW6uePXtq8+bNuuGGGzR58mTb5X5NTa8mt912m26//XYlJyfrp59+ajFnaWmpUlNTNW/ePAUFBenll1/WtGnTVFtbq+nTp59yzr/Umhr0lz7//HPFxsaqR48eWrJkiQICAvTSSy/pnnvu0X/+8x89+uijdvGzZs3StddeqxdeeEHV1dWaMWOGbrrpJu3Zs0fe3t4uzRU4ZxkAOrwXX3zRkGR8+OGHtrG7777bkGS8+uqrdrGjR482Lr/8crsxScbcuXNtr//yl78Ykoxt27Y55Lr77ruNsLCwZufS0NBg1NXVGWvXrjW8vb2N77//vtX7GoZh/PDDD4bVajVuvfVWu/F//OMfhiQjPj7eNlZWVmZIMl588UXb2AUXXGCkpqa2mGPMmDFO59F0vD59+hi1tbVO3/tlrrlz5xqSjLS0NLvYl19+2ZBkvPTSS7axkz/jJmFhYcbdd99te+3KZ79582ZDkrFw4UK7uJycHEOSsXLlSrs8VqvV2Ldvn23s559/Nrp162Y88MADDrkAAIBzTXXX+++/b9TV1RlHjhwxNm/ebAQFBRlDhgwx6urqbLERERHGwIED7cYMwzBuvPFGo2fPnkZDQ4NhGIaRmJhodOrUyaisrLTF1NfXGxEREYYko6yszDbe2ppi27ZtDjVFU324evVqu33XrVtnSDJyc3Ptxj/88ENDkrF8+XLDMAxjz549LdY+v8zvzIoVKwxJxhtvvGE3ft999zVbZzV57bXXDElGaWlps8f/7rvvmv18mo73+OOPN/veL4WFhRleXl4O+UaMGGF07drV+OmnnwzD+N/vwy9/Robh/PNvrgY1DMef6+23325YLBajvLzcLm7UqFFG586djR9//NEuz+jRo+3iXn31VUOSUVhY6DQfYEZcogh4MC8vL9100012Y1dddZX27dvXrnlKSko0duxYBQQEyNvbW76+vpo4caIaGhq0d+9el45VWFio48eP63e/+53deGxsrMLCwk65/29+8xutWbNGTz75pN5///02XSY5duxYl868OnmuEyZMkI+Pj7Zt2+Zyble8++67kuTwxKLf/va3Ov/88/XOO+/YjQ8YMEChoaG211arVZdddlm7fx8AAPAEgwcPlq+vr7p06aIbbrhBF110kd544w35+Jy4iObLL7/Uv/71L1udUF9fb9tGjx6tiooK2yVk27Zt0/DhwxUYGGg7vre3d6vObGqLcePG2b3+61//qgsvvFA33XST3TwHDBigoKAg22V2TbVNc7XPqWzbtk1dunTR2LFj7cbvvPPOU+47YMAA+fn56f7779ef//xn/fvf/z7lPs6cvPaWXHHFFerfv7/d2J133qnq6moVFxe3KX9rvfvuuxo+fLhCQkLsxu+55x4dO3bM4ab4J3+mV111lSRR56FDocEFeLDOnTvLarXajVksFh0/frzdcpSXlysuLk4HDhzQn/70J+3YsUMffvihli1bJunEqeiuaLqUMCgoyOE9Z2Mny8nJ0d13360XXnhBMTEx6tatmyZOnOj03g7N6dmzZ+sn7GRePj4+CggIsK3lTDl06JB8fHwcTr338vJSUFCQQ/6AgACHY1gsFpd/RgAAQFq7dq0+/PBDvfvuu3rggQe0Z88e3XHHHbb3m+7FNX36dPn6+tptKSkpkqSqqipJJ/6b3tbax1WdO3dW165d7cb+85//6Mcff5Sfn5/DXCsrK+3m6WxeTbXPqRw6dMiuidekNevs06ePtm7dqh49eujBBx9Unz591KdPH/3pT3865b6/5Eqd19LP5GzUec7mGhwc7DT/yZ9/020qqPPQkXAPLgBn1Ouvv66ffvpJGzZssDvDqrS0tE3Ha/qPs7OGVGVlpcNN1k/WvXt3ZWVlKSsrS+Xl5dq0aZNmzpypgwcPavPmza2aQ3M3GW1OZWWlLr74Ytvr+vp6HTp0yK7QsFgsDjf3l06vOAoICFB9fb2+++47uyaXYRiqrKzUNddc0+ZjAwCAlkVGRtpuLD9s2DA1NDTohRde0Guvvabx48ere/fukqSMjAzddtttTo/RdG/RgICAZmufk51uTeGszunevbsCAgKarZW6dOlim2fTvJzVPqcSEBDg9Ib0rf1DZFxcnOLi4tTQ0KBdu3bpueeeU2pqqgIDA3X77be36hiu1Hkt/UyaPoumPyaf/DNpagq2VUBAgCoqKhzGv/32W0myfb8AT8IZXABc5spffJqKhF/ezNwwDD3//PNtyj148GBZrVa9/PLLduM7d+50+RTr0NBQPfTQQxoxYoTdaeTtfdbSyXN99dVXVV9fr6FDh9rGevXqpY8++sgu7t1339XRo0ftxlz57JueevTSSy/Zjefm5uqnn36yvQ8AAM68hQsX6qKLLtLjjz+uxsZGXX755br00ku1e/duRUdHO92aGkfDhg3TO++8Y/cExoaGBuXk5DjkaW1N4Yobb7xRhw4dUkNDg9N5NjXimmqb5mqfUxk2bJiOHDmiTZs22Y27ejN9b29vDRo0yHbFQFOd195nLX366afavXu33dgrr7yiLl262B4G1PTH15N/JievsWl+rZ3b8OHD9e6779oaWk3Wrl2rzp07a/Dgwa1dBtBhcAYXAJf169dPkrRy5Up16dJFVqtV4eHhTk89HzFihPz8/HTHHXfo0Ucf1fHjx7VixQr98MMPbcp90UUXafr06XryySc1ZcoU/fa3v9X+/fttT69pyeHDhzVs2DDdeeedioiIUJcuXfThhx9q8+bNdn85vfLKK7VhwwatWLFCUVFROu+882x/gW2LDRs2yMfHRyNGjLA9RbF///6aMGGCLSYpKUlz5szR448/rvj4eH322WdaunSp/P397Y7l6mc/cuRIzZgxQ9XV1br22mttT1EcOHCgkpKS2rwmAADgmosuukgZGRl69NFH9corr+iuu+7S//k//0ejRo3SyJEjdc899+jiiy/W999/rz179qi4uFh/+ctfJEmPPfaYNm3apP/6r//S448/rs6dO2vZsmVOn/LX2prCFbfffrtefvlljR49WtOmTdNvfvMb+fr66ptvvtG2bdt0880369Zbb1VkZKTuuusuZWVlydfXV9dff70++eQT25OnT2XixIn64x//qIkTJ+qpp57SpZdeqry8PL399tun3Dc7O1vvvvuuxowZo9DQUB0/ftz2tO7rr79e0okzzcLCwvTGG29o+PDh6tatm7p3737KKwCaExwcrLFjx2revHnq2bOnXnrpJeXn52vBggXq3LmzJOmaa67R5ZdfrunTp6u+vl4XXXSRNm7cqPfee8/heK7UoHPnztVf//pXDRs2TI8//ri6deuml19+WW+99ZYWLlx4Wj9vwLTcfZd7AGdec09RPP/88x1inT0lRk6eNpOVlWWEh4cb3t7edk+1cfYkxDfffNPo37+/YbVajYsvvth45JFHjL/97W9On9xzqqcoGoZh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AAAAAACAqdHgAgAAgFPLly9XeHi4rFaroqKitGPHjhbjCwoKFBUVJavVqt69eys7O9sh5scff9SDDz6onj17ymq1KjIyUnl5eWdqCQAAwEPQ4AIAAICDnJwcpaamavbs2SopKVFcXJxGjRpl9zChXyorK9Po0aMVFxenkpISzZo1S1OnTlVubq4tpra2ViNGjNDXX3+t1157TZ9//rmef/55XXzxxWdrWQAAoINq003mAQAA0LEtXrxYkydP1pQpUyRJWVlZevvtt7VixQplZmY6xGdnZys0NFRZWVmSpMjISO3atUuLFi2yPT179erV+v7777Vz5075+vpKku1J3AAAAKeDM7gAAABgp7a2VkVFRUpISLAbT0hI0M6dO53uU1hY6BA/cuRI7dq1S3V1dZKkTZs2KSYmRg8++KACAwPVr18/Pf3002poaGh2LjU1NaqurrbbAAAATkaDCwAAAHaqqqrU0NCgwMBAu/HAwEBVVlY63aeystJpfH19vaqqqiRJ//73v/Xaa6+poaFBeXl5euyxx/SHP/xBTz31VLNzyczMlL+/v20LCQk5zdUBAICOiAYXAAAAnPLy8rJ7bRiGw9ip4n853tjYqB49emjlypWKiorS7bffrtmzZ2vFihXNHjMjI0OHDx+2bfv372/rcgAAQAfGPbgAAABgp3v37vL29nY4W+vgwYMOZ2k1CQoKchrv4+OjgIAASVLPnj3l6+srb29vW0xkZKQqKytVW1srPz8/h+NaLBZZLJbTXRIAAOjgOIMLAAAAdvz8/BQVFaX8/Hy78fz8fMXGxjrdJyYmxiF+y5Ytio6Ott1Q/tprr9WXX36pxsZGW8zevXvVs2dPp80tAACA1qLBBQAAAAfp6el64YUXtHr1au3Zs0dpaWkqLy9XcnKypBOXDk6cONEWn5ycrH379ik9PV179uzR6tWrtWrVKk2fPt0W89///d86dOiQpk2bpr179+qtt97S008/rQcffPCsrw8AAHQsXKIIAAAAB4mJiTp06JDmz5+viooK9evXT3l5eQoLC5MkVVRUqLy83BYfHh6uvLw8paWladmyZQoODtaSJUs0btw4W0xISIi2bNmitLQ0XXXVVbr44os1bdo0zZgx46yvDwAAdCw0uAAAAOBUSkqKUlJSnL63Zs0ah7H4+HgVFxe3eMyYmBi9//777TE9AAAA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",
      "text/plain": [
       "<Figure size 1200x400 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# Drawing both of them\n",
    "figure, axis = plt.subplots(1, 2)\n",
    "figure.set_figheight(4)\n",
    "figure.set_figwidth(12)\n",
    "figure.tight_layout(w_pad = 5)\n",
    "\n",
    "def draw(y, id):\n",
    "    x = np.array(range(0, np.size(y)))\n",
    "    axis[id].bar(x, y, color=\"lightgreen\", ec='black')\n",
    "    axis[id].scatter(x, y, color=\"orange\")\n",
    "\n",
    "axis[0].title.set_text(\"Initial distribution\")\n",
    "axis[1].title.set_text(\"Required distribution\")\n",
    "draw(a, 0)\n",
    "draw(b, 1)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.9375\n"
     ]
    }
   ],
   "source": [
    "import pandas as pd\n",
    "from aif360.sklearn.metrics import ot_distance\n",
    "\n",
    "_a = pd.Series(a)\n",
    "_b = pd.Series(b)\n",
    "c = ot_distance(_a, _b)\n",
    "\n",
    "print(c)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Usage\n",
    "\n",
    "The type of outcomes must be provided using the `mode` keyword argument. The definition for the four types of outcomes supported are provided below:\n",
    "- Binary: Yes/no outcomes. Outcomes must 0 or 1.\n",
    "- Continuous: Continuous outcomes. Outcomes could be any real number.\n",
    "- Nominal: Multiclass outcomes with no rank or order between them. Outcomes must be a finite set of integers.\n",
    "- Ordinal: Multiclass outcomes that are ranked in a specific order. Outcomes must be positive integers."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Compas Dataset"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll demonstrate finding the scanning for bias with earth_movers_distance using the Compas dataset. We scan for bias in the predictions of an `sklearn` logistic regression model with respect to different groups."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aif360.algorithms.preprocessing.optim_preproc_helpers.data_preproc_functions import load_preproc_data_compas\n",
    "\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "np.random.seed(0)\n",
    "dataset_orig = load_preproc_data_compas()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We scan for bias at first with respect to `sex`, and then `age`.\n",
    "\n",
    "To scan for bias with respect for a feature that is one-hot encoded - in this case, age category - we need to convert it to nominal or ordinal format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "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>sex</th>\n",
       "      <th>race</th>\n",
       "      <th>priors_count=0</th>\n",
       "      <th>priors_count=1 to 3</th>\n",
       "      <th>priors_count=More than 3</th>\n",
       "      <th>c_charge_degree=F</th>\n",
       "      <th>c_charge_degree=M</th>\n",
       "      <th>age_cat</th>\n",
       "      <th>two_year_recid</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   sex  race  priors_count=0  priors_count=1 to 3  priors_count=More than 3  \\\n",
       "0  0.0   0.0             1.0                  0.0                       0.0   \n",
       "1  0.0   0.0             0.0                  0.0                       1.0   \n",
       "2  0.0   1.0             0.0                  0.0                       1.0   \n",
       "3  1.0   1.0             1.0                  0.0                       0.0   \n",
       "4  0.0   1.0             1.0                  0.0                       0.0   \n",
       "\n",
       "   c_charge_degree=F  c_charge_degree=M  age_cat  two_year_recid  \n",
       "0                1.0                0.0        1             1.0  \n",
       "1                1.0                0.0        0             1.0  \n",
       "2                1.0                0.0        1             1.0  \n",
       "3                0.0                1.0        1             0.0  \n",
       "4                1.0                0.0        1             0.0  "
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dataset_orig_df = pd.DataFrame(dataset_orig.features, columns=dataset_orig.feature_names)\n",
    "# Binning the features corresponding to age ('reshaping' them into one ordinal column)\n",
    "age_cat_cols = ['age_cat=Less than 25', 'age_cat=25 to 45', 'age_cat=Greater than 45']\n",
    "age_cat = np.argmax(dataset_orig_df[age_cat_cols].values, axis=1).reshape(-1, 1)\n",
    "df = dataset_orig_df.drop(age_cat_cols, axis=1)\n",
    "df['age_cat'] = age_cat\n",
    "df['two_year_recid'] = dataset_orig.labels\n",
    "df.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Measuring bias with respect to `sex`\n",
    "\n",
    "\n",
    "We train a linear regression model on the dataset, and scan its results for bias with respect to `sex` using `earth_movers_distance`.\n",
    "\n",
    "The arguments are as follows:\n",
    "- `ground_truth`: ground truth labels;\n",
    "- `classifier`: predicted labels;\n",
    "- `prot_attr`: the values of the sensitive attributes (with respect to which the classifier may be introducing bias);\n",
    "- `num_iters`: maximum number of iterations performed when calculating the Earth Mover's Distance;\n",
    "- `mode`: mode of the labels, one of binary, nominal, ordinal and continious; in our case the labels are binary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aif360.sklearn.metrics import ot_distance\n",
    "from sklearn.linear_model import LogisticRegression\n",
    "from sklearn.model_selection import train_test_split\n",
    "\n",
    "X = df.drop('two_year_recid', axis=1)\n",
    "y = df['two_year_recid']\n",
    "clf = LogisticRegression(solver='lbfgs', max_iter=10000, C=1.0, penalty='l2')\n",
    "clf.fit(X, y)\n",
    "preds = pd.Series(clf.predict_proba(X)[:,0])\n",
    "\n",
    "ot_val1 = ot_distance(y_true=y, y_pred=preds, prot_attr=df['sex'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "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>sex</th>\n",
       "      <th>ot_val</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.000209</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1.0</td>\n",
       "      <td>0.001647</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   sex    ot_val\n",
       "0  0.0  0.000209\n",
       "1  1.0  0.001647"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "bs1 = pd.DataFrame({\"sex\": ot_val1.keys(), \"ot_val\": ot_val1.values()})\n",
    "display(bs1)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We get the bias value for each each of the protected groups - in this case, Male (`0`) and Female (`1`). \n",
    "\n",
    "These values range from 0 to 1 and can be interpreted as the difference in percent between the ground truth distribution and the distribution of the protected group: for example, a value of 0.3 would mean a 30% difference."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Measuring bias with respect to `age_cat`\n",
    "\n",
    "Now we measure the bias of the same classifier with respect to the age category."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [],
   "source": [
    "ot_val2 = ot_distance(y_true=y, y_pred=preds, prot_attr=df['age_cat'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "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_cat</th>\n",
       "      <th>ot_val</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0</td>\n",
       "      <td>0.000578</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1</td>\n",
       "      <td>0.000313</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>2</td>\n",
       "      <td>0.001800</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   age_cat    ot_val\n",
       "0        0  0.000578\n",
       "1        1  0.000313\n",
       "2        2  0.001800"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "bs2 = pd.DataFrame({\"age_cat\": ot_val2.keys(), \"ot_val\": ot_val2.values()})\n",
    "display(bs2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adult Dataset"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us consider the Adult Dataset. It has two protected categories: `sex` and `race`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aif360.algorithms.preprocessing.optim_preproc_helpers.data_preproc_functions import load_preproc_data_adult\n",
    "\n",
    "import numpy as np\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "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>race</th>\n",
       "      <th>sex</th>\n",
       "      <th>Age (decade)=10</th>\n",
       "      <th>Age (decade)=20</th>\n",
       "      <th>Age (decade)=30</th>\n",
       "      <th>Age (decade)=40</th>\n",
       "      <th>Age (decade)=50</th>\n",
       "      <th>Age (decade)=60</th>\n",
       "      <th>Age (decade)=&gt;=70</th>\n",
       "      <th>Education Years=6</th>\n",
       "      <th>Education Years=7</th>\n",
       "      <th>Education Years=8</th>\n",
       "      <th>Education Years=9</th>\n",
       "      <th>Education Years=10</th>\n",
       "      <th>Education Years=11</th>\n",
       "      <th>Education Years=12</th>\n",
       "      <th>Education Years=&lt;6</th>\n",
       "      <th>Education Years=&gt;12</th>\n",
       "      <th>Income Binary</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   race  sex  Age (decade)=10  Age (decade)=20  Age (decade)=30  \\\n",
       "0   0.0  1.0              0.0              1.0              0.0   \n",
       "1   1.0  1.0              0.0              0.0              1.0   \n",
       "2   1.0  1.0              0.0              1.0              0.0   \n",
       "3   0.0  1.0              0.0              0.0              0.0   \n",
       "4   1.0  0.0              1.0              0.0              0.0   \n",
       "\n",
       "   Age (decade)=40  Age (decade)=50  Age (decade)=60  Age (decade)=>=70  \\\n",
       "0              0.0              0.0              0.0                0.0   \n",
       "1              0.0              0.0              0.0                0.0   \n",
       "2              0.0              0.0              0.0                0.0   \n",
       "3              1.0              0.0              0.0                0.0   \n",
       "4              0.0              0.0              0.0                0.0   \n",
       "\n",
       "   Education Years=6  Education Years=7  Education Years=8  Education Years=9  \\\n",
       "0                0.0                1.0                0.0                0.0   \n",
       "1                0.0                0.0                0.0                1.0   \n",
       "2                0.0                0.0                0.0                0.0   \n",
       "3                0.0                0.0                0.0                0.0   \n",
       "4                0.0                0.0                0.0                0.0   \n",
       "\n",
       "   Education Years=10  Education Years=11  Education Years=12  \\\n",
       "0                 0.0                 0.0                 0.0   \n",
       "1                 0.0                 0.0                 0.0   \n",
       "2                 0.0                 0.0                 1.0   \n",
       "3                 1.0                 0.0                 0.0   \n",
       "4                 1.0                 0.0                 0.0   \n",
       "\n",
       "   Education Years=<6  Education Years=>12  Income Binary  \n",
       "0                 0.0                  0.0            0.0  \n",
       "1                 0.0                  0.0            0.0  \n",
       "2                 0.0                  0.0            1.0  \n",
       "3                 0.0                  0.0            1.0  \n",
       "4                 0.0                  0.0            0.0  "
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "data_raw = load_preproc_data_adult()\n",
    "data = data_raw.convert_to_dataframe()[0]\n",
    "data.head()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Measuring bias with respect to `sex`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [],
   "source": [
    "clf = LogisticRegression(solver='lbfgs', max_iter=10000, C=1.0, penalty='l2')\n",
    "X = data.drop('Income Binary',axis=1)\n",
    "y = data['Income Binary']\n",
    "\n",
    "clf.fit(X, y)\n",
    "preds = pd.Series(clf.predict_proba(X)[:,0])\n",
    "\n",
    "ot_val1 = ot_distance(y_true=y, y_pred=preds, prot_attr=data['sex'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "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>sex</th>\n",
       "      <th>ot_val</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.000503</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1.0</td>\n",
       "      <td>0.000067</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   sex    ot_val\n",
       "0  0.0  0.000503\n",
       "1  1.0  0.000067"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "bs1 = pd.DataFrame({\"sex\": ot_val1.keys(), \"ot_val\": ot_val1.values()})\n",
    "display(bs1)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Measuring bias with respect to `race`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [],
   "source": [
    "ot_val2 = ot_distance(y_true=y, y_pred=preds, prot_attr=data['race'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "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>race</th>\n",
       "      <th>ot_val</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.000779</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>1.0</td>\n",
       "      <td>0.000068</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "   race    ot_val\n",
       "0   0.0  0.000779\n",
       "1   1.0  0.000068"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "bs2 = pd.DataFrame({\"race\": ot_val2.keys(), \"ot_val\": ot_val2.values()})\n",
    "display(bs2)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## More details\n",
    "\n",
    "It is commonly employed as a means to quantify the similarity between distributions, particularly when the distributions have distinct supports. In scenarios where the supports of the distributions are disjoint, OT-based Wasserstein distances offer favorable comparisons to well-known f-divergences such as the Kullback-Leibler divergence, Jensen-Shannon divergence, and Total Variation distance.\n",
    "\n",
    "One notable aspect that makes OT valuable for data science applications is its ability to compute meaningful sub-gradients of the Wasserstein distance. This feature enhances its efficiency as a tool for measuring and optimizing similarity between empirical distributions.\n",
    "\n",
    "The machine learning (ML) literature has seen numerous contributions utilizing OT as an approach. For instance, in the training of Generative Adversarial Networks (GANs), OT has been utilized to tackle the issue of vanishing gradients, which can hinder the learning process. Additionally, OT has been employed to identify discriminant or robust subspaces within datasets, offering useful insights. Moreover, the Wasserstein distance has found application in measuring similarity between word embeddings of documents, as well as comparing signals or spectra.\n",
    "\n",
    "Due to the inherent constraint in the problem, solving Optimal Transport (OT) can be quite challenging. As a result, in practical applications dealing with discrete distributions, a more manageable approach known as a linear program has been employed as a substitute. This approach corresponds to the Kantorovitch formulation, where the original Monge mapping, denoted as $m$ is replaced by a joint distribution represented by an OT matrix.\n",
    "From the optimization problem described above, we can identify two primary components of the OT solution that have practical applications:\n",
    "- The optimal value (Wasserstein distance): This quantifies the similarity between distributions. It is used to measure the dissimilarity or similarity between datasets or distributions. The Wasserstein distance represents the optimal value obtained from solving the OT problem.\n",
    "- The optimal mapping (Monge mapping or OT matrix): This determines the correspondences between the distributions. It describes how the mass is transported between the source and target distributions. The optimal mapping can be utilized to transfer knowledge or information between distributions.\n",
    "\n",
    "In the first case, OT is employed to assess the similarity between distributions or datasets. Here, the Wasserstein distance, which is the optimal value obtained from solving the OT problem, is used as a measure of similarity. In the second case, the focus lies on understanding the specific manner in which mass is transferred between distributions, represented by the mapping. This mapping can be leveraged to facilitate the transfer of knowledge or information between the distributions.\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### OT for mapping estimation\n",
    "\n",
    "One fascinating aspect of the Optimal Transport (OT) problem is the inherent OT mapping. When computing the optimal transport between discrete distributions, one of the outputs is the OT matrix, which provides correspondences between the samples in each distribution.\n",
    "\n",
    "This correspondence is estimated based on the OT criterion and is obtained in a non-supervised manner. This characteristic makes it particularly intriguing for problems involving dataset transfer. OT has been employed, for instance, in performing color transfer between images or in the context of domain adaptation, where knowledge or information is transferred between different datasets.\n",
    "\n",
    "Furthermore, more recent applications have explored the extension of OT, known as Gromov-Wasserstein, to establish correspondences between languages using word embeddings. This utilization of OT enables the identification of connections or similarities between languages based on the distributional properties of word embeddings.\n",
    "\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Kantorovich optimal transport problem\n",
    "\n",
    "This is the most typical OT problem. It seeks an optimal coupling $\\boldsymbol{T}$ which minimizes the displacement cost of a discrete measure $\\boldsymbol{a}$ to a discrete measure $\\boldsymbol{b}$ with respect to a ground cost $\\boldsymbol{M} \\in \\mathbb{R}^{n_{1} \\times n_{2}}$. In order to be a transport plan, $\\boldsymbol{T}$ must be part of the set $\\Pi(\\mathbf{a}, \\mathbf{b})=\\left\\{\\boldsymbol{T} \\geq \\mathbf{0}, \\boldsymbol{T} \\mathbf{1}_{n_{2}}=\\boldsymbol{a}, \\boldsymbol{T}^{\\top} \\mathbf{1}_{n_{1}}=\\boldsymbol{b}\\right\\}$. When the ground cost is a metric, the optimal value of the OT problem is also a metric (Rubner et al., 2000; Cuturi and Avis, 2014) and is called the Wasserstein distance. In this discrete case, the OT problem is defined as\n",
    "\n",
    "$$\n",
    "W_{M}(\\boldsymbol{a}, \\boldsymbol{b})=\\min _{\\boldsymbol{T} \\in \\Pi(\\mathbf{a}, \\mathbf{b})}\\langle\\boldsymbol{T}, \\boldsymbol{M}\\rangle\n",
    "$$\n",
    "\n",
    "which is a linear program. The optimization problem above is often adapted to include a regularization term for the transport plan $\\boldsymbol{T}$, such as entropic regularization (Cuturi, 2013) or squared L2. For the entropic regularized OT problem, one may use the Sinkhorn Knopp algorithm (or variants), or stochastic optimization algorithms. POT has a simple syntax to solve these problems."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solving optimal transport\n",
    "\n",
    "The optimal transport problem between discrete distributions is often expressed as\n",
    "$$\n",
    "\\begin{array}{r}\n",
    "\\gamma^*=\\arg \\min _{\\gamma \\in \\mathbb{R}_{+}^{m \\times n}} \\sum_{i, j} \\gamma_{i, j} M_{i, j} \\\\\n",
    "\\text { s.t. } \\gamma 1=a ; \\gamma^T 1=b ; \\gamma \\geq 0\n",
    "\\end{array}\n",
    "$$\n",
    "where:\n",
    "- $M \\in \\mathbb{R}_{+}^{m \\times n}$ is the metric cost matrix defining the cost to move mass from bin $a_i$ to bin $b_j$.\n",
    "- $a$ and $b$ are histograms on the simplex (positive, sum to 1) that represent the weights of each samples in the source an target distributions.\n",
    "Solving the linear program above can be done using the function ot.emd that will return the optimal transport matrix $\\gamma^*$ :"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The necessity and priority of usage\n",
    "\n",
    "The main difference between the MDSS and OT detectors is the range of applicability. MDSS scanner can in linear time decide, what the most anomalous subset is, while in the case of OT detector has a narrower but more accurate field of use. The method used can only account for 1-dimensional histograms as precisely described in \"POT: Python Optimal Transport\" https://jmlr.org/papers/v22/20-451.html. This means there is no possibility yet to handle datasets of more than 1 feature. For more dimensions, there is a prospect for the Sinkhorn algorithm, which will be implemented in the nearest future. As compared to MDSS, the user needs to specify the sensitive attribute for which wants to know the bias. \n",
    "\n",
    "So if the user is interested in obtaining a certain bias on a particular parameter, it is better to use earth_movers_distance. But if it is more important to see the general picture for all parameters on bias presence, then it is better to use MDSS.\n",
    "\n",
    "The matrix that is obtained from the emd method is called a transport plan in the OT framework (the gamma matrix in https://pythonot.github.io/all.html?highlight=emd#ot.emd). It is the matrix which minimizes the transportation cost, and workable to evaluate the actual Wasserstein distance by taking the Frobenius product (see here for instance: https://en.wikipedia.org/wiki/Frobenius_inner_product) with the metric cost matrix, M."
   ]
  }
 ],
 "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"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "e3a8dcdfdfc9ccb9b75f5bdad7d0512468824af451b906a037b07d69b0e56c16"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}