{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Iterables"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-15T09:49:38.950604Z",
     "start_time": "2021-02-15T09:49:33.794597Z"
    }
   },
   "outputs": [],
   "source": [
    "from fractions import Fraction\n",
    "import poisson_approval as pa"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Iterable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The package provides a large variety of iterables to generate **profiles**, **strategies** or **tau-vectors**. In the following example, we iterate over all the tau-vectors whose coefficients are fractions of the given denominator 3, i.e. using a \"grain\" of $\\frac{1}{3}$:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-15T09:49:38.996481Z",
     "start_time": "2021-02-15T09:49:38.954593Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<a: 1> ==> a\n",
      "<a: 2/3, ab: 1/3> ==> a\n",
      "<a: 2/3, ac: 1/3> ==> a\n",
      "<a: 2/3, b: 1/3> ==> a\n",
      "<a: 2/3, bc: 1/3> ==> a\n",
      "<a: 2/3, c: 1/3> ==> a\n",
      "<a: 1/3, ab: 2/3> ==> a\n",
      "<a: 1/3, ab: 1/3, ac: 1/3> ==> a\n",
      "<a: 1/3, ab: 1/3, b: 1/3> ==> a, b\n",
      "<a: 1/3, ab: 1/3, bc: 1/3> ==> a, b\n",
      "<a: 1/3, ab: 1/3, c: 1/3> ==> a\n",
      "<a: 1/3, ac: 2/3> ==> a\n",
      "<a: 1/3, ac: 1/3, b: 1/3> ==> a\n",
      "<a: 1/3, ac: 1/3, bc: 1/3> ==> a, c\n",
      "<a: 1/3, ac: 1/3, c: 1/3> ==> a, c\n",
      "<a: 1/3, b: 2/3> ==> b\n",
      "<a: 1/3, b: 1/3, bc: 1/3> ==> b\n",
      "<a: 1/3, b: 1/3, c: 1/3> ==> a, b, c\n",
      "<a: 1/3, bc: 2/3> ==> b, c\n",
      "<a: 1/3, bc: 1/3, c: 1/3> ==> c\n",
      "<a: 1/3, c: 2/3> ==> c\n",
      "<ab: 1> ==> a, b\n",
      "<ab: 2/3, ac: 1/3> ==> a\n",
      "<ab: 2/3, b: 1/3> ==> b\n",
      "<ab: 2/3, bc: 1/3> ==> b\n",
      "<ab: 2/3, c: 1/3> ==> a, b\n",
      "<ab: 1/3, ac: 2/3> ==> a\n",
      "<ab: 1/3, ac: 1/3, b: 1/3> ==> a, b\n",
      "<ab: 1/3, ac: 1/3, bc: 1/3> ==> a, b, c\n",
      "<ab: 1/3, ac: 1/3, c: 1/3> ==> a, c\n",
      "<ab: 1/3, b: 2/3> ==> b\n",
      "<ab: 1/3, b: 1/3, bc: 1/3> ==> b\n",
      "<ab: 1/3, b: 1/3, c: 1/3> ==> b\n",
      "<ab: 1/3, bc: 2/3> ==> b\n",
      "<ab: 1/3, bc: 1/3, c: 1/3> ==> b, c\n",
      "<ab: 1/3, c: 2/3> ==> c\n",
      "<ac: 1> ==> a, c\n",
      "<ac: 2/3, b: 1/3> ==> a, c\n",
      "<ac: 2/3, bc: 1/3> ==> c\n",
      "<ac: 2/3, c: 1/3> ==> c\n",
      "<ac: 1/3, b: 2/3> ==> b\n",
      "<ac: 1/3, b: 1/3, bc: 1/3> ==> b, c\n",
      "<ac: 1/3, b: 1/3, c: 1/3> ==> c\n",
      "<ac: 1/3, bc: 2/3> ==> c\n",
      "<ac: 1/3, bc: 1/3, c: 1/3> ==> c\n",
      "<ac: 1/3, c: 2/3> ==> c\n",
      "<b: 1> ==> b\n",
      "<b: 2/3, bc: 1/3> ==> b\n",
      "<b: 2/3, c: 1/3> ==> b\n",
      "<b: 1/3, bc: 2/3> ==> b\n",
      "<b: 1/3, bc: 1/3, c: 1/3> ==> b, c\n",
      "<b: 1/3, c: 2/3> ==> c\n",
      "<bc: 1> ==> b, c\n",
      "<bc: 2/3, c: 1/3> ==> c\n",
      "<bc: 1/3, c: 2/3> ==> c\n",
      "<c: 1> ==> c\n"
     ]
    }
   ],
   "source": [
    "for tau in pa.IterableTauVectorGrid(denominator=3):\n",
    "    print(tau)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For most applications, it is not interesting to investigate all these tau-vectors because of the symmetries between candidates. To study them up to symmetries, use the option ``standardized=True``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-15T09:49:39.050392Z",
     "start_time": "2021-02-15T09:49:39.001467Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<a: 1> ==> a\n",
      "<a: 2/3, ab: 1/3> ==> a\n",
      "<a: 2/3, b: 1/3> ==> a\n",
      "<a: 2/3, bc: 1/3> ==> a\n",
      "<a: 1/3, ab: 2/3> ==> a\n",
      "<a: 1/3, ab: 1/3, ac: 1/3> ==> a\n",
      "<a: 1/3, ab: 1/3, b: 1/3> ==> a, b\n",
      "<a: 1/3, ab: 1/3, bc: 1/3> ==> a, b\n",
      "<a: 1/3, ac: 1/3, b: 1/3> ==> a\n",
      "<a: 1/3, b: 1/3, c: 1/3> ==> a, b, c\n",
      "<a: 1/3, bc: 2/3> ==> b, c\n",
      "<ab: 1> ==> a, b\n",
      "<ab: 2/3, ac: 1/3> ==> a\n",
      "<ab: 1/3, ac: 1/3, bc: 1/3> ==> a, b, c\n"
     ]
    }
   ],
   "source": [
    "for tau in pa.IterableTauVectorGrid(denominator=3, standardized=True):\n",
    "    print(tau)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most iterables of the package provide options that enable to finely tune the outputs. In the following example, there are ballots $a$ with a fixed share 1/7, ballots $ab$ with a fixed share 2/7, and the remaining 4/7 of the voters are split between ballots $b$, $bc$ and $c$, with a \"relative\" grain $\\frac{1}{4}$, i.e. an \"absolute\" grain $\\frac{4}{7} \\cdot \\frac{1}{4} = \\frac{1}{7}$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-15T09:49:39.063923Z",
     "start_time": "2021-02-15T09:49:39.052331Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<a: 1/7, ab: 2/7, b: 4/7> ==> b\n",
      "<a: 1/7, ab: 2/7, b: 3/7, bc: 1/7> ==> b\n",
      "<a: 1/7, ab: 2/7, b: 3/7, c: 1/7> ==> b\n",
      "<a: 1/7, ab: 2/7, b: 2/7, bc: 2/7> ==> b\n",
      "<a: 1/7, ab: 2/7, b: 2/7, bc: 1/7, c: 1/7> ==> b\n",
      "<a: 1/7, ab: 2/7, b: 2/7, c: 2/7> ==> b\n",
      "<a: 1/7, ab: 2/7, b: 1/7, bc: 3/7> ==> b\n",
      "<a: 1/7, ab: 2/7, b: 1/7, bc: 2/7, c: 1/7> ==> b\n",
      "<a: 1/7, ab: 2/7, b: 1/7, bc: 1/7, c: 2/7> ==> b\n",
      "<a: 1/7, ab: 2/7, b: 1/7, c: 3/7> ==> a, b, c\n",
      "<a: 1/7, ab: 2/7, bc: 4/7> ==> b\n",
      "<a: 1/7, ab: 2/7, bc: 3/7, c: 1/7> ==> b\n",
      "<a: 1/7, ab: 2/7, bc: 2/7, c: 2/7> ==> b, c\n",
      "<a: 1/7, ab: 2/7, bc: 1/7, c: 3/7> ==> c\n",
      "<a: 1/7, ab: 2/7, c: 4/7> ==> c\n"
     ]
    }
   ],
   "source": [
    "iterable = pa.IterableTauVectorGrid(\n",
    "    d_ballot_fixed_share={'a': Fraction(1, 7), 'ab': Fraction(2, 7)},\n",
    "    ballots=['b', 'bc', 'c'],\n",
    "    denominator=4\n",
    ")\n",
    "for tau in iterable:\n",
    "    print(tau)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more information, cf. the *Reference* section on iterables."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conditional Iterable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Say you have a test on tau-vectors, for example the fact of electing candidate $a$ only:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-15T09:49:39.081371Z",
     "start_time": "2021-02-15T09:49:39.065296Z"
    }
   },
   "outputs": [],
   "source": [
    "def test_a_wins(tau):\n",
    "    return tau.winners == {'a'}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to iterate over tau vectors that meet this test, you can use the classic Python syntax:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-15T09:49:39.141051Z",
     "start_time": "2021-02-15T09:49:39.085244Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<a: 1> ==> a\n",
      "<a: 2/3, ab: 1/3> ==> a\n",
      "<a: 2/3, ac: 1/3> ==> a\n",
      "<a: 2/3, b: 1/3> ==> a\n",
      "<a: 2/3, bc: 1/3> ==> a\n",
      "<a: 2/3, c: 1/3> ==> a\n",
      "<a: 1/3, ab: 2/3> ==> a\n",
      "<a: 1/3, ab: 1/3, ac: 1/3> ==> a\n",
      "<a: 1/3, ab: 1/3, c: 1/3> ==> a\n",
      "<a: 1/3, ac: 2/3> ==> a\n",
      "<a: 1/3, ac: 1/3, b: 1/3> ==> a\n",
      "<ab: 2/3, ac: 1/3> ==> a\n",
      "<ab: 1/3, ac: 2/3> ==> a\n"
     ]
    }
   ],
   "source": [
    "for tau in pa.IterableTauVectorGrid(denominator=3):\n",
    "    if test_a_wins(tau):\n",
    "        print(tau)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, you can specify the test directly when defining the iterable:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-02-15T09:49:39.167454Z",
     "start_time": "2021-02-15T09:49:39.143518Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<a: 1> ==> a\n",
      "<a: 2/3, ab: 1/3> ==> a\n",
      "<a: 2/3, ac: 1/3> ==> a\n",
      "<a: 2/3, b: 1/3> ==> a\n",
      "<a: 2/3, bc: 1/3> ==> a\n",
      "<a: 2/3, c: 1/3> ==> a\n",
      "<a: 1/3, ab: 2/3> ==> a\n",
      "<a: 1/3, ab: 1/3, ac: 1/3> ==> a\n",
      "<a: 1/3, ab: 1/3, c: 1/3> ==> a\n",
      "<a: 1/3, ac: 2/3> ==> a\n",
      "<a: 1/3, ac: 1/3, b: 1/3> ==> a\n",
      "<ab: 2/3, ac: 1/3> ==> a\n",
      "<ab: 1/3, ac: 2/3> ==> a\n"
     ]
    }
   ],
   "source": [
    "for tau in pa.IterableTauVectorGrid(denominator=3, test=test_a_wins):\n",
    "    print(tau)"
   ]
  }
 ],
 "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.7.3"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "sideBar": true,
   "skip_h1_title": true,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "188.875px"
   },
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}