tabulator.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notebook for _Nyquist's Ranked Choice Voting Tabulator_\n",
    "\n",
    "This is my sandbox for exploring the results of [ranked choice voting](https://en.wikipedia.org/wiki/Ranked_voting) elections. Learn more at the [GitHub Repository](https://github.com/KalebNyquist/ranked-choice-tabulator).\n",
    "\n",
    "> 💡 Looking for data to experiment with? Try the [Ranked Choice Voting Resource Center's Data Clearinghouse](https://www.rcvresources.org/data-clearinghouse)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Navigation\n",
    "* [Functional Code](#Functional-Code)\n",
    "    * [Import Libraries & At-Large Functions](#Import-Libraries-&-At-Large-Functions)\n",
    "    * [Select Configuration for Reading Cast Vote Records](#Select-Configuration-for-Reading-Cast-Vote-Records)\n",
    "        * [Configuration Wizard `cfg_wizard()`](#Configuration-Wizard-cfg_wizard())\n",
    "        * [Load and Save Configurations from Memory `load_cfgs()`](#Load-and-Save-Configurations-from-Memory-load_cfgs())\n",
    "    * [Tabulate Election Results](#Tabulate-Election-Results)\n",
    "    * [Visualize Election Results](#Visualize-Election-Results)\n",
    "    * [Narrate Election Results](#Narrate-Election-Results) `narrate_results()`\n",
    "    * [Check for Non-Monotoniciy](#Check-for-Non-Monotonicity) `monotonicity_check()`\n",
    "* [Execution Code](#Execution-Code)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Functional Code\n",
    "This section defines the Python functions, global variables, and libraries/packages needed to execute the code. Every cell needs to be run prior to executing the code but nothing significant will happen until [the execution code](#Execution-Code) is run afterwards."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import Libraries & At-Large Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When using Google Colab, un-comment the lines below to install the necessary libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# !pip install parse\n",
    "# !pip install num2words"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import numpy as np\n",
    "from parse import parse\n",
    "import json\n",
    "import os\n",
    "from math import ceil, floor\n",
    "from collections import Counter\n",
    "from num2words import num2words\n",
    "\n",
    "# cfg_wizard\n",
    "import pathlib\n",
    "\n",
    "# presentation\n",
    "import matplotlib.pyplot as plt\n",
    "from matplotlib.lines import Line2D\n",
    "import matplotlib.patches as patches\n",
    "\n",
    "# non-monotonicity check\n",
    "from itertools import permutations, combinations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Select Configuration for Reading Cast Vote Records\n",
    "### Configuration Wizard `cfg_wizard()`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_path_to_election_data():\n",
    "    \"\"\" - [ ] get source\"\"\"\n",
    "    try:\n",
    "        current_location = pathlib.Path(__file__).parent.resolve()\n",
    "    except NameError:\n",
    "        current_location = pathlib.Path().absolute().__str__().replace(\"\\\\\", \"/\")\n",
    "    return current_location + '/election_data'\n",
    "\n",
    "\n",
    "def list_election_data_locs_and_make_selection(file_or_folder):\n",
    "    \"\"\"Lists all files or folders, allowing user to input selection.\"\"\"\n",
    "    \n",
    "    print(f\"Alright! {file_or_folder}s listed below:\")\n",
    "    \n",
    "    if file_or_folder == \"file\":\n",
    "        options = [x.name for x in os.scandir('election_data') if x.is_file()]\n",
    "    elif file_or_folder == \"folder\":\n",
    "        options = [x.name for x in os.scandir('election_data') if x.is_dir()]\n",
    "    else:\n",
    "        print(\"❌ Invalid Parameter:\", file_or_folder)\n",
    "        raise Exception\n",
    "    \n",
    "    for i, option in enumerate(options, start = 1):\n",
    "        print(f\"    {i}. {option}\".rjust(4))\n",
    "        \n",
    "    selection = None\n",
    "    while selection is None:\n",
    "        selection_i = input(f\"Which {file_or_folder} has the election data?\")\n",
    "        try:\n",
    "            selection = options[int(selection_i) - 1]\n",
    "        except:\n",
    "            print(\"Selection invalid.\")\n",
    "    \n",
    "    return selection\n",
    "\n",
    "\n",
    "def get_data_location():\n",
    "    \"\"\"Guides user where to copy and input file containing cast vote record data.\"\"\"\n",
    "    \n",
    "    print(\"To start, add the file or folder containing the data to the `election_data` folder found here:\")\n",
    "    print(\"     \", get_path_to_election_data(), \"\\n\")\n",
    "    \n",
    "    data_storage = input(\"Did you add a (1) file or (2) folder? \")\n",
    "    while data_storage not in [\"1\", \"2\"]:\n",
    "        print(data_storage, \"is invalid input\")\n",
    "        data_storage = input(\"Did you add a (1) file or (2) folder? \")\n",
    "        \n",
    "    if data_storage == \"1\":\n",
    "        file_name = list_election_data_locs_and_make_selection(\"file\")\n",
    "        return file_name, None\n",
    "        \n",
    "    elif data_storage == \"2\":\n",
    "        folder_name = list_election_data_locs_and_make_selection(\"folder\")\n",
    "\n",
    "        print(f\"Sounds good. What is the extension of the data files in the folder? \")\n",
    "        \n",
    "        files_found = []\n",
    "        while len(files_found) == 0: \n",
    "            extension = input(\"File Extension (for example, .csv): \")\n",
    "            extension = f\".{extension}\".replace(\"..\", \".\")\n",
    "            file_name = folder_name + \"/*\" + extension\n",
    "\n",
    "            file_path, extension = file_name.split(\"*\")\n",
    "\n",
    "            for file in os.listdir(\"election_data/{}\".format(file_path)):\n",
    "                if file.endswith(extension):\n",
    "                    files_found.append(file)\n",
    "            if len(files_found) == 0:\n",
    "                print(f\"No files found with extension {extension}. Make sure you inputted the extension correctly (case-sensitive!).\")\n",
    "                \n",
    "        print(len(files_found), \"files found:\", \", \".join(files_found))\n",
    "        \n",
    "        return file_name, files_found\n",
    "    \n",
    "\n",
    "def get_record_structure():\n",
    "    \"\"\"Guides user on how to identify & specify the structure of the cast vote record data.\"\"\"\n",
    "    \n",
    "    record_structures = {\n",
    "        \"field\" : \"When there are '1st Place', '2nd Place', etc. columns with candidate IDs as the value in each.\",\n",
    "        \"value\" : \"When there are 'Ranking A' + 'Candidate A' columns, then 'Ranking B' + 'Candidate B', columns, etc. as rankings and candidate IDs are paired as separate but corresponding columns.\",\n",
    "        \"array\" : \"When all the rankings + candidates information are stored together as a list. For example: ['(1) Candidate A', '(2) Candidate B', etc.]\"\n",
    "    }\n",
    "    \n",
    "    print(\"\\n\\nOkay, here comes the tricky part. There are three known ways to structure RCV data:\")\n",
    "    \n",
    "    for format_, description in record_structures.items():\n",
    "        print(\"    `{}` — {}\".format(format_, description))\n",
    "\n",
    "    record_structure = input(\"Enter how your is data structured [field, value, or array]? \").lower()\n",
    "    while record_structure not in record_structures:\n",
    "        print(record_structure, \"is invalid input\")\n",
    "        record_structure = input(\"Enter how your is data structured [field, value, or array]? \").lower()\n",
    "        \n",
    "    return record_structure\n",
    "\n",
    "\n",
    "def get_header_row():\n",
    "    \"\"\"Asks user to idenify a valid header row\"\"\"\n",
    "    \n",
    "    print(\"\\nIs there a header row that contains column names?\")\n",
    "    \n",
    "    header_row = None\n",
    "    \n",
    "    while header_row is None:\n",
    "        header_row = input(\"Instructions: Enter header row (leave empty for none, 0 for top row, 1 for second row, etc.): \")\n",
    "        if header_row == \"\":\n",
    "            pass\n",
    "        else:\n",
    "            try:\n",
    "                header_row = int(header_row)\n",
    "            except ValueError:\n",
    "                print(header_row, \"is invalid input. Enter an integer (0, 1, 2, etc.) or leave blank.\")\n",
    "                header_row = None\n",
    "    \n",
    "    if header_row == \"\":\n",
    "        header_row = None\n",
    "    \n",
    "    return header_row\n",
    "\n",
    "\n",
    "def get_unique_id(header_row):\n",
    "    \"\"\"Asks user to select a column that identifies each ballot uniquely (if it exists)\"\"\"\n",
    "    \n",
    "    # - [ ] change to the input system used for other columns\n",
    "    \n",
    "    print(\"\\n**OPTIONAL**: Is there a column that identifies each ballot uniquely? (i.e., no duplicates)\")\n",
    "    \n",
    "    unique_id = None\n",
    "    \n",
    "    if header_row is None:\n",
    "        print(\"Instructions: Because you identified no header row, column names will be 0-indexed integers.\")\n",
    "        while unique_id is None:\n",
    "            unique_id = input(\"Enter unique id as integer (or leave empty for none): \")\n",
    "            if unique_id == \"\":\n",
    "                pass\n",
    "            else:\n",
    "                try:\n",
    "                    unique_id = int(unique_id)\n",
    "                except ValueError:\n",
    "                    print(unique_id, \"is invalid input. Enter an integer (0, 1, 2, etc.) or leave blank.\")\n",
    "                    unique_id = None\n",
    "    if type(header_row) is int:\n",
    "        print(\"Instructions: Because you identified a header row, use column names from the header row.\")\n",
    "        unique_id = input(\"Enter unique id (or leave empty for none): \")\n",
    "        \n",
    "    if unique_id == \"\":\n",
    "        unique_id = None\n",
    "    \n",
    "    return unique_id\n",
    "\n",
    "\n",
    "def get_tied_symbol():\n",
    "    \"\"\"Asks user to select a character that identifies tied candidates within the same field value.\"\"\"\n",
    "    \n",
    "    print(\"\\nIs there a symbol that identifies candidates that are equally ranked on the same ballot?\")\n",
    "    print(\"For example, if 'A=B' denotes a tie between Candidate A & Candidate B, then the `tied symbol` is '='.\")\n",
    "    \n",
    "    tied_symbol = input(\"Tied symbol (leave blank for none): \")\n",
    "    if tied_symbol == \"\":\n",
    "        tied_symbol = None\n",
    "    \n",
    "    return tied_symbol\n",
    "\n",
    "\n",
    "def get_file_delimiter():\n",
    "    \"\"\"Asks user to identify the spreadsheet's delimiter.\"\"\"\n",
    "    print(\"\\nWhat is the delimiter character for the spreadsheet? (often, but not always, a comma. If tab-delimited, input <tab>.)\")\n",
    "    file_delimiter = input(\"Spreadsheet delimiter: \")\n",
    "    \n",
    "    if file_delimiter == \"<tab>\":\n",
    "        file_delimiter = \"\\t\"\n",
    "    \n",
    "    return file_delimiter\n",
    "\n",
    "\n",
    "def load_data(file_path, header_row, file_delimiter):\n",
    "    \"\"\"Loads cast vote record data using the appropriate `pandas` module according to the extension\"\"\"\n",
    "    \n",
    "    extension = file_path.split(\".\")[-1].lower()\n",
    "    check_and_create_dirs()\n",
    "    \n",
    "    if extension == \"csv\":\n",
    "        print(\"Loading .csv file…\", end=\"\\r\")\n",
    "        election_df = pd.read_csv(file_path,\n",
    "                                  low_memory=False,\n",
    "                                  header=header_row,\n",
    "                                 )\n",
    "    elif extension in ['xls', 'xlsx']:\n",
    "        print(\"Loading Excel file…\", end=\"\\r\")\n",
    "        election_df = pd.read_excel(file_path,\n",
    "                                    header=header_row,\n",
    "                                   )\n",
    "    elif extension in ['txt', 'prm']:\n",
    "        print(\"Loading text table file…\", end=\"\\r\")\n",
    "        election_df = pd.read_table(file_path,\n",
    "                                    header = header_row,\n",
    "                                    delimiter = file_delimiter,\n",
    "                                   )\n",
    "    else:\n",
    "        raise Exception\n",
    "        \n",
    "    return election_df\n",
    "\n",
    "\n",
    "def print_columns(columns_dict):\n",
    "    \"\"\"Prints a dictionary of column index numbers and names to ease selecting the appropriate column\"\"\"\n",
    "    print(\"\\nThe following columns are in the data:\")\n",
    "    for i, column in columns_dict.items():\n",
    "        print(f\"    [{i}] {column}\")\n",
    "        \n",
    "        \n",
    "def get_field_columns(columns_dict):\n",
    "    \"\"\"Guides the user to identify the appropiate columns when encountering a `field` record structure\"\"\"\n",
    "    \n",
    "    print_columns(columns_dict)\n",
    "    field_columns = []\n",
    "\n",
    "    i = 1\n",
    "    while True:\n",
    "        w = num2words(i, ordinal = True)\n",
    "        field_col_input = input(f\"Enter the column # where the {w} place candidate is listed for each row (or leave blank to finish): \")\n",
    "        \n",
    "        if field_col_input == \"\":\n",
    "            break\n",
    "        \n",
    "        try:\n",
    "            field_col = columns_dict[int(field_col_input)]\n",
    "        except Exception:\n",
    "            print(\"Error: enter listed value\")\n",
    "            continue\n",
    "        \n",
    "        field_columns.append(field_col)\n",
    "        i += 1\n",
    "\n",
    "    return field_columns\n",
    "\n",
    "\n",
    "def get_value_columns(columns_dict):\n",
    "    \"\"\"Guides the user to identify the appropiate columns when encountering a `value` record structure\"\"\"\n",
    "    \n",
    "    print_columns(columns_dict)\n",
    "    field_columns = []\n",
    "    value_columns = []\n",
    "    \n",
    "    i = 1\n",
    "    while True:\n",
    "        w = num2words(i, ordinal = True)\n",
    "        value_col_input = input(f\"Enter the column # where a candidate is {w}-listed (in terms of data structure, not actual rank) for each row (or leave blank to finish): \")\n",
    "        if value_col_input == \"\":\n",
    "            break\n",
    "        \n",
    "        try:\n",
    "            value_col = columns_dict[int(value_col_input)]\n",
    "        except Exception:\n",
    "            print(\"Error: enter listed value\")\n",
    "            continue\n",
    "        \n",
    "        while True:\n",
    "            field_col_input = input(f\"Enter the column # where the candidate in column `{value_col}` is ranked for each row.\")\n",
    "            try:\n",
    "                field_col = columns_dict[int(field_col_input)]\n",
    "                break\n",
    "            except Exception:\n",
    "                print(\"Error: enter listed value\")\n",
    "        \n",
    "        value_columns.append(value_col)\n",
    "        field_columns.append(field_col)\n",
    "        \n",
    "        i += 1\n",
    "        \n",
    "    return field_columns, value_columns\n",
    "\n",
    "\n",
    "def cfg_wizard():\n",
    "    \"\"\"Text-based guide written in conversational English to aid setup of a configuration for reading cast vote record data (`read_cfg`).\"\"\"\n",
    "    \n",
    "    print(\"🧙 Welcome to the Configuration Wizard!\")\n",
    "    print(\"I am a step-by-step guide for setting the parameters necessary for reading your RCV data into the program.\\n\")\n",
    "    \n",
    "    check_and_create_dirs()\n",
    "    file_name, files_found = get_data_location()\n",
    "    \n",
    "    if \"*\" not in file_name:\n",
    "        preview_file(file_name)\n",
    "    elif \"*\" in file_name:\n",
    "        # - [ ] Make preview_folder() function\n",
    "        print(\"❌ Cannot preview folder-based election data.\")\n",
    "    \n",
    "    file_delimiter = get_file_delimiter()\n",
    "    header_row = get_header_row()\n",
    "    \n",
    "    if \"*\" in file_name:\n",
    "        file_path = \"election_data/\" + file_name.split(\"*\")[0] + files_found[0]\n",
    "    elif \"*\" not in file_name:\n",
    "        file_path = \"election_data/\" + file_name\n",
    "        \n",
    "    election_df = load_data(file_path, header_row, file_delimiter)\n",
    "    columns_dict = {i + 1 : col for i, col in enumerate(election_df.columns)}\n",
    "    \n",
    "    record_structure = get_record_structure()\n",
    "    unique_id = get_unique_id(header_row)\n",
    "    tied_symbol = get_tied_symbol()\n",
    "\n",
    "    read_cfg = {\"File Name\" : file_name, \n",
    "            \"Record Structure\" : record_structure,\n",
    "            \"File Delimiter\" : file_delimiter,\n",
    "            \"Header Row\" : header_row,\n",
    "            \"Unique Record ID\" : unique_id,\n",
    "            \"Tied Symbol\" : tied_symbol}\n",
    "    \n",
    "    if record_structure == \"field\":\n",
    "        field_columns = get_field_columns(columns_dict)\n",
    "        read_cfg.update({\"Ranking Field Values\" : field_columns})\n",
    "    elif record_structure == \"values\":\n",
    "        field_columns, value_columns = get_value_columns(columns_dict)\n",
    "        read_cfg.update({\"Ranking Field Values\" : field_columns,\n",
    "                         \"Candidate Field Values\" : value_columns})\n",
    "    elif record_structure == \"array\":\n",
    "        # - [ ] Make same quality as above\n",
    "        array_column = input(\"Type name of array column: \")\n",
    "        array_delimiter = input(\"Type delimiter used for array elements: \")\n",
    "        array_template = input(\"Type template used for array element using template tags, e.g. '{candidate}.[{rank}]' = 'CandidateB.[3]' : \")\n",
    "        \n",
    "        if \"{candidate}\" not in array_template:\n",
    "            print(\"Invalid array template. Needs `{candidate}` in string.\")\n",
    "            raise Exception\n",
    "        if \"{rank}\" not in array_template:\n",
    "            print(\"Invalid array template. Needs `{rank}` in string.\")\n",
    "            raise Exception\n",
    "        \n",
    "        read_cfg.update({\"Array Column\" : array_column,\n",
    "                         \"Array Delimiter\" : array_delimiter,\n",
    "                         \"Array Template\" : array_template})\n",
    "    \n",
    "    \n",
    "    # - [ ] add ballots to skip\n",
    "    # - [ ] add candidates to skip\n",
    "    \n",
    "    cfg_nickname = input(\"Give this configuration a nickname (leave blank to skip): \")\n",
    "    if cfg_nickname != \"\":\n",
    "        read_cfg.update({\"Configuration Nickname\" : cfg_nickname})\n",
    "        \n",
    "    \n",
    "    return read_cfg\n",
    "\n",
    "\n",
    "def candidate_name_wizard(ballots):\n",
    "    \"\"\"Text-based guide written in conversational English to aid setup of a map between candidate IDs and their names as they should be displayed.\"\"\"\n",
    "    \n",
    "    print('🧙‍♂️ Welcome to the candidate name wizard!\\nI am going to provide you the `ids` of candidates (i.e., as they are shown in the data), and you are going to give me their \"real name\" (i.e., what you want shown in the visual/verbal outputs).\\n')\n",
    "    \n",
    "    candidate_names = {}\n",
    "    print(\"Loading candidate names...\", end=\"\\r\")\n",
    "    \n",
    "    for candidate_id in determine_all_candidates(ballots):\n",
    "        candidate_names.update({candidate_id : input(f\"Name for `{candidate_id}`?\")})\n",
    "        \n",
    "    return candidate_names\n",
    "\n",
    "\n",
    "def get_candidate_to_name_map(use_candidate_ids_as_names = True):\n",
    "    \"\"\"Creates a candidate ID to name map, with the option of having the names for presentation be equal to IDs used for internal processing.\"\"\"\n",
    "\n",
    "    if use_candidate_ids_as_names:\n",
    "        name_map = {x : x for x in determine_all_candidates(ballots)}\n",
    "    if use_candidate_ids_as_names is False:\n",
    "        candidate_names = candidate_name_wizard(ballots)\n",
    "        view_cfg = {\"Election Name\" : input(\"Election Name: \"),\n",
    "                \"Candidate Names\" : candidate_names}\n",
    "        save_cfg(view_cfg, which='view')\n",
    "        name_map = view_cfg['Candidate Names']\n",
    "        \n",
    "    return name_map\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def preview_file(file_name):\n",
    "    with open(f\"election_data/{file_name}\") as e:\n",
    "        print(f\"\\n 🔍 Previewing {file_name}:\\n----------------------------------------------------------------------------------\")\n",
    "        for rep in range(0,5):\n",
    "            print(\"    \", e.readline(), end=\"\")\n",
    "        print(\"----------------------------------------------------------------------------------\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Load and Save Configurations from Memory `load_cfgs()`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def check_and_create_dirs(check_for = ['election_data']):\n",
    "    \"\"\"Makes sure necessary directories exist, and if not create them.\"\"\"\n",
    "    for required_dir in check_for:\n",
    "        if required_dir not in os.listdir():\n",
    "            os.mkdir(required_dir)\n",
    "\n",
    "            \n",
    "def save_cfg(cfg_to_save, which = \"read\"):\n",
    "    \"\"\"Saves a configuration as a subdocument in a JSON file that stores all local configurations. A backup file is also created to mitigate loss when an error or crash is encountered in the process of saving.\"\"\"\n",
    "    \n",
    "    try:\n",
    "        with open(f'{which}_cfgs.json', mode='r') as load_cfgs:\n",
    "            cfgs = json.load(load_cfgs)\n",
    "    except FileNotFoundError:\n",
    "        cfgs = []\n",
    "    \n",
    "    with open(f'{which}_cfgs_backup.json', mode=\"w\") as backup_cfgs:\n",
    "        json.dump(cfgs, backup_cfgs)\n",
    "    \n",
    "    if cfg_to_save in cfgs:\n",
    "        print(\"⚠️ Identical configuration already exists. No change made.\")\n",
    "    elif cfg_to_save not in cfgs:\n",
    "        cfgs.append(cfg_to_save)\n",
    "    \n",
    "        with open(f'{which}_cfgs.json', mode='w') as save_cfgs:\n",
    "            json.dump(cfgs, save_cfgs)\n",
    "\n",
    "    return cfgs\n",
    "\n",
    "\n",
    "def load_cfgs(which = \"read\"):\n",
    "    \"\"\"Guides the user to load a locally stored configuration. The `cfg_wizard()` can also be accessed through this interface.\"\"\"\n",
    "    try:\n",
    "        with open(f'{which}_cfgs.json') as read_cfgs:\n",
    "            cfgs = json.load(read_cfgs)\n",
    "    except FileNotFoundError:\n",
    "        cfgs = []\n",
    "    \n",
    "    cfgs_dict = {}\n",
    "    cfg_selection = \"0\"\n",
    "    no_name = \"????? (No Nickname or File Name)\"\n",
    "    \n",
    "    left_margin = len(str(len(cfgs)))\n",
    "    \n",
    "    print(\"# |\".rjust(left_margin + 3), \"Saved Configurations\\n—————————————————————————————————————————————————————————————————————————\")\n",
    "    for i, cfg in enumerate(cfgs, start = 1):\n",
    "        str_i = f\"{i} |\".rjust(left_margin + 3)\n",
    "        cfgs_dict.update({str(i) : cfg})\n",
    "        if 'Configuration Nickname' in cfg:\n",
    "            print(str_i, cfg['Configuration Nickname'])\n",
    "        if 'Election Name' in cfg:\n",
    "            print(str_i, cfg['Election Name'])\n",
    "        elif 'File Name' not in cfg:\n",
    "            print(str_i, no_name)\n",
    "        elif 'Configuration Nickname' not in cfg:\n",
    "            print(str_i, cfg['File Name'])\n",
    "    print(\"+ |\".rjust(left_margin + 3), \"🧙 Create new configuration using wizard\")\n",
    "    \n",
    "    print(\"\\n\", end=\"\")\n",
    "    cfg_selection = input(\"Load Configuration File #: \")\n",
    "    while cfg_selection not in cfgs_dict.keys():\n",
    "        if cfg_selection == \"+\":\n",
    "            print(\"\\n\", end=\"\")\n",
    "            read_cfg = cfg_wizard()\n",
    "            save_cfg(read_cfg)\n",
    "            cfgs_dict.update({\"N\" : read_cfg})\n",
    "            cfg_selection = \"N\"\n",
    "            break\n",
    "        \n",
    "        if len(cfgs_dict) > 0:\n",
    "            print(f\"File # not found. Select # between {min(cfgs_dict)}-{max(cfgs_dict)}, or select `+` to create new configuration.\")\n",
    "        elif len(cfgs_dict) == 0:\n",
    "            print(f\"File # not found. Select `+` to create new configuration.\")\n",
    "        \n",
    "        cfg_selection = input(\"Load Configuration File #: \")\n",
    "        \n",
    "    read_cfg = cfgs_dict[cfg_selection]\n",
    "    print(\"✔\", read_cfg.get('Configuration Nickname',\n",
    "                            read_cfg.get('File Name',\n",
    "                                         read_cfg.get('Election Name',\n",
    "                                         no_name))), \"configuration selected.\")\n",
    "    \n",
    "    return read_cfg"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tabulate Election Results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def load_election_data(file_path):\n",
    "    \"\"\"Loads cast vote record data using the appropriate `pandas` module according to the extension\"\"\"\n",
    "    # - [ ] Similar to load data for configuration wizard, worthwhile to merge\n",
    "    \n",
    "    extension = file_path.split(\".\")[-1].lower()\n",
    "    check_and_create_dirs()\n",
    "    \n",
    "    if extension == \"csv\":\n",
    "        print(f\"Loading .csv file: {file_path}\".ljust(20), end=\"\\r\")\n",
    "        election_df = pd.read_csv(file_path,\n",
    "                                  low_memory=False,\n",
    "                                  header=read_cfg['Header Row']\n",
    "                                 )\n",
    "    elif extension in ['xls', 'xlsx']:\n",
    "        print(f\"Loading Excel file: {file_path}\".ljust(20), end=\"\\r\")\n",
    "        election_df = pd.read_excel(file_path,\n",
    "                                    header=read_cfg['Header Row']\n",
    "                                   )\n",
    "    elif extension in ['txt', 'prm']:\n",
    "        print(f\"Loading text table file: {file_path}\".ljust(20), end=\"\\r\")\n",
    "        election_df = pd.read_table(file_path,\n",
    "                                    header = read_cfg['Header Row'],\n",
    "                                    delimiter = read_cfg.get('File Delimiter'),\n",
    "                                    skiprows = read_cfg.get('Skip Rows'),\n",
    "                                   )\n",
    "    #elif json\n",
    "    else:\n",
    "        raise Exception\n",
    "        \n",
    "    return election_df\n",
    "\n",
    "\n",
    "def clean_election_dataframe(read_cfg, election_df):\n",
    "    \"\"\"Cleans the dataframe of cast vote records by removing non-unique records and ballots that the read configuration designates to skip\"\"\"\n",
    "    if read_cfg['Unique Record ID'] is not None:\n",
    "        election_df = election_df[election_df[read_cfg[\"Unique Record ID\"]].notna()]\n",
    "\n",
    "        skip_ballots = read_cfg.get('Skip Ballots', [])\n",
    "        for skip_ballot in skip_ballots:\n",
    "            election_df = election_df[election_df[read_cfg[\"Unique Record ID\"]] != skip_ballot]\n",
    "\n",
    "    election_df = election_df.fillna(np.nan).replace([np.nan], [None])\n",
    "    return election_df\n",
    "\n",
    "\n",
    "def get_election_data_as_dataframe(read_cfg):\n",
    "    \"\"\"Gets the cast vote records as a pandas dataframe\"\"\"\n",
    "    if \"*\" in read_cfg['File Name']:\n",
    "\n",
    "        file_paths = []\n",
    "\n",
    "        file_path, extension = read_cfg['File Name'].split(\"*\")\n",
    "        file_path = f\"election_data/{file_path}\"\n",
    "\n",
    "        for file in os.listdir(file_path):\n",
    "            if file.endswith(extension):\n",
    "                file_paths.append(\"{}{}\".format(file_path, file, extension))\n",
    "\n",
    "        election_df = pd.concat([load_election_data(file_path) for file_path in file_paths])\n",
    "\n",
    "    elif type(read_cfg['File Name']) == str:\n",
    "        file_path = f\"election_data/{read_cfg['File Name']}\"\n",
    "        election_df = load_election_data(file_path)\n",
    "    print(\"✔ Loaded!\".ljust(80))\n",
    "    \n",
    "    election_df = clean_election_dataframe(read_cfg, election_df)\n",
    "    print(\"✔ Cleaned!\".ljust(30))\n",
    "    \n",
    "    return election_df\n",
    "\n",
    "\n",
    "def generate_by_value_columns_of_interest(read_cfg):\n",
    "    \"\"\"Gets the names of columns used to extract relevant data from the dataframe when encountering a `value` data stucture. Note that `cand` (used throughout) is short for 'candidate'.\"\"\"\n",
    "    rank_columns = {}\n",
    "    cand_columns = {}\n",
    "    \n",
    "    for i, rank_value in enumerate(read_cfg['Ranking Field Values']):\n",
    "        if read_cfg.get('Ranking Field Template', False):\n",
    "            rank_columns.update({read_cfg['Ranking Field Template'].format(ranking_field_value = rank_value) : f\"Rank {i}\"})\n",
    "        else:\n",
    "            rank_columns.update({rank_value : f\"Rank {i}\"})\n",
    "        \n",
    "        if \"{ranking_field_value}\" in read_cfg.get('Candidate Field Template', False):\n",
    "            cand_columns.update({read_cfg['Candidate Field Template'].format(ranking_field_value = rank_value) : f\"Cand {i}\"})\n",
    "\n",
    "    if \"{candidate_field_value}\" in read_cfg.get('Candidate Field Template', False):\n",
    "        for i, cand_value in enumerate(read_cfg['Candidate Field Values']):\n",
    "            cand_columns.update({read_cfg['Candidate Field Template'].format(candidate_field_value = cand_value) : f\"Cand {i}\"})\n",
    "    \n",
    "    return rank_columns, cand_columns\n",
    "        \n",
    "\n",
    "def generate_by_field_columns_of_interest(read_cfg):\n",
    "    \"\"\"Gets the names of columns used to extract relevant data from the dataframe when encountering a `field` data stucture.\"\"\"\n",
    "    rank_scores = {}\n",
    "    cand_columns = {}\n",
    "    \n",
    "    for i, rank_value in enumerate(read_cfg['Ranking Field Values'], start = 1):\n",
    "        \n",
    "        rank_scores.update({f\"Rank {i}\" : i})\n",
    "        if read_cfg.get('Ranking Field Template', False):\n",
    "            cand_columns.update({read_cfg['Ranking Field Template'].format(ranking_field_value = rank_value) : f\"Cand {i}\"})\n",
    "        else:\n",
    "            cand_columns.update({rank_value : f\"Cand {i}\"})\n",
    "        \n",
    "    return rank_scores, cand_columns\n",
    "\n",
    "\n",
    "longest_array = 0\n",
    "\n",
    "def generate_ballot_by_array(election_record, read_cfg):\n",
    "    \"\"\"Creates a ballot when encoutering an `array` data structure, according to the ballot data schema used internally.\"\"\"\n",
    "    global longest_array\n",
    "    \n",
    "    if read_cfg['Record Structure'] != \"array\":\n",
    "        raise Exception\n",
    "    \n",
    "    ballot = {}\n",
    "    \n",
    "    if \"Unique Record ID\" in read_cfg:\n",
    "        try:\n",
    "            ballot.update({\"Record ID\" : election_record[read_cfg[\"Unique Record ID\"]]})\n",
    "        except KeyError:\n",
    "            ballot.update({\"Record ID\" : election_record[int(read_cfg[\"Unique Record ID\"])]})\n",
    "    \n",
    "    try:\n",
    "        raw_vote = election_record[read_cfg[\"Array Column\"]]\n",
    "    except KeyError:\n",
    "        raw_vote = election_record[int(read_cfg[\"Array Column\"])]\n",
    "    \n",
    "    if type(raw_vote) == list:\n",
    "        vote_array = raw_vote\n",
    "    elif type(raw_vote) == str:\n",
    "        vote_array = raw_vote.split(read_cfg[\"Array Delimiter\"])\n",
    "    elif raw_vote is None:\n",
    "        vote_array = []\n",
    "    else:\n",
    "        raise Exception(ballot.get(\"Record ID\"), type(raw_vote))\n",
    "    \n",
    "    i = 0\n",
    "    for vote in vote_array:\n",
    "        vote = vote.strip()\n",
    "        deconstructed_vote = parse(read_cfg['Array Template'], vote)\n",
    "        if deconstructed_vote is None:\n",
    "            continue\n",
    "        ballot.update({f\"Rank {i}\" : deconstructed_vote['rank']})\n",
    "        ballot.update({f\"Cand {i}\" : deconstructed_vote['candidate']})\n",
    "\n",
    "        i += 1\n",
    "        if i > longest_array:\n",
    "            longest_array = i\n",
    "    \n",
    "    return ballot\n",
    "\n",
    "\n",
    "def get_ballots_and_column_maps(read_cfg, election_df):\n",
    "    \"\"\"Creates dictionaries used to map voter rankings with corresponding candidate ids.\"\"\"\n",
    "    columns_of_interest = {}\n",
    "\n",
    "    if read_cfg['Record Structure'] == \"value\":\n",
    "        rank_columns, cand_columns = generate_by_value_columns_of_interest(read_cfg)    \n",
    "        for cols in [rank_columns, cand_columns]:\n",
    "            columns_of_interest.update(cols)\n",
    "        if read_cfg.get(\"Unique Record ID\",) is not None: \n",
    "            columns_of_interest.update({read_cfg[\"Unique Record ID\"] : \"Record ID\"})\n",
    "        ballots = election_df[columns_of_interest].rename(columns = columns_of_interest).to_dict(\"records\")\n",
    "\n",
    "    elif read_cfg['Record Structure'] == \"field\":\n",
    "        rank_scores, cand_columns = generate_by_field_columns_of_interest(read_cfg)\n",
    "        rank_columns = dict(zip(rank_scores.keys(), rank_scores.keys()))\n",
    "        for cols in [cand_columns]:\n",
    "            columns_of_interest.update(cols)\n",
    "        ballots = election_df[columns_of_interest].rename(columns = columns_of_interest).to_dict(\"records\")\n",
    "        for ballot in ballots:\n",
    "            ballot = ballot.update(rank_scores)\n",
    "\n",
    "    elif read_cfg['Record Structure'] == \"array\":\n",
    "        election_records = election_df.to_dict(\"records\")\n",
    "        ballots = [generate_ballot_by_array(election_record, read_cfg) for election_record in election_records]\n",
    "        rank_columns = {f\"Rank {i}\" : f\"Rank {i}\" for i in range(0, longest_array)}\n",
    "        cand_columns = {f\"Cand {i}\" : f\"Cand {i}\" for i in range(0, longest_array)}\n",
    "\n",
    "    rank_to_cand_map = dict(zip(rank_columns.values(), cand_columns.values()))\n",
    "    cand_to_rank_map = {v : k for k, v in rank_to_cand_map.items()}\n",
    "\n",
    "    print( \"✔ Mapped!\")\n",
    "    \n",
    "    return ballots, rank_to_cand_map, cand_to_rank_map, rank_columns, cand_columns\n",
    "\n",
    "\n",
    "def get_readable_votes(ballot):\n",
    "    \"\"\"Adds a series of  'Vote #' fields to each ballot that combines the information from the 'Rank #' and 'Cand #' columns\"\"\"\n",
    "    votes = {}\n",
    "    \n",
    "    for rank_column in rank_columns.values():\n",
    "\n",
    "        try:\n",
    "            rank_val = ballot.get(rank_column, None)\n",
    "            if rank_val:\n",
    "                rank_num = int(rank_val)\n",
    "                if rank_column not in votes:\n",
    "                    votes.update({rank_num : []})\n",
    "            elif rank_val is None:\n",
    "                continue\n",
    "        except TypeError:\n",
    "            print(rank_column, ballot)\n",
    "            raise Exception\n",
    "        except ValueError:\n",
    "            continue\n",
    "\n",
    "        candidate = ballot[rank_to_cand_map[rank_column]]\n",
    "        \n",
    "        if read_cfg['Tied Symbol']:\n",
    "            if candidate is None:\n",
    "                votes[rank_num].append(candidate)\n",
    "            elif read_cfg['Tied Symbol'] in candidate:\n",
    "                deconstructed_candidates = candidate.split(read_cfg['Tied Symbol'])\n",
    "                for deconstructed_candidate in deconstructed_candidates:\n",
    "                    votes[rank_num].append(deconstructed_candidate)\n",
    "            elif read_cfg['Tied Symbol'] not in candidate:\n",
    "                votes[rank_num].append(candidate)\n",
    "                \n",
    "        elif read_cfg['Tied Symbol'] is None:\n",
    "            votes[rank_num].append(candidate)\n",
    "\n",
    "    for vote, candidates in votes.items():\n",
    "        ballot.update({\"Vote {}\".format(vote) : candidates})\n",
    "    \n",
    "    return ballot\n",
    "\n",
    "\n",
    "def process_all_ballots(ballots):\n",
    "    \"\"\"Wraps the per-ballot `get_readable_votes()` function in a manner that processes all ballots.\"\"\"\n",
    "    \n",
    "    for ballot in ballots:\n",
    "        ballot = get_readable_votes(ballot)\n",
    "    print(\"✔ Processed!\")\n",
    "    \n",
    "    return ballots\n",
    "\n",
    "\n",
    "def get_top_choice(ballot, elims):\n",
    "    \"\"\"Gets the top choice for a ballot after factoring in which candidates have been eliminated from consideration.\"\"\"\n",
    "    i = 1\n",
    "    choice = None\n",
    "    while choice is None:\n",
    "        \n",
    "        if f\"Vote {i}\" not in ballot:\n",
    "            return None\n",
    "        \n",
    "        choices = ballot[f\"Vote {i}\"].copy()\n",
    "        \n",
    "        for elim in elims:\n",
    "            if elim in choices:\n",
    "                choices.remove(elim)\n",
    "        \n",
    "        if len(choices) >= 2:\n",
    "            choice = choices\n",
    "            return choice\n",
    "        \n",
    "        elif len(choices) == 1:\n",
    "            [choice] = choices\n",
    "            return choice\n",
    "        \n",
    "        elif len(choices) == 0:\n",
    "            i += 1\n",
    "            \n",
    "        else:\n",
    "            raise Exception(\"Stuck in 'No Choice' While Loop\")\n",
    "            \n",
    "\n",
    "def get_total_votes(round_, include_nones = False):\n",
    "    \"\"\"Gets the total number of votes in a given round.\"\"\"\n",
    "    if include_nones:\n",
    "        total_votes = sum(dict(round_).values())\n",
    "    elif include_nones is False:\n",
    "        total_votes = sum([votes for candidate, votes in dict(round_).items() if candidate is not None])\n",
    "    return total_votes\n",
    "\n",
    "\n",
    "def contest_round(round_):\n",
    "    \"\"\"Identify the top and bottom-ranked candidates for each (\"instant-runoff\") round to determine who should be eliminated and if anyone won the election in that round.\"\"\"\n",
    "    \n",
    "    total_votes = get_total_votes(round_)\n",
    "    win_threshold = floor((total_votes / 2) + 1)\n",
    "    \n",
    "    round_winner = {\"candidate\": None, \"votes\" : 0}\n",
    "    round_loser = {\"candidate\": None, \"votes\" : total_votes}\n",
    "\n",
    "    for candidate, votes in round_.items():\n",
    "\n",
    "        if candidate is None:\n",
    "            continue\n",
    "\n",
    "        if votes > round_winner[\"votes\"]:\n",
    "            round_winner = {\"candidate\" : candidate, \"votes\" : votes}\n",
    "        elif votes == round_winner[\"votes\"]:\n",
    "            if round_winner[\"candidate\"] is None:\n",
    "                round_winner = {\"candidate\" : candidate, \"votes\" : votes}\n",
    "            elif type(round_winner[\"candidate\"]) == list:\n",
    "                round_winner[\"candidate\"].append(candidate)\n",
    "            else:\n",
    "                round_winner[\"candidate\"] = [round_winner[\"candidate\"], candidate]\n",
    "\n",
    "        if votes < round_loser[\"votes\"]:\n",
    "            round_loser = {\"candidate\" : candidate, \"votes\" : votes}\n",
    "        elif votes == round_loser[\"votes\"]:\n",
    "            if round_loser[\"candidate\"] is None:\n",
    "                round_loser = {\"candidate\" : candidate, \"votes\" : votes}\n",
    "            elif type(round_loser[\"candidate\"]) == list:\n",
    "                round_loser[\"candidate\"].append(candidate)\n",
    "            else:\n",
    "                round_loser[\"candidate\"] = [round_loser[\"candidate\"], candidate]\n",
    "\n",
    "    if round_winner[\"votes\"] >= win_threshold:\n",
    "        winner_to_crown = round_winner\n",
    "    elif round_winner[\"votes\"] < win_threshold:\n",
    "        winner_to_crown = None\n",
    "\n",
    "    loser_to_eliminate = round_loser\n",
    "    \n",
    "    return loser_to_eliminate, round_winner, winner_to_crown, total_votes, win_threshold\n",
    "\n",
    "\n",
    "def contest_favorite_betrayal_round(round_, forced_elim, forced_elim_order):\n",
    "    \"\"\"Variation of `contest_round()` used for identifying possible non-monotonicity in `monotonicity_check()`.\"\"\"\n",
    "    \n",
    "    total_votes = get_total_votes(round_)\n",
    "    win_threshold = floor((total_votes / 2) + 1)\n",
    "    \n",
    "    round_winner = {\"candidate\": None, \"votes\" : 0}\n",
    "    round_loser = {\"candidate\": None, \"votes\" : total_votes}\n",
    "    \n",
    "    for candidate, votes in round_.items():\n",
    "\n",
    "        if candidate is None:\n",
    "            continue  \n",
    "        elif candidate == forced_elim:\n",
    "            forced_loser = {\"candidate\" : candidate, \"votes\" : votes}\n",
    "        elif candidate not in forced_elim_order:\n",
    "            actual_winner = {\"candidate\" : candidate, \"votes\" : votes}\n",
    "\n",
    "        if votes > round_winner[\"votes\"]:\n",
    "            round_winner = {\"candidate\" : candidate, \"votes\" : votes}\n",
    "        elif votes == round_winner[\"votes\"]:\n",
    "            if round_winner[\"candidate\"] is None:\n",
    "                round_winner = {\"candidate\" : candidate, \"votes\" : votes}\n",
    "            elif type(round_winner[\"candidate\"]) == list:\n",
    "                round_winner[\"candidate\"].append(candidate)\n",
    "            else:\n",
    "                round_winner[\"candidate\"] = [round_winner[\"candidate\"], candidate]\n",
    "        \n",
    "        if votes < round_loser[\"votes\"]:\n",
    "            round_loser = {\"candidate\" : candidate, \"votes\" : votes}\n",
    "        elif votes == round_loser[\"votes\"]:\n",
    "            if round_loser[\"candidate\"] is None:\n",
    "                round_loser = {\"candidate\" : candidate, \"votes\" : votes}\n",
    "            elif type(round_loser[\"candidate\"]) == list:\n",
    "                round_loser[\"candidate\"].append(candidate)\n",
    "            else:\n",
    "                round_loser[\"candidate\"] = [round_loser[\"candidate\"], candidate]\n",
    "\n",
    "    if forced_elim_order[-1] == forced_elim:\n",
    "        if actual_winner['votes'] > forced_loser['votes']:\n",
    "            loser_to_eliminate = forced_loser\n",
    "        elif actual_winner['votes'] == forced_loser['votes']:\n",
    "            # stopgap\n",
    "            loser_to_eliminate = forced_loser\n",
    "        elif actual_winner['votes'] < forced_loser['votes']:\n",
    "            loser_to_eliminate = actual_winner\n",
    "    elif forced_elim in forced_elim_order[0:-1]:\n",
    "        loser_to_eliminate = forced_loser\n",
    "\n",
    "    if round_winner[\"votes\"] >= win_threshold:\n",
    "        winner_to_crown = round_winner\n",
    "    elif round_winner[\"votes\"] < win_threshold:\n",
    "        winner_to_crown = None\n",
    "    \n",
    "    return loser_to_eliminate, round_winner, winner_to_crown, total_votes, win_threshold\n",
    "\n",
    "\n",
    "def determine_all_first_round_candidates_on_board(ballots):\n",
    "    \"\"\"Determines who are all the candidates who appear in the first round of voting.\"\"\"\n",
    "    all_candidates = []\n",
    "    for ballot in ballots:\n",
    "        top_votes = ballot.get('Vote 1')\n",
    "        if top_votes:\n",
    "            for top_vote in top_votes:\n",
    "                if top_vote:\n",
    "                    all_candidates.append(top_vote)\n",
    "            all_candidates = list(set(all_candidates))\n",
    "    return all_candidates\n",
    "\n",
    "\n",
    "def determine_candidates_eligibility_for_first_round(ballots):\n",
    "    \"\"\"Used to determine which candidates are (in)eligible for the first round of (\"instant-runoff\") voting.\"\"\"\n",
    "    \n",
    "    # All Candidates\n",
    "    all_candidates = set(determine_all_candidates(ballots))\n",
    "    \n",
    "    # All Candidates in the First Round (Including Ties)\n",
    "    eligible = set(determine_all_first_round_candidates_on_board(ballots))\n",
    "    # - [ ] what if a competitive candidate is also only tie-ranked for first?\n",
    "    \n",
    "    # Ineligible Candidates\n",
    "    ineligible = all_candidates.difference(eligible)\n",
    "    \n",
    "    return all_candidates, eligible, ineligible\n",
    "\n",
    "\n",
    "def contest_election(ballots, criteria_test = None, forced_elim_order = None):\n",
    "    \"\"\"Runs an (\"instant-runoff\") election in a series of consecutive rounds to determine the election winner.\"\"\"\n",
    "    \n",
    "    rounds = {}\n",
    "    results = {}\n",
    "    round_i = 0\n",
    "    \n",
    "    elims = read_cfg.get(\"Pre-Eliminated Candidate Codes\", []).copy()\n",
    "    all_candidates, eligible, ineligible = determine_candidates_eligibility_for_first_round(ballots)\n",
    "    \n",
    "    if criteria_test in [\"Favorite Betrayal\"]:\n",
    "        pass\n",
    "    else:\n",
    "        for ineligible_candidate in ineligible:\n",
    "            elims.append(ineligible_candidate)\n",
    "    \n",
    "    winner_to_crown = None\n",
    "\n",
    "    while winner_to_crown is None:\n",
    "        round_i += 1\n",
    "        print(f\"Contesting Round {round_i}...\", end=\"\\r\")\n",
    "        rounds.update({round_i : Counter()})\n",
    "        tied_ballots = 0\n",
    "\n",
    "        for ballot in ballots:\n",
    "            top_choice = get_top_choice(ballot, elims)\n",
    "            if type(top_choice) == list:\n",
    "                tied_ballots += 1\n",
    "            elif (type(top_choice) in [str, float, int]) or (top_choice is None):\n",
    "                rounds[round_i][top_choice] += 1\n",
    "            else:\n",
    "                raise Exception(f\"Top Choice Error: {top_choice} {type(top_choice)}\")\n",
    "        \n",
    "        if criteria_test in [\"Favorite Betrayal\"]:\n",
    "            forced_elim = forced_elim_order[round_i - 1]\n",
    "            loser_to_eliminate, round_winner, winner_to_crown, total_votes, win_threshold = contest_favorite_betrayal_round(rounds[round_i],\n",
    "                                                                                                                            forced_elim,\n",
    "                                                                                                                            forced_elim_order)\n",
    "            elims.append(forced_elim)\n",
    "            \n",
    "        elif criteria_test is None:\n",
    "            loser_to_eliminate, round_winner, winner_to_crown, total_votes, win_threshold = contest_round(rounds[round_i])\n",
    "\n",
    "            if type(loser_to_eliminate['candidate']) == list:\n",
    "                elims.extend(loser_to_eliminate['candidate'])\n",
    "            else:\n",
    "                elims.append(loser_to_eliminate['candidate'])\n",
    "        \n",
    "        ordered_vote_counts = dict(sorted(rounds[round_i].items(), key = lambda kv: kv[1], reverse=True))\n",
    "        \n",
    "        results[round_i] = {}\n",
    "        results[round_i].update({\"Tied Ballots\" : tied_ballots})\n",
    "        results[round_i].update({\"Vote Counts\" : ordered_vote_counts})\n",
    "        results[round_i].update({\"Total Votes\" : total_votes})\n",
    "        results[round_i].update({\"Win Threshold\" : win_threshold})\n",
    "        results[round_i].update({\"Round Winner\" : round_winner['candidate']})\n",
    "        if criteria_test not in [\"Favorite Betrayal\"]:\n",
    "            results[round_i].update({\"Eliminated\" : loser_to_eliminate['candidate']})\n",
    "        elif criteria_test in [\"Favorite Betrayal\"]:\n",
    "            results[round_i].update({\"Eliminated\" : loser_to_eliminate['candidate']})\n",
    "\n",
    "    results[round_i].update({\"Winner\" : winner_to_crown['candidate']})\n",
    "    print(f\"✔ Contested! {name_map[winner_to_crown['candidate']]} won after {len(rounds)} rounds.\".ljust(30))\n",
    "    return rounds, results\n",
    "\n",
    "\n",
    "def determine_all_candidates(ballots):\n",
    "    \"\"\"Determines who all the candidates in a given election are on the basis of whether or not they are in the ballot data.\"\"\"\n",
    "    all_candidates = []\n",
    "    \n",
    "    for ballot in ballots:\n",
    "        #for cand_column in cand_columns:\n",
    "        for cand_column in cand_columns.values():\n",
    "            add_candidate = ballot.get(cand_column)\n",
    "            if add_candidate:\n",
    "                \n",
    "                if read_cfg['Tied Symbol'] is not None:\n",
    "                    deconstructed_add_candidates = add_candidate.split(read_cfg['Tied Symbol'])\n",
    "                elif read_cfg['Tied Symbol'] is None:\n",
    "                    deconstructed_add_candidates = [add_candidate]\n",
    "                \n",
    "                for dac in deconstructed_add_candidates:\n",
    "                    if dac:\n",
    "                        all_candidates.append(dac)\n",
    "                all_candidates = list(set(all_candidates))\n",
    "                \n",
    "    return all_candidates\n",
    "\n",
    "\n",
    "def calculate_vote_transfers(result_0, result_1):\n",
    "    \"\"\"Determines how many votes are transferred from a candidate eliminated in a given round to the candidates who are eligible for the next round.\"\"\"\n",
    "    transfers = {}\n",
    "    for candidate in result_1['Vote Counts']:\n",
    "        if candidate not in result_0['Vote Counts']:\n",
    "            continue\n",
    "        transfer = result_1['Vote Counts'][candidate] - result_0['Vote Counts'][candidate]\n",
    "        transfers.update({candidate : transfer})\n",
    "    return transfers\n",
    "\n",
    "\n",
    "def calculate_percentages(result, total_ballots):\n",
    "    \"\"\"Determines the percentage of votes earned by each candidate in a given round.\"\"\"\n",
    "    percentages = {}\n",
    "    \n",
    "    total_votes = result['Total Votes']\n",
    "    \n",
    "    for candidate, votes in result['Vote Counts'].items():\n",
    "        ballot_percentage = (votes / total_ballots) # i.e., includes undervotes\n",
    "        vote_percentage = (votes / total_votes) # i.e., does not include undervotes\n",
    "        percentages.update({candidate : {\"Of Ballots\" : ballot_percentage,\n",
    "                                         \"Of Votes\" : vote_percentage}})\n",
    "    \n",
    "    return percentages\n",
    "\n",
    "\n",
    "def enrich_results(results):\n",
    "    \"\"\"Adds additional statistics to each round's results.\"\"\"\n",
    "    \n",
    "    for i, result in results.items():\n",
    "    \n",
    "        percentages = calculate_percentages(result, len(ballots))\n",
    "        result.update({'Percentages' : percentages})\n",
    "\n",
    "        if 'Winner' in result:\n",
    "            continue\n",
    "\n",
    "        elif 'Eliminated' in result:\n",
    "            transfers = calculate_vote_transfers(results[i], results[i + 1])\n",
    "            result.update({'Vote Transfers' : transfers})\n",
    "        \n",
    "    print(\"✔ Enriched!\")\n",
    "    return results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualize Election Results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Horizontal Bar Graph"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_color_to_candidate_map(ballots, results, palette_choice = \"tableau_remix\"):\n",
    "    \"\"\"Get map of candidate IDs to a color from desired palette.\"\"\"\n",
    "    \n",
    "    def get_palette_choice(palette_choice):\n",
    "        \"\"\"Get desired palette. Learn more about these palettes at https://gist.github.com/KalebNyquist/965e2c2b5512026817ed9aec69bbe278\"\"\"\n",
    "\n",
    "        # - [ ] add greyscale choice\n",
    "        if palette_choice == \"xgfs\":\n",
    "            palette = ['#ebac23', '#b80058', '#008cf9', '#006e00', '#00bbad', '#d163e6', '#b24502', '#ff9287', '#5954d6',\n",
    "                       '#00c6f8', '#878500', '#00a76c']\n",
    "            greys = ['#585858', '#eeeeee']\n",
    "        elif palette_choice == \"tableau_remix\":\n",
    "            palette = ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#bcbd22', '#17becf', \n",
    "                       '#aec7e8', '#ffbb78', '#98df8a', '#ff9896', '#c5b0d5', '#c49c94', '#f7b6d2', '#dbdb8d', '#9edae5']\n",
    "            greys = ['#7f7f7f', '#c7c7c7']\n",
    "        else:\n",
    "            raise Exception\n",
    "\n",
    "        return palette, greys\n",
    "    \n",
    "    \n",
    "    palette, greys = get_palette_choice(palette_choice)\n",
    "\n",
    "    all_candidates, eligible, ineligible = determine_candidates_eligibility_for_first_round(ballots)\n",
    "    eligible_first_round_vote_counts = {e : results[1]['Vote Counts'].get(e, 0) for e in eligible}\n",
    "    eligible_ordered = dict(sorted(eligible_first_round_vote_counts.items(), key = lambda kv: kv[1], reverse=True))\n",
    "\n",
    "    color_map = {}\n",
    "    for c, candidate in enumerate(eligible_ordered):\n",
    "        cr = c % len(palette)\n",
    "        color_map.update({candidate : palette[cr]})\n",
    "        \n",
    "    return color_map, greys\n",
    "\n",
    "\n",
    "def get_legend(color_map, greys):\n",
    "    \"\"\"Get user_friendly visual legend used for mapping candidate-specific colors to their names.\"\"\"\n",
    "\n",
    "    handles = [patches.Patch(color=v, label=name_map[k]) for k, v in color_map.items()]\n",
    "    grey_handles = [patches.Patch(color=greys[i], label=[\"Tied Ballot\", \"Exhausted Ballot\"][i]) for i in [0, 1]]\n",
    "    handles = handles + grey_handles\n",
    "\n",
    "    plt.legend(handles=handles, fontsize=12, frameon=False)\n",
    "    plt.gca().set_axis_off()\n",
    "\n",
    "    return plt\n",
    "\n",
    "\n",
    "def get_horizontal_bar_graph_of_rounds(results):\n",
    "    \"\"\"Get results displayed in a horizontal bar graph.\"\"\"\n",
    "\n",
    "    fig, ax = plt.subplots(len(results), 1, figsize = (12,len(results) * 2.05))\n",
    "\n",
    "    plt.subplots_adjust(left=0.1,\n",
    "                        bottom=0.1, \n",
    "                        right=0.9, \n",
    "                        top=0.9, \n",
    "                        wspace=0.4, \n",
    "                        hspace=0.4)\n",
    "\n",
    "    for i, result in results.items():\n",
    "\n",
    "        ax_no = i-1\n",
    "\n",
    "        barh_coordinates = []\n",
    "        cumulative_percentage = 0\n",
    "\n",
    "\n",
    "        exhausted_section = {}\n",
    "\n",
    "        for candidate, percentage in result['Percentages'].items():\n",
    "\n",
    "            if candidate:\n",
    "                barh_section = {\"Candidate\" : name_map[candidate],\n",
    "                                \"Vote Share\" : percentage[\"Of Ballots\"],\n",
    "                                \"Cumulative\" : cumulative_percentage,\n",
    "                                \"Color\" : color_map[candidate]\n",
    "                               }\n",
    "\n",
    "                barh_coordinates.append(barh_section)\n",
    "                cumulative_percentage += percentage[\"Of Ballots\"]\n",
    "\n",
    "\n",
    "            elif candidate is None:\n",
    "                exhausted_percentage = (total_ballots - result[\"Total Votes\"]) / total_ballots\n",
    "                exhausted_section = {\"Candidate\" : \"Exhausted Ballots\",\n",
    "                                     \"Vote Share\" : exhausted_percentage,\n",
    "                                     \"Color\" : greys[1]}\n",
    "\n",
    "\n",
    "        tied_percentage = result[\"Tied Ballots\"] / total_ballots\n",
    "\n",
    "        tied_section = {\"Candidate\" : \"Tied Ballots\",\n",
    "                        \"Vote Share\" : tied_percentage,\n",
    "                        \"Cumulative\" : cumulative_percentage,\n",
    "                        \"Color\" : greys[0]}\n",
    "\n",
    "        barh_coordinates.append(tied_section)\n",
    "        cumulative_percentage_plus_tied = cumulative_percentage + tied_percentage\n",
    "\n",
    "        if exhausted_section != {}:\n",
    "            exhausted_section.update({\"Cumulative\" : cumulative_percentage_plus_tied})\n",
    "            barh_coordinates.append(exhausted_section)\n",
    "\n",
    "        eliminated_candidate = result['Eliminated']\n",
    "        if type(eliminated_candidate) == list:\n",
    "            eliminated_string = \", \".join(result['Eliminated'])\n",
    "            eliminated_vote = result['Percentages'][result['Eliminated'][0]]['Of Ballots'] * 100\n",
    "        elif type(eliminated_candidate) != list:\n",
    "            eliminated_string = name_map[result['Eliminated']]\n",
    "            eliminated_vote = result['Percentages'][result['Eliminated']]['Of Ballots'] * 100\n",
    "\n",
    "        leading_candidate = result['Round Winner']\n",
    "        if type(leading_candidate) == list:\n",
    "            leading_string = \", \".join(result['Round Winner'])\n",
    "            leading_vote = result['Percentages'][result['Round Winner'][0]]['Of Ballots'] * 100\n",
    "        elif type(leading_candidate) != list:\n",
    "            leading_string = name_map[result['Round Winner']]\n",
    "            leading_vote = result['Percentages'][result['Round Winner']]['Of Ballots'] * 100\n",
    "\n",
    "        win_condition = \"{}%\".format(round(100 * result['Win Threshold'] / total_ballots , 2))\n",
    "        if \"Winner\" in result:\n",
    "            win_condition = \"✔ {}\".format(win_condition)\n",
    "        else:\n",
    "            win_color = \"black\"\n",
    "\n",
    "        # X Axis\n",
    "        ax[ax_no].set_xticks([cumulative_percentage * .5], minor=False)\n",
    "        ax[ax_no].set_xticks([0, cumulative_percentage], minor=True)\n",
    "        ax[ax_no].set_xticklabels([\"Required to Win Election:\\n{}\".format(win_condition)], minor=False, color = win_color)\n",
    "        ax[ax_no].set_xticklabels([\"This Round's Leader:\\n{} • {:.2f}%\".format(leading_string, leading_vote),\n",
    "                                   \"Eliminated This Round:\\n{} • {:.2f}%\".format(eliminated_string, eliminated_vote)],\n",
    "                                  minor=True)\n",
    "        ax[ax_no].set_xlim(-.01, 1)\n",
    "        ax[ax_no].grid(True, axis=\"x\", color=\"black\", lw=2, alpha=.4)\n",
    "        ax[ax_no].grid(True, axis=\"x\", color=\"black\", which=\"minor\", lw=2, alpha=1)\n",
    "\n",
    "        # TODO:\n",
    "        # https://stackoverflow.com/questions/33678606/changing-color-of-single-characters-in-matplotlib-plot-labels\n",
    "        # [ ] make all current xticks \"major\" / remove 'win_color' entirely\n",
    "        # [ ] add a colored ◼ \n",
    "        \n",
    "        # Y Axis\n",
    "        ax[ax_no].set_yticks([0])\n",
    "        label = \"{} round\".format(num2words(i, ordinal=True)).title()\n",
    "        ax[ax_no].set_yticklabels([label], weight=\"bold\")\n",
    "\n",
    "        # Cosmetics\n",
    "        ax[ax_no].set_frame_on(False)\n",
    "        ax[ax_no].tick_params(axis=\"x\", direction='in', length=0, pad=3, which=\"minor\")\n",
    "        ax[ax_no].tick_params(axis=\"x\", direction='in', length=0, pad=3, which=\"major\")\n",
    "        ax[ax_no].tick_params(axis=\"y\", direction='in', length=0, pad=12.5)\n",
    "\n",
    "        for coordinate in barh_coordinates:\n",
    "            ax[ax_no].barh(0,\n",
    "                         coordinate[\"Vote Share\"],\n",
    "                         left=coordinate[\"Cumulative\"],\n",
    "                         label=coordinate[\"Candidate\"],\n",
    "                         color=coordinate[\"Color\"]\n",
    "                        )\n",
    "\n",
    "        ax[ax_no].get_xticklabels(minor = True)[0].set_ha(\"left\")\n",
    "        ax[ax_no].get_xticklabels(minor = True)[1].set_ha(\"right\")\n",
    "        \n",
    "    return fig"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Narrate Election Results `narrate_results()`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "relative_performance_words = {\n",
    "    \"+\" : \"rose to\",\n",
    "    \"-\" : \"fell to\",\n",
    "    \"=\" : \"remained at\",\n",
    "    \"!\" : \"was\"\n",
    "}\n",
    "\n",
    "leader_performance_words = {\n",
    "    \"+\" : \"took the lead\",\n",
    "    \"-\" : None,\n",
    "    \"=\" : \"held first place\",\n",
    "    \"!\" : \"received the most highest rankings of any candidate\"\n",
    "}\n",
    "\n",
    "\n",
    "def fvote(number_of_votes, singular = False, noun = \"vote\", extra = \"\", verb = None):\n",
    "    \"\"\"Parameter-guided string creation to display the number and kind of votes in a human-readable manner\"\"\"\n",
    "    if singular:\n",
    "        return \"{:,} {noun}\".format(number_of_votes, noun = noun)\n",
    "    elif (number_of_votes >= 2) or (number_of_votes == 0):\n",
    "        if verb == \"are\":\n",
    "            return \"{:,} {noun}s {extra}are\".format(number_of_votes, extra = extra, noun = noun)\n",
    "        else:\n",
    "            return \"{:,} {noun}s\".format(number_of_votes, noun = noun)\n",
    "    elif number_of_votes == 1:\n",
    "        if verb == \"are\":\n",
    "            return f\"1 {noun} {extra}is\"\n",
    "        else:\n",
    "            return f\"1 {noun}\"\n",
    "    else:\n",
    "        raise Exception\n",
    "\n",
    "        \n",
    "def narrate_result(result_i, results):\n",
    "    \"\"\"Gives a text-based account for what happened in a particular round of voting.\"\"\"\n",
    "            \n",
    "    def candidate_relative_performance(candidate):\n",
    "        \"\"\"Evaluates a candidate's performance in the rankings relative to the previous round of voting.\"\"\"\n",
    "        \n",
    "        if result_i - 1 not in results:\n",
    "            return \"!\"\n",
    "        \n",
    "        this_round = list(result['Vote Counts']).index(candidate)\n",
    "        try:\n",
    "            last_round = list(results[result_i - 1]['Vote Counts']).index(candidate)\n",
    "        except ValueError:\n",
    "            raise Exception\n",
    "        \n",
    "        if this_round == last_round:\n",
    "            return \"=\"\n",
    "        elif this_round > last_round:\n",
    "            return \"-\"\n",
    "        elif this_round < last_round:\n",
    "            return \"+\"\n",
    "    \n",
    "    result = results[result_i]\n",
    "    round_name = num2words(result_i, to=\"ordinal\")\n",
    "    candidates = [k for k, v in list(result['Vote Counts'].items()) if k]\n",
    "    votes = [v for k, v in list(result['Vote Counts'].items()) if k]\n",
    "    win_threshold = result['Win Threshold']\n",
    "    \n",
    "    ## Leading Candidate\n",
    "    a = f\"In the {round_name} round of voting, \"\n",
    "    \n",
    "    # - [ ] replace with round winner\n",
    "    if 'Winner' not in result:\n",
    "        b = f\"{name_map[candidates[0]]} {leader_performance_words[candidate_relative_performance(candidates[0])]} with {fvote(votes[0])}.\"\n",
    "    elif 'Winner' in result:\n",
    "        b = f\"{name_map[candidates[0]]} won the election with {fvote(votes[0])}, {fvote(votes[0] - win_threshold)} more than the {fvote(win_threshold, singular=True)} threshold required to win.\"\n",
    "    \n",
    "    ## Intermediate Candidates\n",
    "    c = \"\"\n",
    "    \n",
    "    if 'Winner' in result:\n",
    "        listed_candidates = candidates[1:]\n",
    "    if 'Winner' not in result:\n",
    "        listed_candidates = candidates[1:-1]\n",
    "    \n",
    "    for rank, intermediate_candidate in enumerate(listed_candidates, start=1):\n",
    "        \n",
    "        if (rank == len(candidates) - 2) & (rank != 1):\n",
    "            c = c + \"and \"\n",
    "        \n",
    "        rank_ordinal = num2words(rank + 1, to=\"ordinal\")\n",
    "        appendage = f\"{name_map[intermediate_candidate]} {relative_performance_words[candidate_relative_performance(intermediate_candidate)]} {rank_ordinal} with {fvote(votes[rank])}, \"\n",
    "        c = c + appendage\n",
    "    \n",
    "        if (rank == len(candidates) - 2) or (len(listed_candidates) == 1):\n",
    "            if c.endswith(\", \"):\n",
    "                c = c[:-2] + \". \"\n",
    "            \n",
    "    ## Eliminated/Winning Candidate\n",
    "            # - [ ] add eliminated/winners and transfer votes\n",
    "    if ('Eliminated' in result) & ('Winner' not in result):\n",
    "        eliminated_candidate = result['Eliminated']\n",
    "        if type(eliminated_candidate) == list:\n",
    "            eliminated_votes = result['Vote Counts'][result['Eliminated'][0]]\n",
    "        elif type(eliminated_candidate) != list:\n",
    "            eliminated_votes = result['Vote Counts'][result['Eliminated']]\n",
    "        \n",
    "        if type(eliminated_candidate) == list:\n",
    "            eliminated_candidates_name_mapped = [name_map[x] for x in eliminated_candidate[0:-2]]\n",
    "            d = f\"Because {', '.join(eliminated_candidates_name_mapped)} and {name_map[eliminated_candidate[-1]]} tied for \"\n",
    "        if type(eliminated_candidate) != list:\n",
    "            d = f\"Because {name_map[eliminated_candidate]} received \"\n",
    "            \n",
    "        d = d + f\"the fewest highest rankings with only {fvote(eliminated_votes)}, they do not advance to the next round.\"\n",
    "        \n",
    "        if 'Vote Transfers' in result:\n",
    "            \n",
    "            if type(eliminated_candidate) == list:\n",
    "                eliminated_candidates_name_mapped = [name_map[x] for x in eliminated_candidate[0:-2]]\n",
    "                e = f\" Of {', '.join(eliminated_candidates_name_mapped)} and {name_map[eliminated_candidate[-1]]}'s combined {fvote(eliminated_votes * len(eliminated_candidate))},\" \n",
    "            if type(eliminated_candidate) != list:\n",
    "                e = f\" Of {name_map[eliminated_candidate]}'s {fvote(eliminated_votes)},\"\n",
    "            \n",
    "            recipients = [k for k, v in list(result['Vote Transfers'].items()) if k and v != 0]\n",
    "            received_votes = [v for k, v in list(result['Vote Transfers'].items()) if k and v != 0]\n",
    "            vote_transfers = dict(zip(recipients, received_votes))\n",
    "            \n",
    "            for i, (recipient, received_vote) in enumerate(vote_transfers.items()):\n",
    "                if (i == len(vote_transfers) - 1) & (i != 0):\n",
    "                    e = e + \" and\"\n",
    "                e = e + f\" {fvote(received_vote, verb='are')} transferred to {name_map[recipient]},\"\n",
    "                if i == len(vote_transfers) - 1:\n",
    "                    if c.endswith(\", \"):\n",
    "                        e = e[:-2] + \". \"\n",
    "                \n",
    "            undervotes = result['Vote Transfers'].get(None, 0)\n",
    "            if undervotes > 0:\n",
    "                f = f\"{fvote(undervotes, noun='ballot', extra = 'did not rank any of the remaining candidates and', verb='are')} removed from consideration. \"\n",
    "                e = e + f\n",
    "                \n",
    "            d = d + e\n",
    "            \n",
    "        c = c + d\n",
    "    \n",
    "    next_round = num2words(result_i + 1, to=\"ordinal\")\n",
    "    if 'Winner' not in result:\n",
    "        z = f\"Because no candidate reached the {fvote(win_threshold, singular=True)} threshold to win the election, voting continues on to the {next_round} round.\\n\"\n",
    "    elif 'Winner' in result:\n",
    "        z = \"\"\n",
    "    \n",
    "    narration = a + b + \" \" + c + z\n",
    "    \n",
    "    return narration\n",
    "\n",
    "\n",
    "def narrate_results(results):\n",
    "    \"\"\"Wrapper function to process each round's result into `narrate_result{}` to give a text-based account for what happened over the course of an instant-run off.\"\"\"\n",
    "    for result in results:\n",
    "        print(narrate_result(result, results))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Check for Non-Monotonicity `monotonicity_check()`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def determine_feasibility_by_subversive_elim_count(subversive_elim_orders):\n",
    "    \"\"\"Checks number of 'subversive' (i.e., resulting in a different winner than expected) candidate elimination orders to determine in an investigtion of non-monotonicity is warranted\"\"\"\n",
    "    \n",
    "    if len(subversive_elim_orders) > 0:\n",
    "        print(f\"✔ {len(subversive_elim_orders)} subversive elimination orders found. Continue with analysis.\")\n",
    "        return True\n",
    "    elif len(subversive_elim_orders) == 0:\n",
    "        print(\"🛇 Zero subversive elimination orders found. Non-monotonicity cannot be proven. Analysis complete.\")\n",
    "        return False\n",
    "\n",
    "def get_pairwise_winners(elim_order, pairs):\n",
    "    \"\"\"Not a strict/Condorcet pairwise (i.e. % of first-place votes) but rather who places higher in terms of the elimination order.\"\"\"\n",
    "    pairwise_winners = {}\n",
    "    \n",
    "    for pairwise in pairs:\n",
    "        home_team = pairwise[0]\n",
    "        away_team = pairwise[1]\n",
    "\n",
    "        home_team_score = elim_order[home_team]\n",
    "        away_team_score = elim_order[away_team]\n",
    "\n",
    "        if home_team_score > away_team_score:\n",
    "            pairwise_winners.update({pairwise : home_team})\n",
    "        elif home_team_score < away_team_score:\n",
    "            pairwise_winners.update({pairwise : away_team})\n",
    "        else:\n",
    "            # - [ ] TODO: Manage tie situation\n",
    "            raise Exception\n",
    "    \n",
    "    return pairwise_winners\n",
    "\n",
    "\n",
    "def run_pairwise_tournament(pairs, real_elim_order, subversive_elim_orders):\n",
    "    \"\"\"Runs each pairing of candidates against their performance in the actual results and each of the subversive elimination orders identified.\"\"\"\n",
    "    \n",
    "    def investigate_results_by_pairing_for_abnormalities(row):\n",
    "        \"\"\"Analyzes a row of the dataframe (representing a pairing of candidates) to see if there is something abnormal about the winners (i.e. different candidate is victorious depending on the elimination order)\"\"\"\n",
    "        winners = [winner for elim_order, winner in row.items() if elim_order != \"Analysis\"]\n",
    "        winners = list(set(winners))\n",
    "\n",
    "        if len(winners) == 1:\n",
    "            return \"Consistent\" # The same candidate will win regardless of the elimination order (real or subversive)\n",
    "\n",
    "        # Determine distribution of multiple winners\n",
    "        real_winner = []\n",
    "        fake_winners = []\n",
    "\n",
    "        for elim_order, winner in row.items():\n",
    "            if elim_order == \"Real\":\n",
    "                real_winner.append(winner)\n",
    "            elif elim_order == \"Analysis\":\n",
    "                continue\n",
    "            else:\n",
    "                fake_winners.append(winner)\n",
    "\n",
    "        fake_winners = list(set(fake_winners))\n",
    "\n",
    "        if len(fake_winners) >= 2:\n",
    "            return \"Mixed\" # Multiple candidates can win depending on the subversive elimination order\n",
    "\n",
    "        if len(fake_winners) == 1:\n",
    "            if fake_winners != real_winner:\n",
    "                return \"Opposed\" # A candidate who wins in each subversive elimination order is different than the candidate who wins given the real results\n",
    "    \n",
    "    pairwise_tournament = {}\n",
    "    pairwise_tournament.update({\"Real\" : get_pairwise_winners(real_elim_order, pairs)})\n",
    "    \n",
    "    for z in subversive_elim_orders:\n",
    "        forced_elim_order = {x : i + 1 for i, x in enumerate(z['elimination order'])}\n",
    "        forced_elim_str = \"-\".join(list(forced_elim_order.keys()))\n",
    "        pairwise_winners = get_pairwise_winners(forced_elim_order, pairs)\n",
    "        pairwise_tournament.update({forced_elim_str : pairwise_winners})\n",
    "    \n",
    "    bracket = pd.DataFrame(pairwise_tournament)\n",
    "    bracket[\"Analysis\"] = bracket.apply(investigate_results_by_pairing_for_abnormalities, axis=1)\n",
    "    \n",
    "    print(\"✔ Pairwise matchings across various elimination orders simulated.\")\n",
    "    return bracket\n",
    "\n",
    "\n",
    "def determine_opposed_pairings(bracket):\n",
    "    \"\"\"Distillation of the analyses from `investigate_results_by_pairing_for_abnormalities()` to determine number of opposed pairings.\"\"\"\n",
    "    bracket_analysis = dict(bracket['Analysis'].value_counts())\n",
    "    num_opposed = bracket_analysis.get('Opposed', 0)\n",
    "    \n",
    "    opposed_pairing = bracket[bracket['Analysis'] == \"Opposed\"]\n",
    "\n",
    "    if num_opposed == 0:\n",
    "        print(\"🛇 Can't continue analysis.\", num_opposed)\n",
    "        return opposed_pairing, False\n",
    "    elif num_opposed == 1:\n",
    "        print(f\"✔ 1 opposed pairing detected: {'-'.join(list(opposed_pairing['Real'].keys())[0])}. Continue with analysis.\")\n",
    "        return opposed_pairing, True\n",
    "    elif num_opposed >= 2:\n",
    "        print(\"🛇 Can't continue analysis.\", num_opposed)\n",
    "        return opposed_pairing, False\n",
    "    \n",
    "\n",
    "def get_relative_ranks_of_opposed_pair(opposed_pairing):\n",
    "    \"\"\"Figure out which candidate in a opposed pairing performs better — this is the candidate who is on the cusp of elimination and whose voters favor the other candidate in the opposed pair over the actual winner.\"\"\"\n",
    "\n",
    "    [higher_rank] = opposed_pairing['Real'].values\n",
    "    [pair_identities] = [opposed_pairing['Real'].keys()][0]\n",
    "    [lower_rank] = [candidate for candidate in pair_identities if candidate != higher_rank]\n",
    "    \n",
    "    return higher_rank, lower_rank\n",
    "\n",
    "\n",
    "def get_critical_result(results, lower_rank):\n",
    "    \"\"\"Determine the round in the real election where the (subversive) candidate is eliminated before they can have a significant numbers of votes be counted for them from another candidate's elimination\"\"\"\n",
    "    [g] = [(i, result) for i, result in results.items() if result['Eliminated'] == lower_rank]\n",
    "    critical_i = g[0]\n",
    "    critical_result = g[1]\n",
    "    print(\"✔ Critical result detected: Round\", critical_i)\n",
    "    return critical_i, critical_result\n",
    "\n",
    "\n",
    "def reverse_evaluate_ballot_for_key_candidates(ballot, num_candidates, higher_rank, lower_rank, winner):\n",
    "    \"\"\"Determine the order of the key candidates: the real winner, the subversive candidate (lower_rank), and the alternative elimination (higher_rank)\"\"\"\n",
    "    evaluation_dict = {}\n",
    "\n",
    "    for ranked_cand in [higher_rank, lower_rank, winner]:\n",
    "        cand_to_i = {cand_a : cand_i for cand_i, cand_a in ballot.items() if cand_a == ranked_cand}\n",
    "\n",
    "        if cand_to_i == {}:\n",
    "            evaluation_dict.update({ranked_cand : num_candidates})\n",
    "            continue\n",
    "\n",
    "        [cand] = list(cand_to_i.keys())\n",
    "\n",
    "        if ranked_cand != cand:\n",
    "            raise Exception\n",
    "\n",
    "        [cand_i] = list(cand_to_i.values())\n",
    "        rank_i = cand_to_rank_map[cand_i]\n",
    "        rank = ballot[rank_i]\n",
    "\n",
    "        evaluation_dict.update({ranked_cand : int(rank)})\n",
    "        \n",
    "    return evaluation_dict\n",
    "\n",
    "def get_possible_betrayals(ballots, lower_rank, higher_rank, winner):\n",
    "    \"\"\"Dictionary collecting all the ballots that represent a voter who can help ruin the election by choosing to rank the winner above the alternate elimination candidate\"\"\"\n",
    "\n",
    "    all_candidates = determine_all_candidates(ballots)\n",
    "    num_candidates = len(all_candidates)\n",
    "\n",
    "    possible_betrayals = {\n",
    "        \"Winner-Above-Spoiler\" : [],\n",
    "        \"Winner-Equal-Spoiler\" : [],\n",
    "        \"Winner-Below-Spoiler\" : []\n",
    "    }\n",
    "    \n",
    "    for ballot in ballots:\n",
    "\n",
    "        evaluation_dict = reverse_evaluate_ballot_for_key_candidates(ballot, num_candidates, higher_rank, lower_rank, winner)\n",
    "\n",
    "        if evaluation_dict[higher_rank] < evaluation_dict[lower_rank] < evaluation_dict[winner]:\n",
    "            possible_betrayals[\"Winner-Below-Spoiler\"].append(ballot)\n",
    "        elif evaluation_dict[higher_rank] < evaluation_dict[winner] == evaluation_dict[lower_rank]:\n",
    "            possible_betrayals[\"Winner-Equal-Spoiler\"].append(ballot)\n",
    "        elif evaluation_dict[higher_rank] < evaluation_dict[winner] < evaluation_dict[lower_rank]:\n",
    "            possible_betrayals[\"Winner-Above-Spoiler\"].append(ballot)\n",
    "        else:\n",
    "            pass\n",
    "\n",
    "    print(\"✔ Ballots sorted by defection possibility.\")\n",
    "    return possible_betrayals\n",
    "\n",
    "\n",
    "def get_threshold_dict(possible_betrayals, betrayals_remaining):\n",
    "    \"\"\"Used as a way of marking how many voters defected, and of what preference profile, at a given point in a hypothetical vote rank swap. Used to mark the lower and upper bounds of a non-monotonic range.\"\"\"\n",
    "    \n",
    "    threshold_dict = {\n",
    "        \"Simple Advance\" : len(possible_betrayals['Winner-Above-Spoiler']) - betrayals_remaining[\"Simple Advance\"],\n",
    "        \"Tie Broken + Advance\" : len(possible_betrayals['Winner-Equal-Spoiler']) - betrayals_remaining[\"Tie Broken + Advance\"],\n",
    "        \"Leapfrog + Advance\" : len(possible_betrayals['Winner-Below-Spoiler']) - betrayals_remaining[\"Leapfrog + Advance\"]\n",
    "    }\n",
    "    \n",
    "    return threshold_dict\n",
    "\n",
    "\n",
    "def get_betrayals_remaining(possible_betrayals):\n",
    "    \"\"\"Used to count how many voters may defect to cause a 'favorite betrayal'\"\"\"\n",
    "    \n",
    "    n_above = len(possible_betrayals['Winner-Above-Spoiler'])\n",
    "    n_equal = len(possible_betrayals['Winner-Equal-Spoiler'])\n",
    "    n_below = len(possible_betrayals['Winner-Below-Spoiler'])\n",
    "    betrayals_remaining = {\"Simple Advance\" : n_above, \"Tie Broken + Advance\" : n_equal, \"Leapfrog + Advance\" : n_below}\n",
    "    return betrayals_remaining\n",
    "\n",
    "\n",
    "def determine_thresholds(possible_betrayals, critical_result, lower_rank, higher_rank, winner):\n",
    "    \"\"\"Shifts voters who can defect/betray their favorite by moving their vote to the winner one at a time, and then looking to see if the outcome of the election has been changed\"\"\"\n",
    "    \n",
    "    spoiler_advantage, alternate_elim_threshold, spoiler_needs_to_win = nonmonotonicity_factors(possible_betrayals,\n",
    "                                                                                                   critical_result,\n",
    "                                                                                                   lower_rank,\n",
    "                                                                                                   higher_rank,\n",
    "                                                                                                   winner)\n",
    "\n",
    "    betrayals_remaining = get_betrayals_remaining(possible_betrayals)\n",
    "\n",
    "    for betrayal_type in betrayals_remaining:\n",
    "\n",
    "        while betrayals_remaining[betrayal_type] > 0:\n",
    "\n",
    "            if alternate_elim_threshold == 0:\n",
    "                lower_threshold = get_threshold_dict(possible_betrayals, betrayals_remaining)\n",
    "\n",
    "            if spoiler_advantage == spoiler_needs_to_win:\n",
    "                higher_threshold = get_threshold_dict(possible_betrayals, betrayals_remaining)\n",
    "\n",
    "            betrayals_remaining[betrayal_type] -= 1\n",
    "\n",
    "            alternate_elim_threshold -= 1\n",
    "\n",
    "            if betrayal_type in ['Tie Broken + Advance', 'Leapfrog + Advance']:\n",
    "                spoiler_needs_to_win += 1\n",
    "\n",
    "            if betrayal_type in ['Leapfrom + Advance']:\n",
    "                spoiler_advantage -= 1\n",
    "                \n",
    "    print(\"✔ Non-monotonicity thresholds calculated.\")\n",
    "    return lower_threshold, higher_threshold\n",
    "\n",
    "\n",
    "def describe_threshold(threshold, threshold_type, possible_betrayals, higher_rank, lower_rank, winner):\n",
    "    \"\"\"An English human-readable explanation of a non-monotonic bound\"\"\"\n",
    "    \n",
    "    higher_rank_total = len(possible_betrayals['Winner-Above-Spoiler']) + len(possible_betrayals['Winner-Equal-Spoiler']) + len(possible_betrayals['Winner-Below-Spoiler'])\n",
    "\n",
    "    above_betrayals = threshold['Simple Advance']\n",
    "    above_possible = len(possible_betrayals['Winner-Above-Spoiler'])\n",
    "\n",
    "    equal_betrayals =  threshold['Tie Broken + Advance']\n",
    "    equal_possible = len(possible_betrayals['Winner-Equal-Spoiler'])\n",
    "\n",
    "    below_betrayals = threshold['Leapfrog + Advance']\n",
    "    below_possible = len(possible_betrayals['Winner-Below-Spoiler'])\n",
    "\n",
    "    if threshold_type == \"lower\":\n",
    "        keywords = (\"begins\", \"minimum\")\n",
    "    elif threshold_type == \"higher\":\n",
    "        keywords = (\"ends\", \"maximum\")\n",
    "    \n",
    "    threshold_english = f\"\"\"Non-monotonicity {keywords[0]} when, of the {higher_rank_total} voters who prefer {name_map[higher_rank]} over {name_map[winner]} & {name_map[lower_rank]}, at {keywords[1]}:\n",
    "    • {above_betrayals} of the {above_possible} voters who **prefer {name_map[winner]} over {name_map[lower_rank]}** defect, and place {name_map[winner]} above {name_map[higher_rank]} \n",
    "    • {equal_betrayals} of the {equal_possible} voters who **equally rank {name_map[winner]} and {name_map[lower_rank]}** defect and place {name_map[winner]} above {name_map[higher_rank]} and {name_map[lower_rank]}\n",
    "    • {below_betrayals} of the {below_possible} voters who **prefer {name_map[lower_rank]} over {name_map[winner]}** defect and place {name_map[winner]} above {name_map[higher_rank]} and {name_map[lower_rank]}\"\"\"\n",
    "\n",
    "    return threshold_english\n",
    "\n",
    "\n",
    "def nonmonotonicity_factors(possible_betrayals, critical_result, lower_rank, higher_rank, winner):\n",
    "    \"\"\"Key numbers used when calculating if an election is nonmonotonic\"\"\"\n",
    "    spoiler_advantage = len(possible_betrayals['Winner-Below-Spoiler']) - len(possible_betrayals['Winner-Above-Spoiler'])\n",
    "    alternate_elim_threshold = critical_result['Vote Counts'][higher_rank] - critical_result['Vote Counts'][lower_rank]\n",
    "    spoiler_needs_to_win = critical_result['Vote Counts'][winner] - critical_result['Vote Counts'][lower_rank]\n",
    "    return spoiler_advantage, alternate_elim_threshold, spoiler_needs_to_win\n",
    "\n",
    "\n",
    "def monotonicity_check(results, ballots):\n",
    "    \"\"\"Runs a monotonicity check of the results and ballots\"\"\"\n",
    "    \n",
    "    def betrayal_factors(results, ballots):\n",
    "        \"\"\"Key numbers used when calculating hypothetical alternatives (i.e., deviant elimination orders) to the actual result\"\"\"\n",
    "    \n",
    "        winner = results[len(results)]['Winner']\n",
    "\n",
    "        winner_set = set([winner])\n",
    "        candidates_but_winner = set(determine_all_candidates(ballots)).difference(winner_set)\n",
    "\n",
    "        if 'Pre-Eliminated Candidate Codes' in read_cfg:\n",
    "            candidates_but_winner = candidates_but_winner.difference(read_cfg['Pre-Eliminated Candidate Codes'])\n",
    "\n",
    "        real_elim_order = {}\n",
    "        reverse_elim_order = {round_i : result['Eliminated'] for round_i, result in results.items()}\n",
    "        for round_i, result in reverse_elim_order.items():\n",
    "            if type(result) == list:\n",
    "                for x in result:\n",
    "                    real_elim_order.update({x : round_i})\n",
    "            elif type(result) != list:\n",
    "                real_elim_order.update({result : round_i})\n",
    "        \n",
    "        real_elim_order = {result['Eliminated'] : round_i for round_i, result in results.items()}\n",
    "        # - [ ] https://statisticsbyjim.com/probability/permutations-probabilities/ <-- how many is too many?\n",
    "        possible_elim_orders = permutations(candidates_but_winner)\n",
    "        elim_orders = [x for x in possible_elim_orders]\n",
    "\n",
    "        pairs = [x for x in combinations(candidates_but_winner, 2)]\n",
    "\n",
    "        print(\"✔ Prerequisite calculations made.\")\n",
    "        return winner, real_elim_order, elim_orders, pairs\n",
    "    \n",
    "    \n",
    "    def find_subversive_elimination_orders(elim_orders, ballots):\n",
    "        \"\"\"Find orders of candidate elimination that would dethrone the real winner.\"\"\"\n",
    "\n",
    "        subversive_elim_orders = []\n",
    "\n",
    "        print(\"\\n########## Beginning election simulations ##########\\n\")\n",
    "\n",
    "        for elim_order in elim_orders:\n",
    "            print(\"Election Simulation with Elimination Order:\", elim_order)\n",
    "            elim_rounds, elim_results = contest_election(ballots,\n",
    "                                                         criteria_test=\"Favorite Betrayal\",\n",
    "                                                         forced_elim_order = elim_order\n",
    "                                                        )\n",
    "\n",
    "            elim_order_winner = elim_results[len(elim_results)]['Winner']\n",
    "\n",
    "            if elim_order_winner != winner:\n",
    "                print(\"‼ Simulated Winner different from Real Winner:\", elim_order_winner, \"≠\", winner)\n",
    "                subversive_elim_orders.append({\"elimination order\" : elim_order,\n",
    "                                      \"results\" : elim_results})\n",
    "\n",
    "            print(\"\\n\", end=\"\")\n",
    "\n",
    "        print(\"########## Concluding election simulations ##########\\n\")\n",
    "\n",
    "        return subversive_elim_orders\n",
    "    \n",
    "    def narrative_numbers(results):\n",
    "        \"\"\"Get round number in human-readable English; other simple-to-calcuate numbers that help describe the narrative can be added here in the future.\"\"\"\n",
    "        real_winning_round = \"{} round\".format(num2words(len(results), ordinal=True))\n",
    "        return real_winning_round\n",
    "\n",
    "    \n",
    "    print(\"Beginning non-monotonicity check…\", end=\"\\r\")\n",
    "    winner, real_elim_order, elim_orders, pairs = betrayal_factors(results, ballots)\n",
    "    subversive_elim_orders = find_subversive_elimination_orders(elim_orders, ballots)\n",
    "    analysis_possible = determine_feasibility_by_subversive_elim_count(subversive_elim_orders)\n",
    "    if analysis_possible is False:\n",
    "        return None, None\n",
    "\n",
    "    bracket = run_pairwise_tournament(pairs, real_elim_order, subversive_elim_orders)\n",
    "    opposed_pairing, able_to_continue = determine_opposed_pairings(bracket)\n",
    "    if able_to_continue is False:\n",
    "        return None, None\n",
    "\n",
    "    higher_rank, lower_rank = get_relative_ranks_of_opposed_pair(opposed_pairing)\n",
    "    critical_i, critical_result = get_critical_result(results, lower_rank)\n",
    "\n",
    "    possible_betrayals = get_possible_betrayals(ballots, lower_rank, higher_rank, winner)\n",
    "    spoiler_advantage, alternate_elim_threshold, spoiler_needs_to_win = nonmonotonicity_factors(possible_betrayals,\n",
    "                                                                                                   critical_result,\n",
    "                                                                                                   lower_rank,\n",
    "                                                                                                   higher_rank,\n",
    "                                                                                                   winner)\n",
    "\n",
    "    lower_threshold, higher_threshold = determine_thresholds(possible_betrayals, critical_result, lower_rank, higher_rank, winner)\n",
    "\n",
    "    real_winning_round = narrative_numbers(results)\n",
    "    \n",
    "    print(\"\\n########## Begin Reporting Results ##########\\n\")\n",
    "    print(f\"In this election, {name_map[winner]} was elected the winner in the {real_winning_round}. However, there exists a range of non-monotonicity where {name_map[lower_rank]} will paradoxically win the election if {name_map[winner]} receives additional votes in the form of higher rankings.¹\\n\")\n",
    "    print(f\"Before we start moving votes around, note that {name_map[lower_rank]} only needs {spoiler_needs_to_win} votes to beat {name_map[winner]}, and if {name_map[higher_rank]} is eliminated before {name_map[lower_rank]} that will give {name_map[lower_rank]} an additional {spoiler_advantage} votes over {name_map[winner]}. Only {alternate_elim_threshold} votes separate {name_map[higher_rank]} from {name_map[lower_rank]}, and every additional vote for {name_map[winner]} over {name_map[higher_rank]} decreases this gap.\\n\")\n",
    "    print(describe_threshold(lower_threshold, \"lower\", possible_betrayals, higher_rank, lower_rank, winner), end=\"\\n\\n\")\n",
    "    # [ ] move language into into `describe_threshold` function\n",
    "    print(f\"In this range of non-monotonicity {name_map[lower_rank]} will win the election instead of {name_map[winner]} despite not receiving any more votes due to {name_map[higher_rank]} having an earlier elimination.\\n\")\n",
    "    print(describe_threshold(higher_threshold, \"higher\", possible_betrayals, higher_rank, lower_rank, winner), end=\"\\n\")\n",
    "    print(f\"\\nAt this point, {name_map[winner]} will still be elected winner when receiving more votes.\")\n",
    "    print(\"\\n¹: For simplicity, non-competitive minor candidates have been factored out.\")\n",
    "    print(\"\\n########## End Reporting Results ##########\\n\")\n",
    "    \n",
    "    print(\"✔ Non-monotonicity check completed.\")\n",
    "    \n",
    "    return lower_threshold, higher_threshold"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Execution Code"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Load Configuration for Reading \"Cast Vote Record\" Data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "read_cfg = load_cfgs()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Run Election to Determine Winner and Round-by-Round Results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "election_df = get_election_data_as_dataframe(read_cfg)\n",
    "ballots, rank_to_cand_map, cand_to_rank_map, rank_columns, cand_columns = get_ballots_and_column_maps(read_cfg, election_df)\n",
    "name_map = get_candidate_to_name_map(use_candidate_ids_as_names=True)\n",
    "ballots = process_all_ballots(ballots)\n",
    "total_ballots = len(ballots)\n",
    "rounds, results = contest_election(ballots)\n",
    "results = enrich_results(results)\n",
    "print(\"✔ Complete!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create Name Map for Mapping Candidate IDs to Name for Presentation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "name_map = get_candidate_to_name_map(use_candidate_ids_as_names=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visualize Results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "color_map, greys = get_color_to_candidate_map(ballots, results)\n",
    "fig = get_horizontal_bar_graph_of_rounds(results)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "legend = get_legend(color_map, greys)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Narrate Results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "narrate_results(results)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Check for Non-Monotonicity"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "lower_threshold, higher_threshold = monotonicity_check(results, ballots)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "_[Return to Navigation](#Navigation)_"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}