course1/01_data_manipulation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notebook 1 - Working with tabulated data \n",
    "----------------------------------------------------------------\n",
    "\n",
    "## Table of Content <a id='toc' />\n",
    "\n",
    "1. **[Reading tabulated data](#1)**  \n",
    "    1.1 [Reading data from a file](#11)  \n",
    "    1.2 [Setting row names (the index)](#12)  \n",
    "    1.3 [Summary of `pd.read_table()` arguments](#13)  \n",
    "    1.4 [Reading other tabulated file formats](#14)  \n",
    "    <br>\n",
    "\n",
    "2. **[Data manipulation: selecting rows and columns](#2)**  \n",
    "    2.1 [Accessing and setting row and column names](#21)  \n",
    "    2.2 [Accessing single/multiples columns by name](#22)  \n",
    "    2.3 [Deleting columns](#23)  \n",
    "    2.4 [Data types](#24)  \n",
    "    <br>\n",
    "\n",
    "3. **[DataFrame subsetting](#3)**  \n",
    "    3.1 [Accessing specific rows and columns](#31)  \n",
    "    3.2 [Conditional selection](#32)  \n",
    "    <br>\n",
    "    \n",
    "4. **[Operations on columns](#4)**  \n",
    "    4.1 [Arithmetic operations](#41)  \n",
    "    4.2 [Applying built-in summary functions](#42)  \n",
    "    4.3 [Applying custom functions](#43)  \n",
    "    <br>\n",
    "\n",
    "5. **[Writing DataFrames to disk](#5)**\n",
    "   <br>\n",
    "\n",
    "**Supplementary Material - [Additional topics, not covered in class](#a)**  \n",
    "  * Annex 1 - [Sorting operations on dataframes](#a1)  \n",
    "  * Annex 2 - [Dropping rows with missing values](#a2)  \n",
    "  * Annex 3 - [Grouping data by factor](#a3)  \n",
    "  * Annex 4 - [Creating DataFrames and Series from scratch](#a4)  \n",
    "  * Annex 5 - [Concatenate, merge and join DataFrames](#a5)  \n",
    "  * Annex 6 - [Mixed selection by names and positions for `.loc[]` and `.iloc[]`](#a6)  \n",
    "  * Annex 7 - [more ways to add rows to a DataFrame](#a7)\n",
    "  * Annex 8 - [Wide and long format](#a8)  \n",
    "  \n",
    "<br>\n",
    "<br>"
   ]
  },
  {
   "attachments": {
    "pandas_dataframe_and_series.png": {
     "image/png": "iVBORw0KGgoAAAANSUhEUgAABUwAAAIPCAYAAACok5SCAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAANK4SURBVHhe7P17kBT1vf+P8xf8YfGPVVTKb0o/ZVGJVeYk32PqdzRlrCPq6h7WgK5wCBcRzKIuIAoqN1fIRpYNV3fVFXGXi6vLXW4CrqzAAgKyCsRsnBjUhMRjvCQxBs/36HHP5/N5/bpn+vLunnfPTM/2LDs9j0fVo2Dn3d3T0/2ennk/593v9wABAAAAAAAAAAAAgCQEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpgAAAAAAAAAAAAAWBKYAAAAAAAAAAAAAFgSmAAAAAAAAAAAAABYEpn3COdk0crAMGDBABgyeKvvPWw8DAAAAAAAAQDw5t0lGDh6QzAIGT90vRAF9SM9n8s6R/bJ//0l578se60GA3CEw7RM+kJYfpy6SAwb8WFo+sB4uIj56aYwMTu5/gIO/LVdccYtMqmuRV9/+s3xtrRdXsh4Pj9+XJxPWigAAAAAAAFAafNAiP7bbhT9ukSKMAlJ8/Wd5e0ejTLrlCvm2FQAPGDBIhgy9WiqnNcqOfpgBJJ78vrWfhjesk3PW4wC5QmDaJxR/YHpopr3/uTn4e5Ol5a3PJK6/44Q9HjMPWSsCAAAAAABAaRCDwPTzM09KuROSBjt4/C751FqnP+Bpsw+plS7rcYBcITDtE+IVmN661OzWrrpTWuqmSeVVQ2SQfUFKOljKnzwjn1vbKBif7pLx9m0OfXSRVo/H90fNlblzM7lOurj3AgAAAAAAoLQo8sC052yL3DDIbfsOGvoTmd+yM5UD7GyRuknXyxCnfKb0p35C54/Ml6HJfRss3/v5EYZDgNAQmPYJ8QpMM/WW/PrPb0jLmEudZc1u+je0nC1sT9ML8CGU6/EAAAAAAACAEqWoA9Pz8krVIKfde+nMDvlM17D/+g/S+eR4Gfr/e1IYiQ7iBIFpn1A6gWmKz+VE7VVKb9Mfy7NnCxiZEpgCAAAAAABAf6OYA9Pze2Sive8DJsoeumhCiUFg2ieUWmBq8oGsu8H9NWpQ1SuF6wJPYAoAAAAAAAD9jWIOTNV9v/pZOWs9DFAqFDwwPT5/cPINNqj8RWdWsq//0CktM25xZ1cbNESG3jJD2nKZJMicne3VFplfebVc8e3UtpOas7TfMkka29+TLzNs5NyL5amej4PGyEvWYJf2/gwdYgV8xv5cVblYdryT46RFPZ/JOzsWS+XV33ZmTh805CqpXNwuf0hOFZdjYNrzpbx3coM0TrpFrhiqjAdqHp+rK2V+2xvy56xTz30tf36jLXl83NnrBsjgb18ht0xqzP01+cgnIOz59XL5vrXOgAHDpe0jq8BPXuf0nKy7wd52JgfJ7CPWKg498uV7J2VD4yS55Yqhypgr1ix/89vkjSwHureBaXo9/FzOtM2Q6606OGjIULnluXeSyzoUpO63y2KlriSfd0abvOW716Lny/ekfXGlXOV/j/w21xFqe+Szd3Yk67bzPjNM1ssZLdKZeqMAAAAAAEAsOC7zk22MQVL+opMEyB86W2TGLWq7Wd/+0PH1n9+WV1vmG+1udaZ2t63b/t6XGdq65+TFcqutNeYla94Le3/cNmGqHb9D3slhf0x6PntHdhjtpKud9pnRpryqUha3/yE1a3yOganZ3jq5ITULvdpeMo/P1ZXzpe2NHGahN9qLb7SZx8c9vub4nd++4haZ1Jj7a3JQ933ANOkIuXo6qePtzSqsNnjWY645f5+fkbYZ9hiq5nZuEU8T+vQyawzTQTJ02WnrwQCSmY55/NV8IHXsZrR0WrlOJsyMoT2tvWufv5ZOqz5AUVHwwNQJlpIXh8/lzJPlypvXr1GRZx8KmCSoR85unizfUy6MQQ4uXydBd4B/0PJjazkzuMy2P4OlfF2W8Tc/PyG1V7lviDQHl8uTZ85kDUw/P7HYCcsyOWjobDkUlFEZb/KO2UOVW+E1DpotaflhDuQXECbkye+7692+2UrpHHpzTn8ty6/QL+t3onrvgHG+Fl/vn5xK46ChMjvwQPc+MPXUw7PGeZupjvtq6XygFqbun1j8o+C6P+gqqT1hvv4e+ezoYvlR4HNfKmM2Z3mPfJ2QtvFZ6mVfTRAGAAAAAAB9wCGZaX3X/7HZAP78jDxZrnT68Jup/dVzVjZP/l6Gdrttpva70onJbGdl2x+jHb8uy7Byn5+olauccC3dweVPypkz2QJTs12mTpwUZKasxIwCOmT20Mx5wqD0nkRZOCKzlf368VOJvEO/ns+OyuIfZTjepkYdmLrnw5zO31nj9c68VFnXMlnXbA7NdMsyNNq/TrTJ+CzHLpXrBB39ryXRkilXMr1B1tm/G0DR0HeB6dVzZXmVHQoNlu+ZKfvO1Mxq83+ihimD5IZ1mkRRuqR2iLvMkOsnSZ09O9t+s1em9yJzaW2X9o3mhkZXyA032PtjXHx+4u7PDM8b+VKp7Qq4UBoX7hbltvMBg78nlYs3JPdpZ4vbW9Dc/iBn33SB6aey+Xa73Liwfq9SpjWmtpOcgX5+pScsG3T7ZtF11vxg3Q3OcRz8o/my4eS78sknnxi+KyftY3RprXEkw5NvQNhVO8Td77QLdG/OaY98eMpczvCFaXKFtcyAK6bJC8n1bY+I2gny0823O9tLnq9pjbLBWnan+Wvl95RzP+h22RzQKza6wPRqmTjx+9b/U8dg7txpUnnVEBk0cY81jEEh6775XlycPAZmnfUEo5fWSFvbGLnU+nvwj2bo3yMZjpP/PZLcxqtvyzmzXp4zfyFWn7MPJggDAAAAAIA+wA1Mr567XKrscMtsg81vkZ1W++snalA16AbRRwG1MsRZZohcP6ku1S4x20Nmr0xPh5ig9rsSuF1xg9xg78+gofITZ3/87SGj7RwYBXhnjzfb8Is3mPtktN+dXo+Ggwa5+6YLTD/dLLfb5cm22TRpTG4n1e6aX6kGxYPkdm3DSx0Ob7D8aP4GOfmumQMYvnvSOUZmOzEcPcah907ofNVs+y7aEHxu1AUn3DSzF6P9aWcVxv5tWPwTqyeo6aVG+1oXTCrn7+qJMtHumJWsD3Nl7rTU3ZCezlI5BKbe82gcuxkt8urb55L7du7tV41zqXQyMupniyZEP39kttNmHjR0vDxpt3c/OSdvH7HzHKPN7O8/Bv2evgtMbbXJ/NeSeNYN+wYMqpJX0ga8NN8g5pt/h7wdcLt0z9ln3V9vBs2UQ5qLmxsa2ctdJbVH/bepfy4d05SgL2D8zY823+7u86UzpcPfhbznQ9kz1d+zTheY9hjHabAMHf+kdAbdRvB5h0xzQjPdNpQel0Nq5IR2I/mTb0DoCShvWOcMy5AimnNqnNScbnMw6TEumoPNi1hn0O3r3nPv+YVKIbrA1Nb4YOgIGi6hUHX/Blnufy9+vkcmKh/8KQfJDct9vT99QegVy39tFXhRn/NS40DpPvo8H6CZwlcAAAAAACgS3MDUNtnjMi0KSMiz2ea+MNt7g38k83e8HTBEXY+cfdZtdwwy2h3pzSElcLOXu6pWjvrb8J529yCpSg8mDD6Szbe7+6ybPb7nwz0y1d9rUddW7TGO0+ChMv7JTnkvYHy1zzumuYGxbhu/Xu50IBpScyKgTZkn54/IfP/rGPw9mZxhf72cN9rOdvs6uIOMJ7jUBtXp50+bwahkDUzVbQYFtWZzdaYbiKZ1Xjsveyba28gwDCEUJX0bmF46RjYHdmv33r7t+WUgZ9TKqgsVvQGONjCy+ahNhjvL6W5jV/d3iPHmCtrf9BnjAzK4rPx6+RXWNnQhnfKBlCU0zIe8A0L1IpXXfmU/p8kP0F49hw/lAyfolyj1eNy61PoFMMAjmnE+veFlFD0rw9f9ZxP68FWtZxn3Tf2lNy0MN+g5ITX2l40sIf5HbcOd5wwKqQEAAAAAoFjwBqaXjtkcOHSYJJ5U5r7IczZ2dUZ3bZvQG7gNumF5enhrobZNtLexq/s7ZKYERwG+4fvybquqw9EZz2c96qC0uQvSlgoavsDs3Tk/y9ijaq4yvE17p2yKHjlR4warM9N6APkC04Denh6yBKY9J2qc9mzmoPkjaRtubSetra3ul+bcQFHTp4HptCyjBKuBTvjxNVK4z6eb7Mf7HFc/m2met7Py7NX2tjTdp8+tkxus7QwYku02d3Vb+Qem6r7fkDYAhnLb9qCJsiPTRSsPLlxgmv2cGgcm2sBU3Z4uCDRQj0dWNfvkqesT9+h7XoYksrp/ZLYb8P90R/C+9XTINHs5zY8KZm9eeztBPVAd1GM+raOX4TEAAAAAAFxY1MA024RBaugU0ObLivJ82g5P6nNcLZmjgGflantbt2+2JohyObfuBms7A2RIttvc1W3l3VZV910zFqbSkWXQxB1pvV2j4Wv5Q/t8/bwrg4bK+Bb9fBRqGzRrpzglO0hvr3rryMQ9ObSgMwam5l2+9mu5QrI3V93X4c211OEVvy+/PKPvlATFSZ8GplmDNjWoyfFi8vXfrbE5LHfek/n51Iqe+dcX9Q2pCTnVN1/WgCfLtgLo+fIvntd2asXVznOm77tvfBHzloUss6aHoS8D07Dn1BO25fMh1POl/EV5vk9Orcj6oRYmMHVnYXTJvR4GU7C6rx7PjCdb/RKU/mva2Wfd+jpp23949jXdnXKPva28v0gAAAAAAED/IHNbwc+R2W4Ql1v76Gv5e1B7Qvt8IdrkWdqXalswW6ew/NqqPfLlX9TXdkpWZOqA1dMltcoESOZ8Ju1BQ/31FqPt/F77Yu/cH5bpQ7D1SMc0u/z/laUn1dekUW2Hp7VD88hUMgamaqe2SbLtPzT7o7rzHmdb/vrpGaoxGR6/ETB0BBQb/SswzeVi8vWf5e0dxhv06m9nnSVP93xRBabqr0qZe6qa5PjmNi8+nS0y45ahWWfJ0+67fxIq0+REVMFjX+ZKvoGperwDg+VentPwH0LGB9B7ndIy4xYZqvuFTDVge3kHyBZ5BaZ9VfcjCkzDhMoec/4iAQAAAAAA/ZNwgWkubZWv//y27FhcKVd/W3N7uMdCBqbnZN0N9nay9FQ1ybGt2vPle9LZMkNuGapOYKVTv+/+SahMkxNRBY772lu+lj+/0eKbXX6QbwJv9ZiHNK0dGnVgqtbPcKbXz8+Np1InxzI0hyuY0RI8Rw0UBUUVmPac3SxjlF9Ostmr0CjLGzJc4JXDm9s/vkkWA5+z5zN5q2WyZ1b9lIPle5PbJGDYyqzkGxCqvxTqbsuO4pzm+iGUwj+mbBYDttfXgWmf1v0LGpgOkqHzj0g+wxYBAAAAAEB/IcrAtEfObh7jTLyT3UIGpiGDuxzaqp+fqJWrsnSYcg1+zp7P3pKWyeqs+pbmJE1tCSlMbuqdtMs7XKF6rMI4WMpf9L/IkMfdpBCB6aChMv+IrrUaNGTBIBly/eL0ycWgKCiewPT8EZmtBEaX3rJYdrx9Tv7ue9dne75CBKa972H6gaxTZwa8qlpaOt+Vv/jupw8Vspm9EV9tkRnXe3+hGjR0vmjf31nILyBUB6fWDNwc0TnN5UPI5oN1Nyjd5a+S6pZOefcvvl99cthefsfDJdS57Ou6r77+jC8u98A0n2MEAAAAAADFSnSB6fkjs5Ww9FK5xbyD8tzffQFgtucLEbhlbA+q24mgh+kH65SeoYPkquoW6Xz3L76h9cKFhWZP3FdbZvjCuwJ2TFEndvLsX7j9zkwe28o5MM1eP3PGvGv45AZZXOkLrgeXS1oGDP2e/hWYqhXaN7iyOlPdkGkdgRPRRBYaZXtDZnzz+cm8LXV2tgE/fjZw9sBQIZtDj3z2Vound+L3n0xYZbmTT/jleV2DquQV39U5qnOa9UPIRp213TgPzwYf6H4VmPZ53Y8oMFVn20+fpAwAAAAAAOJLuEBKbcvc7plxWZ2hfIhM6whsDfVRYJq93eUh47bUmeGNNtqzZwNu384zeEzefar2zP2+5BEF5IB67NX9Oy97JtqP5zuZl03UganauUszkVYEfP2Hdpmt3EU8qOoV7qQsMvo0MM02ILIasPhv3871ohRZaJTtDfnr5XKFtZ0BVyw33m4Z6Dkjv3TejOnbynWf8gtMU/Sc+aW7v5qZ/rIR6kPBpOesPOscvwEypOZE2sU/qnOa7QPNIcLlQh8PH2HOZVTHqa8D0/N7JjrPN8jYTuZ3PwAAAAAAxAe1rZBtlnw1vPLPWJ5r8Np3gWmm3MKPpx2etq1c9ynPwDRJj5z5pbu/3jA6Ino6ZJq1ff/+qccqbIbhJerA1Bvmpt0NGxWf75Cf2vvgGa4AioE+DUwHXDpTOoLGbjhvXOCc3n9DpNZXk3ILjT6XHT/NvFxkgalR1WuV/a05EfQG8w8AnL6t3PbJe6ELfbFRL/o3rJOwP6CECgh7PpMO9TUPul02f2SVKUR1TuXTzXK7VT7g6mcl8K6IHAPTzB9qKUIdDw3RB6YR1v2IAlPPeQmoAwAAAAAAEEfUtoI5g3qHBEcBM907E9NCpRwDUzWYKnBgKl21yv7WSHAUYOy7Og9FvoFplg5Y2VDbgYW48+/zPRPdYe/85089VpcaZXnnklEHpmZz9XanfNDtm6UwzVWl/g6aLb3qZAt9Tt8GpqaXjpE2/8xD/oDt+0+Kv6e4+suErrei9Hwoe6q8M5P1KjTK+obsMd77yvNdalyU/XcHfP0H2eHbJ9221J54A4a3ad6on8uZ5crYm4Zp+35ktgz50Xxp187C1iNnW9z1h/jT6BzILbT7Wv789g6Z/yN11sJLjeX1t01EdU6NFy+znXFfhktb0JXu/B6Z6GxLv9znZ5Z7ZxfsB4Fpn9f9qAJTOW8cJ/cWk0FX1WYe7Nocd/fIKfkwwyIAAAAAAFAMeANT00vHpE9C3PNZhydUTB8+Tu19qu+o1PPhHqlSg8lCB6Y9XVKrzjFhtJnSo4Advn0yTNuW2stxgAzXN1BluTqpkmbfj8weIj+a3y7v+eZASdJzVlqc9dM7pmXiyOzBMuT6Gcn5VfzzZ6QwZ8r3tp/T25nqcdfXAZWeL9+Tk0d+m3Y8Q50/m2zDKHo67Q2Sq2qPBob6JubYsEdOfehtj59bJ+VDx0vLG3/WTqr1ubEPzpAIedzpCxeWPg1MBw2y36iD5UeTGmXD/v2yf8NiqfyeN2Cr1f3soF60zMo8e4OcfPcT+eSTc/L2q0/K+KHqRSRlr0KjXN6Q/l+MBv9IZrTslP3G69rQOEl+ZM9UP+gGmTnt6uBted6o5kXkSXn17XPGa/tE3j25wRdApkzbd+diMEiGXFUp86392L+hUab9ZKgy0dENsi6Xi4sP9Tx+f9RcmTvX66RbrpBvp83Mf6mM2Rw0DotBROfU/KB5pcpddpBxwXpyp/Had7bIDGO/6o5bi/kCPDO8f/LVt+WccZw/efekbJj/o/QZBftBYNrndT+ywNTA/x4ZNESun1QnLeb5Mevn/p3SUjdNKq/+tnXsc/zwAwAAAACAfozaVhgkg+xQzWgzT2rckGozL66U76ltyIAeiGo7xpy4d/aGk/Ku2YY797a8+uR4Gap2eEla4MDUwBOEGQ7+0QyrjbNBGie57cpBN8yUaVcHb8vTu9ZsPz/5qrx9zmzrvSsnN8x3MwXH9H132qZGW+uqyvlOW2tD4zT5idJWHHTDOu1rCUJt85oZzrevuEUm2RnAtEq5+tvenGLQDS3a+Vh6zrZ4OyUN/p5UTrPyoKTGMZs7SW4Zak9Y3cvzZ5MtMDXwn8dBQ66XSXUtstPet50tUqe+Vv85VOrK4G8bx8eq28n1lHpgntvZ+cy+DReUvp30qT0hbWP8PS4VBw2V2R2fBQRsPXJ2szpgscZLx8jmjmedCtur0CjHN2TP2XVSnnYRcx00dKrs+bBHeV79tj4/UStXpV3oFY0PhtoTO5wPnbR9/+glGZNhP5ImtxE0SHZmvBfL7A42e7v+IcNPR0miOacmaRdhxYl7lAvT5yekVhl4OV3zl6UTssN+vf0hMO3ruh9lYGrQ89lRWawJ/bUOGiMv8bMbAAAAAECR420rtCfaPBMR+x00dHbw8H09Z2VzphzB8NIxm6XjWbu9U/jANNlGW1ee3uHGcZAMnbpHPuxRnle7rc/lRO1VnrtJ/Zp36p3YYYd/6fv+0UtjMuxHyuQ2QkYBH6zz3uUarP1arRU1fG2cf11HH62XLpbT1nouhQlMzfP42dHFmmBa76AxL3l7ifZ0yeKsrytLRzLot/RtYJqso1/LH9oXKz3KzCT+aqmc3yZvZer/bGHONNY46RYZOsSulIPl21ebPSo7JZnPnXtRys3gbNBQWZb+LpNPd423nnewjN+VKZn5VHaNt0KebCHO13+Q9sXqLyypXp6Ld7zjdOk+92J56mIzeKrsD/hhoeezt6Rtvm87Q81fKXbIO8kNHZf5yTdywL6btzTvaJRJtwyVIU54aP0S5GwjP7JdhAd/+wq54pZJUtfyqrz9oW5YgGB6e05tzO0srrzKfe2Dvy1XVzamfzCYswW2zffUwUFDhsotkxplxzupwP74/NQ5GDx+l7bb/OllVq/dQUPk504P1tzJvR669Fndt7djvv75mV7caVlmfzhoP9RUjPd9Z4vMr7xarvD8EmnWzyuMYz9XGjec1N9GAgAAAAAARYamc0Vau9lqz7S9lfFW6BRmjuBr6ybbe/OlpfMPyduh7Tb3oKHLNG0TpX0/eLxkjgJ2yXgrQEsLyHyk2qBXu3dbJnt5LnbalcZeyYvlqTbT4Kn7RR8F9Mhnb7Ul20rqdoYa7etGO1M4Pj/VlgvYd/N28R2Nai9Nc9lvJ9vozjbywNzuqy11Mk3bjrsl2RuzM2tHKQujHf5OMq+4QmnTGpqv9YqrpXJanbS8+rb8Wbu5EOfP5vQyq/fxIBmaKUgwMepmZ4uZEfjunDWPYbJnbaNsOPmeaJurPV/Ke1Zb113XzHLMnCvE8YF+xwUITAEAAAAAAAAgvuR2NxoAQH+FwBQAAAAAAAAAIoTAFACKGwJTAAAAAAAAAIgQAlMAKG4ITAEAAAAAAAAgQghMAaC4KVhgaoekiIj5CgAAAAAAxYPuOz0iukLxQGCKiP1WAAAAAAAoHnTf6RHRFYoHzhYAAAAAAAAAAACABYEpAAAAAAAAAAAAgAWBKQAAAAAAAAAAAIAFgSkAAAAAAAAAAACABYEpAAAAAAAAAAAAgAWBKQAAAAAAAAAAAIAFgSkAAAAAAAAAAACABYEpAAAAAAAAAAAAgAWBKQAAAAAAAAAAAIAFgSkAAAAAAAAAAACABYEpAAAAAAAAAAAAgAWBKQAAAAAAAAAAAIAFgSkAAAAAAAAAAACABYEpAAAAAAAAAAAAgAWBKQAAAAAAAAAAAIAFgSkAAAAAAAAAAACABYEpAAAAAAAAAAAAgAWBKQAAAAAAAAAAAIAFgSkAAAAAAAAAAACABYEpAAAAAAAAAAAAgAWBKQAAAAAAAAAAAIAFgSkAAAAAAAAAAACARWwD07devkMmPP4vMtpwwvrd8rH1eP/iC3mt7frkPo5+/Fp57MAfrceh1PnjwRlu/V27Xf5kPQ4AAAAAAAAAAIWlwIHpUXl2ybVWIHi9PHbgfevxwtO5MRU2JX2mVc5aj/cr3n1Optv7+PhE2fR763GAjzbJo07dGC2t71qPAwAAAAAAAABAQSlwYHpAGpzQ51/koVd+Zz1eeIohMP3VrtvdfXxuE70IQeELaV/v1uFJW1+XHqsEAAAAAAAAAAAKB4HpBeOErF7i7uOjHcSl4OUfRx5x6/CSZXKcxBQAAAAAAAAAoOAQmF4o3nlGqp1jw+34oOHTrbLQqSM3yeoz1uMAAAAAAAAAAFAwCEwvEL/dO87dvyeekV9ZjwO4/E42PePW4+pdJKYAAAAAAAAAAIXmAgamygzxdffIS38U6fnspGzfcI/ca08UVV8u8zZskrc+t1bx0/OxdHX8XOYts7dzk8xY0yj7z32VQ2D6jXz8253SvGac+3yPXy8/e/p+aeo4KR+rtz9/tEUeq7O3d63cu6VT/mEVJTnfKU0r3W00nbIeD+Rj2dlib8+w7dW08Sn/cXyBNUv6tTK/4/3ksdn0vDXzf/0d8vyvrQUtvjp3UDZtuV9m2sciuVy5VK/+uWw6+b58ZS2X4qg01VvLGPu76PDH1uM23tn7791xIm3/Pj78kDOL+9im9fKO9bie3p7rr+T9M5vl+efvkeqVN8lY63nN832vcb6aO9/2ni+T86/Kcus1jn1uo3xgnu9fbZKVq8ud4zrpKWPdY/axCSg/fi547NCv35fOV4z694S9jvFcS0bIvOdXJ+ugjp7P3pY9O9TzZDzPynuk/uVX5P2vrYUU3njpJms5w2dfMF4HAAAAAAAAAAAUkgsYmKq958bJU7sWyL1OKOlz+WI5ct5azaYnIVueU8JB1boRcu9y5e+0wPSv8taee5yQS+fYZ59RwrsvpHOjElw9PlrWvfONVfaN/GrXaLfsmXXy28CEzcY7fqmu5+3ZVya65TtbpUF9PYYNJ60Fjef/7YGZUqWU6Zzw3AvKfnl7Lo5ev8cbAPcY5009F0tWyhtWUQrvhERp66fRm3P9jbzx0nD9sooTntvoPce/b5WH7PKnfynr2ka4QavHa2XO3mOyf3Nw+cID6ePL9ny4R5Y7IbnO4bLkiC9s/f12+YXvPKrqepB+fOB+ZZkFciBr3QIAAAAAAAAAgN7QTwLT7E7f4+1S2b1HCSmz6QtM/3Tg/oBwzGvVZqUn6UdbZaES8o1t2Zqa1d7z+HBZfcYOUjPgGZvyX2TF8fR11MBUpx2Y/vXk41nDUlv19Xhm6K97XDrVIM4zvqrp7bJO7ULqC1TrjnxhFQTRm3Od67o3yTOnleOoBqa91T/hUs8JWZ0h+HSsu1u2OGPTfiH7WzMFrIYbD1jLKnQtVuoqY90CAAAAAAAAABSafhWYjl25QPa8f156krdHPyNz1F6I6u3IPa/LM0oPTTOYakuY64l89edjsmmtr0eiGpj6110+z3pOo+jLd2X/RjWIvV92fppazcQbYt4kDSf/5Ol5Onb9HvmrtWxG3lsnM53tXCtPdVmPK6QFpnUjZHmnefv4N3L+P96XD5O3b3dJsxrcGcdh3elzcj4Z7n0lH55u9fVovE+2f2SWGXhCUe+EQrqw1nPuzqyUSU6Z9xjp6cW5Nso7N14vk1b9XDYdOyXv/92+1f0r+Vv3Os96M/cmrDKDtMD0Wpmx2brt/ev3Zfd6tcdwtnJvYPynjvuUsmtlzq5j1vkwj/k6WajUr0kvnUiu4+9VvPRIqs4lX8fZg9L6/B3yoG6MUt/rcHsWAwAAAAAAAABAIeg/genyx6XTM36lGZQpPfLUiZF8PSAf7fDdMt3zsexe55Z7AlNP2He7rOn29e70Baqe3p/+noX11yu39Yfo/XfycXcbAev5w9kVxzVRrOe1XCt1R9KX6Tm9TFlG7Q3qDfDc28F946vatmw1SlJ49u25TamethnpxbnOiG+7ag9NX9BYZZR5jo6vDmUrd4NK3/FZtzMtJPcEqk+vk98mH01I29PueuaQDyf+rB/n1AOBKQAAAAAAAABAn9J/AlPN7cje0PBx6bQezyVwDJr0yTsmZLWsOf6qvOZxg6x4wl3Xu88ifz3yiPZ2/qqX0idGCiR0YKq8dgXva3lE2v3jvJr0vCornGXU1/ONHN+q9KK0j5F6u/0LC2SF04PT3r43MPQfHz29ONcWyUmtts+ReU+MkElqb1TVDIFpWtCYd7kvaG7b4Ks/hjurnXL1tZxtvzut7kxoNCetOmX1UNVAYAoAAAAAAAAA0KcUZWCaS5gYFJh6181uWiB4fo/UpS3nGz8zGxEFprksk+kc9Bj74QZ41q31Sq/VhQd+p0zudK00nDReo+f1j5bWd1PbykxvAtNv5LftmSfocuyTwNR7PLOrvpYMk43V3yNb3tPUIQJTAAAAAAAAAIA+pSgD038ceUR5PFwP03CB6XB5qkud0Mg3I76qett/NgoSmIbtYWpwfp8sUXprLjzwsfx27zjr79R+qb1YzfE4PSFrFLfOWwS+3nefk+nO4/8iE5rmyPOv2b05vb2B+2NgOvbZF9LqhTlWbucrP5fZS3yTQC1fKW/4uykTmAIAAAAAAAAA9CnFeUu+Z+zOf5FfdPpGkew5J9ua3XJPmOkJKwNCxiA84dVNsnCteou1fgxRLaEnfdIHpt4Z1K+VJa+nz1bvHcPU/1xfKD1IDde3yib7dns7DP1okzxqlxuPbXrJvY3fndAoG/mf6w/a73Yff+IpecsTKGbYbsECU+9zumO/5sNX8v7BRzKcHwMCUwAAAAAAAACAPqU4A1P/bfHOTPffyPn3D0rLc9cr6xmqgalv3aq1rXLij38TZ/qdr/8m7/+mXTZtmCyTnrEn7DH5q7Svd3sEjm3ZKn/qOSPrGt1tjV5i7GMuAeynW2WhvY6hZ2Ipi5wCU18P0dHLZ8qm0x9ar0UzS/6SZXLc14PRMw5q3bVOADvWOB+pRdXzdL1MqLf/751ZPzP5n2vv4xPlhURqdvlkL809M6XKKTPsk8BU5Fe7bnceH103Rp469hv59Ev7HBp18C+/kTdea5SFjdcr59acMGyEPLZjp5z+D3uGfGPZRLPyPJrANIfeyAAAAAAAAAAAEB3FGZjKF9K5UZmwKJue2+W/kTdeGq5fLk33Of/RtVgJ50bLundSQZh/Eqjpu87kMPlTpzylBJ0z9yasx11yCkxDvZZrZeEBzXz2ag9SRXc2fV9AaFtn7FP2F2rRi3Pt602c0T4KTOWjrbIwaOIpn26dz+FW/rp5st8XuHt62D6+QA7kfMwBAAAAAAAAACAfijQwNfj8gDy10jcGpG3dCHlqb4N727t/fNGehOxcm0PQ+OwL8kFyeW9P0rHr94h7873vddTdLzs/sooC8c40P9rY3j+sEpvcAlODnF7L9TJ/z1vKPqv49j/p3bLlj1axiSa0dHug5kJvzvVfpXNj8OubsHKEu299FZga/PX0SpmRNTRVe4x6Z9dPd7jxHOln6MhmpY7b9REAAAAAAAAAAApGgQPTo/KsM7HN9fLYgfetx02+kNfa7Fvnr5VJLx21Hnf54MA0Z0bxsSub5C3rcYev35f9O+6XGfZz1JfLvA2bpOuzb0Q+3S2LrNvHx67dLh9bq7h8Je+fbJWmNePkXmXynbFLRkj16jnyfOcp+fBra9FTS9yZzevvkZd8t0X/o2uJ3KuEZ/fuOmWVBONOrmS4ZKW8YT1u84/jC9zXvmSFHLMe1+O+lp85t8z/i0xYdrtxPFql85wz4ICWsx3TZJKy/xOe2+gLmE/I2kZlmIO6EdLkmQwrG7081z0fS1fHz2Xeypus3rzGNlbeIys7TsrHv39B5ljrVe1Q7mc//6ost49F3U3yrP+U9LbcoOezt2XPy3Nk3hPlysz318vPnhgnC7cYxz05TITLV+dekeefv0eql7nHMvM5OiPrlEmtejdeKgAAAAAAAAAA5EKBA1MI5J1npNoKwkY/fruse8d6HMDG08v1JnnmdPpYtwAAAAAAAAAAEC0EphcM7y3a3uEKAET+1HGfUz90E3YBAAAAAAAAAED0EJheQLr3jHYDMf84q1Di/Em2P2fVDcNJW18PMWYsAAAAAAAAAADkC4HphcQzQ/1oaX3Xehzg3edkOnUDAAAAAAAAAKDPITC9oHwhR7aMcCYymt+hTooFpcwHHfe4E1xteFX+YT0OAAAAAAAAAACFhcAUAAAAAAAAAAAAwILAFAAAAAAAAAAAAMCCwBQAAAAAAAAAYk6XPN94vTVPxPWy6PDH1uP9jHfXyoN11nwWS1bIG9bDfcr5V+WJJdem9qFuhKz9tfV4kdP9ykSZkDz//yIT1u+W3teAX8vGZ/q6TkX1nMeleZl7jpvPfGM9DjYEpgAAAAAAAADQN5xaIZPsQLB+muz8o/V4wTkgDcmQKeVDr/zOerw/8YXsb7VCLMOxGw9Ij1XSp/y+VR5SjlXDSevxIqdzo/uaRj/TKmetx/PnQtSpqJ7zGzm+9SZnO2Nb9zF3ig8CUwAAAAAAAADoG04+7oQ0ox+fKJt+bz1ecIogMD2/R+qcfbxJnjl9gXr9EZjmSDEHpgbvPCPVzrbuk+0fWY9DEgJTAAAAAAAAAOgbCEwD+fjA/e6xWbJMjl+Q7qUGBKY5UuSBqZyRdU+423q040/W42BCYAoAAAAAAAAAfQOBaQBfSPt6d/8u2O34JgSmOVLsganIGy+5t+WPbtkawbiu8YHAFAAAoIg5PGAAolUbAAAAigACUz09r8oKZf/qjnxhFVwACExzpPgD0x7j/TjW2d4j0n7eKgACUwAAgGJGF55h6QkAAFA0ZApMz78qy+tTZWOf2ygfyDfy8a82ycrVI5yJoiYsu0dWdrwlf7VW8dPz2UnZvuEe+Zm9nSVjZOGOV+T9r3MImno+ll93NsrCp93nG11fLjPXLJHtv/rY0+PT0zOv/h55yRf8nu24x5mRfbTxWrLObXVmpUyyl398nLS9Zz1u8seNMt/en7qb5InjujC1S9autCeMulZ+ccjqK2i+pmOt0rRmnFQvs2dXNzReV/Xqn8umk+/LV6klXTIFpp/ulkXWsdXPoK/uR8As7iGOs8PX70vnKz+XeStvcgK+CcvGycItm6Trs9zGes0cmBp17bftsmnL/TLziXL33Bmv4WdPGHXulYNGHbIWdUivU8H1z1olja/k/ZOtRh2/3VnHPMf3rp4jzx/TnJtsgalzbN3XMHbJCJn3/GrZfy59a/LpVlnobO9aearLehwITAEAAIoZXXiGpScAAEDRkCkwVYO6p38p69pGKL3fvFZt7kyb1bvnvRdkvh06+Ry7coRUKX+nBU2fvyWtzymBYprXypxdSlDrCxXHrt/jln2+R+rsIPDxm2TF8aB418Uzfunjj0un9XiS8/tkibM947l0M5p7AtebZPUZ88E/yc4Wd9Z9vdfKvVt8xzJTYJq192mWQC/scTY5f0Kan8rwOoxjn8sM75kC0z8Zxz+ortmOXblEjnh6YHpfa/Wz98i9ynlSHbtysXR+bq1m03NO2jPUcdOq1j1yzpMgZzq+v5OX1w73rO/xiWfkV9aSLidk9RJ3mZl7E9bjEMtv2FsON6cJAAAQRwjNShfOPQAAFCW5BqZZHS2t71rrJfm1tDbqltPrDZpyCRZNh8tTXXbvzm/kjZfUcGq4rD5j9nT0Pj62Zaux9ex4eqw+vU5+az2e4gvZ36rsX93j0unrhvmrXbe75c6EUd5wLVjfDOkFC0zzOc4i3XtGa5ZRzPH2+kyBqacsg96JkXI9vimrXjqh9J71158gr5U57eoxDD6+/3h9XpbQ1xfEJ3lftjyrLLPxgPU4xPIbtrdCpAQAAIgjhGalC+ceAACKklCB6bVyb9tOeffLb5K3GnftutsTCM1pf99a0Sg+vUzpYfkvMvbZdfIrcz35Sj483Sq/WO6WmapBk3/dqlbrOeUbOf/+K9KgBrHqxDjnD0iD0jsvGcJ5XsNoWfdOLreLfyMH2pTtPPuCfGCV2HjHmrxWGk6q2/XOdj7ppRPW47+TTc9cL9PWNMr2M7+RT5OvyaDnvJw79rinx+2K48r2ChSY5necP5adLe7jM3f9yrpN3VjnP07Jni2TZVJr73uYnn1lokxovF+aXzsu7/zlvBVsms9h7Jdad9peVUJPf2Bq1Nf1rXLiz+YemsNJPCNz1B6natD90SZ5VFl37LPPWOsZNfbPx6StRQnQl6yUN5IlJsHH1xO6v7BHzlvP9dXffyOde+bKtKd0PUyzDVVQuhCYAgAAFDGEZqUL5x4AAIqSEIFp1cYD3luzew5IgxJAVe9K3neexNPD0t9j0qDns5fkF055hqDpiafkLTcRS+IN+hbIAaXceyv3tTKh3u1BOcnY/1yCvFSwaW/DUNfLz/faJ2193Q3u3n1OptvrOrfjZyM4eCtUYJrfcfaFycvnyZ737UAzHPkGg8HreV/rpLZX08bW9dbL22XdO6nHvUMwzJQ9/tv1PYGqOqZt8PH97d5xzuOj6+6Wdac/1IyBmg6BqR4CUwAAgCKG0Kx04dwDAEBREiIwTQ/jgoPF7KFPUNDk7cE4uvlpee34q173L5BqZ13fPveckXW6oQDq7pedvtA2mBwCU/nGeI3K7exKr0Ozd6Tu8RTmZEY75fk2/2RGXgsfmOZ/nP/RtdjTG9Z07JLJyYmYUj1UcyNbHen57G3Z8/ICWfi0MgGT3wyBqecY2njqu3u8vOHxAtnmPxbHn5YazXoZn/P3L3h7tJrW3yELd+yU01bvVR0EpnoITAEAAIoYQrPShXMPAABFSUEC01wCx6CgybduVn37bODtRWj53Kacxi5Nkcv+i++2fLsnqXdd93Z8k79K5+bMkwrZFj4w7c1x/kbOHVmgn1CpboQ8dTL7pFommYLBv55cHDhhk8ewgWnA8fLsSw7mFJga/LX7uYCJz66X+e0Jbc9cAlM9BKYAAABFDKFZ6cK5BwCAoqQggekX0r5eeVwb+kQU5C1f7J0p3TMjvupNxv67ExdlJrfAVDskgefWbfeWbxPvJEDXyr3NS2RTp74HY78LTP3H2eTrD+V0Z6MsbPTNsp9jb97AYPD8PlmiHNexK6ul6ZVdTm/PNc0B6+USmAb0MA0VmNbdLVuc90kOz9lzXt492SorV93kC8vticm8EJjqITAFAAAoYgjNShfOPQAAFCUFCUx9tzhrxoTs+XBDYEDoCYzW5zaBUIovjHWV531mpndyqcZn5Fc5DbaZfdKnFN/I8a3qrdzPSKc6Fqbxtzqpz5HNyi3863b6xtfMELyFCEwXHnCmwErx+c7AsWLzP85+zAmVnvLshzoBWBCBwWDXYiVYTK87wYGi9xhWbznsO8a+86WMReoZRsF33jKTQ2Cq8NW5l6ROmZhs7Ob0efIJTPUQmBY5f/niv2Vb558RMSb+8ZP/Sr6333r3C205ol81NDP/pg7FX/PcmvjPPaJOu74AAPQbChSY/uPII+7jhs4M7Mnedk+m3aasBk3edYfLL145Ju//3R3z8au/vy+nj6V67D20N2E9amz6nWeUyZZSvff+amxL7dWXLdCy8QS+T6+T31qP+/FOjDRapivjp6qTYJl4grAlC6TdmYX9lOzZPCZ4PzOeB29gN3r547I/ud2v5MPTrd7A2LD3x9kc+/R6mbWhVTrP/s2ZxOirP++RFUoQ2KvA1FMnb5IVR6zJkpI9WhfLDLUHcYbANNmLt82e+f8reb9znnfsVTUYNeqOO17rtTJj8yvK7PzGef7yE3nnzGZpXnOHTMgwM796fN94abjc29woe35zzpkhv+fLX8kLynsmPTDNsXdzCUJgWuT8x1++koatHyBiTEyc+zL53t7/5mfackS/amhm/k0dir/muTXxn3tEnXZ9AQDoNxQoMJXzB6RBCdCy6QkIe07Ial/QF6jznL+TLc+6PTjHrt+T6l3onwSq7hFp98+AruGD9rvddXwz8XvoeV2e0b7O0dL6rrWMhXcm9szmHph+IftblZ6rWYziOGe/lT/9tesIDEw/3SoLPdvLYMbANJPXysID6qi2f5KdLTkexwzPqR5fz+vTeq0sed3/Q2qnPKUEwjOVHwRKHQLTIofAFDFeEnZhWP2hGXUo/hKYYhgJTAGg31GowNQg08Q9Y1culrbt45y/PUGeQc97W9N6R+q0ezJ6e5KOlnXvuGND/sN4jW4v0H+RqpdOaCfb8XBmpbKOdyxSL/7bvC0bn5NuawmHnoRsUkJdr9fKvSuHO3/nHpiax6o1fTZ2y7ErF8i6LdEd57TZ9dO8Vua8op/MyE/wreffyG9fuds33qfr2JUj3J6igeHlAmlrv0cmOH97rVq7VX7r38nPX5fVT2UPTb29QjP1MNXUC8Uq4/2SNj3WH1+QOc4y18pTXdbjQGBa7BCYIsZLwi4Mqz80ow7FXwJTDCOBKQD0O06tkEl22FY/TXb+0Xrc5Pyrsty+db7uJnn2lPW4w/vJ27NT7fxr5d5d6enOV+dekeY1Y5znmLDsHlnZcVI+7hH5+PBDVqB1rfzikG/sTZOv35fOV5bIwqdHuPtoLDtp5e0y7/nVsuc31q3a8kd56Tm3/N4tnb7xOH9nlCsTE9U9JPuyTeTe86qssJc3TBsbVKHnTJNMU4cYMI7VYx3eYNLBeE37d9wvM5fZ+3O9/Ozp+6X52PvylTN2p+94ZD0PuR7n62XR4d4c5xQ9n52U7VuM17DSncRo7JIRMnNNo+z57cc5haUm3XvHOetPaNniGyf2K3n/WKOxT+VO6Dlh2ThZuOMVef9rtxfm2LXbxX1Fv5Y2O/CsXyLHkmOrbpKVq+1tmK/JPC5vpQeVNj0fy687V0v96tvlZ8o5nbDsduP1LZFNJ991bq9PoTyncXwfO6AMRWCe65fnyLwn3Ncwur5cqlf/3NiOcb6txVS8wyQ8Iu3+ibZKGALTIofAFDFeEnZhWP2hGXUo/hKYYhgJTAEAigXfTP+9mhQJIBe+kc6NSg/X5zaJOmhAqUNgWuQQmCLGS8IuDKs/NKMOxV8CUwwjgSkAQPHgGXO07nHpzLXrJEA++MbDfbSDuFSFwLTIITBFjJeEXRhWf2hGHYq/BKYYRgJTAIAi4vw+WaLcot5w0h0XFSBqek4vU8bNvU+2f2QVQBIC0yKHwBQxXhJ2YVj9oRl1KP4SmGIYCUwBAIoJ74ROY1v3cVs+FIgvZH+rezs+dS0dAtMih8AUMV4SdmFY/aEZdSj+EphiGAlMAQCKjN9vlPn25D/JiYQACsFRaXLq2UTZ+K71MDgQmBY5BKaI8ZKwC8PqD82oQ/GXwBTDSGAKAAAAEB4C0yKHwBQxXhJ2YVj9oRl1KP4SmGIYCUwBAAAAwkNgWuQQmCLGS8IuDKs/NKMOxV8CUwwjgSkAAABAeAhMixwCU8R4SdiFYfWHZtSh+EtgimEkMAUAAAAID4FpkUNgihgvCbui9g158O4KuXHYMBk2rEyGz9ytWaa49Ydm1KH4WwqB6ZJF8+TmG8337TC58Se/lPmaZTA3CUwBAAAAwkNgWuQQmCLGS8KuqD0gU0enQpek923ULFPc+kMz6lD8LYXA9Odz7nLft8Pmy8OaZTA3CUwBAAAAwkNgWuQQmCLGS8KuqCUwxfhJYIphJDDNje4NK+XKkfPlfxle+fOD8rH1OAAAAJQmBKZFDoEpYrwk7IpaAlOMnwSmGMZiD0y/eu+ErH1yldx6d618xw40J66Qu1cfkF9/3GMt1XsOrEhtO+kDe+Ss9TgAAACUJgSmRQ6BKWK8JOyKWgJTjJ8EphjGog1Mv/mT7H/S7fWp9Y7FsvDQ59YKvYPAFAAAAFQITIscAlPEeEnYFbUEphg/CUwxjMUZmH4gLy2o84ajQd7xonRaa/UGAlOAeLPlcHOaAACZIDAtcghM+8p2ue+OslTD7eaFMsd4bPmqVqm6804pvznVoLuxfJz8+4Mvyi82adbfdFJqFjXKJGP5iuHlbiPw5hFSMXaeTF18SJb713nyCRlhzRB807StxmMJqX18sfx7pT3jd7mUG+tOX35SVibXCShf+ZZ3u4or1+yTBx6cKiN/Yq9jPNfwO+Xfp62SeWt+p10HC2t/C7v89Vxr+S9krmc9oy4ubpQ7x45217uxQoaPnSn3PK6p6719f5luOCSzjLo8otzezgi5416zHnfkEJj2dn/N995CuT353GVy891rpS5tncLpD82KKzD9nSxufEGmTjOuQyNGyE32eTKvXyOq5M45G6V2g269vqqb/dOiDkzNz8OFxmfVKPd831h+h4y8c7E80Gh/nmUPTJev2i73PzRT7hhxhzObfvL99xPjM+zBNVKj/Qwz69sab73JcP6Xr9ooU++tkuH2dcWsl6OmyqRHd8rioGtRPzTqwPS/e/63tO39tWztSFiPRM/ZzY3O7fdJx6yUX+z/nXz+Var8q7/9Tl5Z/ZRckyxvlQOph3sFgSlAvCmljAAAooHAtMghMO0rN8pEp+F2v1Q9PEVp2Hu9ccxT8nPPuq/LjAl2YyvIMhk+bbMsUddbPN8tv2ux3DtOCVo93iYTH39JpmYov3tZesPxlyuXyx2ZgoYb75YpGcJWLIz9Kez6pVEHy3V1I00lzNh0RGZOucMJ4HWW/2y9L/jszfvLcP1GuesnAe+xm++Q4eXK3/7AtNf7O0eq59ztXX90Y/o+FlB/aFZMgenjj1VnPPamN/5kocxu9a7Xd3Wzf1q0gen6bXJ3ZabPwznykHX8MwWmK5f9Ivv5v3mKTG9y10luc+H0DOuNlikN7rJLli12frTUObb2V55t92ejCkztoPSme1rl//33Z+XZrW9ZJRHzxWF58A4lvLyjUdYm9GOVftW9R8aOp4cpAGSnlDICAIgGAtMih8C0r1QDkmyWybjH1YZUruveI9OfU55TDUx767hV8rizP4bPrZbRGRqCjhWPpQUVWFj7TdjV2irjcqkjphWLZX5yvd/J3Ptv0y/jsUwq5x1Qnq83769fyayfZftBQtETmBZofwlMc/bh+zTHT+OoR1931+vTutk/Lc7ANJcfD++SqVbImSkw9ZYFe/P0bU6P1VzqzcTF9nO0y7236ZexvW1O/68ntr0NTP1BqW2hAtN/7Gt2g0vDsjW/kbBTO/V8nJAd61vkp8pEUf/rjlr58f2rZPnLCfnkG2tBhUyB6Zsti90JpzQz6H+85zlnrNXv3L1N3rQeN+l+cbm17kL5xevGA1/9Xl5ZvUrKxz+Weq4xj8tPl7VLlz2BVUD5W39NFbv8Q15dsjC1zB1PyYYPzNd9RjYse0p+nHXdYIL299aJ9nPVSvmjW2T/H3RnpUc+eftoapKuKY8r488ulH+Z8pTM3XBCPrB6CbsEv45/GZNa/zvjl8ndq4846+rLX5dzmvOa5JtP5dcvb5G7718sV9lhvHFsbn10g2w4+am+fhmv++CG5z11KDnZ2JPKuYKiopQyAgCIBgLTIofAtK9MD0huGrdc5jYnjLKE1C58yNNr5capm5V1zTEUy+XWOxfL/ctelcUvWL09N70tjz/u7SU1YZHSEzQtML1NxsxJ3Qa4cs1OqVJvM85a/qDMdILP38mc6RVK2W0ybuFrstTs1WPs00Jjn251yobJ6MfecPcJC25/CbuW1D7o1pGKh+SBVWZdN+rWC3uleowdepQZ9UMJsp5bJaPsdQxvHLPEeo98IMubX5LqCUq989wq3Yv3l+85h1XMl1nJ9X4nS5ta5S5/bzY1MI14f5PDWGw4JbWr3duK+0J/aFZMgakZfN1021SpqtkuC9a+bR0349ytbpWJFcoxvudF55j2bd3snxZjYLpy6c/lZuUclN/V6JyDlS+8Jo88/IAMv/kxmW0tn7GHqfH5eFP5ZLlzzgvy6KpTzq30y9e/rNQBw1FPyEJ7vWW/UJ7/YZlpfxYb79kFi5fLuNvGuz1MW1bLaGfZO+WehtR+Jj+3n1gjk8ZUyLgS6GEaFJQWOjDtbLDCvqQrxKgmofjbsU1SrvZQ1fidu1+UA74QMVNgmq336dkNK91y3xAB6rr3NO+UsVbIl+ZdrfLK8T0ZyjfJG55A8ANZ+4BdvkJq16yTHwe97rtelM4vrNWykPP+3tEoz/sOxIc7nnED6gC/c/cG377k/jq+M2u3HNv/YnD5o/vlQ2urDn99W56ZbQWyWh+T0Wvelr9Ziyf54rQsn6rWQ5+/6JR/WItC8VBKGQEARAOBaZFDYNpXegOSG8c0ykLPbZu+iWUmr/feXh+od7ueHiuewLRMKud0eEIYT2iQtdzttdOwdYfcrdyiXPHgbl+44wtUlaACC29/CbvUsGLk7A5P2fLHH3brhxJA1j1W7T4+7H55YL27TlJPaHWnVD9tl+X//vLW8wqZvNQ3/MSGnfKzEcq6BdjfYaOf8O1v3+oPzYopMM2kp/ep0mu3b+tm/7QYA9O59yufKzc+JLOy3L2QKTDNZOB6Tz8hI53Hjc/MWS/JooDxcRs2vSgTnGXNoRrWyEI7YC1Cwwam2YJS28IEpmp4ZhpufNKexB4ZnSUstf3OrL05h6JRBaa9dfxL/2Ft1cR/rDJbtv631nqZCbO/36k77AkOc123N68js7Wy6Jja+/M/ZMujGYJPxzpZeMR9Jd3rl2qWUdTUAej/lFJGAADRQGBa5BCY9pUZgk3LoMZ9ytREE/fc45/YxGtwYKoGnr0s9/ScGSajZr4gDy3yOv2e0e66fXx7canbX8IuT8Dk9Nr8INl7eYrSg6vCaHDa63gCkRFzZLqvXj20qN7Ty8+9/TX/91f2UCV4lvxC7m9f6g/Nii0wTU4+99Ac+fdRykRMfpVz3rd1s39afIHpGzJjgnt8c/lRMet7e8MheWROnYwdO1qZlMmvut4Bmab2Pk2auvvjgSeO+SZ8+pXMnuofwqFMbh5jTtJo3ZHhWb5/m2tgmmtQ2huHT2uzni2I0/LL8fkGU5/ISwvUcKxOHnzZniiqR86/e0QWenoNesO1PgtM73pW1iZvA++RT05ulZFqWbZyT8/G9KDxO3evkx3vfmmt+5I3PDauib+31sxE2v6OeUqeOf6RmIfxq/cOyIN3KWV3eMePNY/DlfeukuUvnZJ3PjH3w8Q49ueOyHx1vSWvW2Ummtcx9UV55b2vjbKv5YOdzXKVUpat/Po1v0lu1aTn2EZP2TV1B+Tdf5jPnKoP8+9zy/7Xo/utoRY+kS2Puo/famwvNRKA+Tq6ZceTDXJVHT1Mi5FSyggAIBoITIscAtO+sjeB6Vvy8NTME43Y9klg2tQotzmP5yCBaZ/ab8KunMa59U4olut4lLZRBKaZf6gwDQ5MC7m/fak/NCumwPSXix+T4bmMR6qe2z6tm/3T4gtMg9+HQWYKTFc+/VTmSQsdfUHr+t2BEyjeNO4pb0/xDJOE3fiTx+Rhfy/lfmy2wLQvglLb7IHpcZlvB1imYQLTP++Xycq62rFP/9gu45Vl1HCtTwLTtAms/iF7fhGi3PPcvqDxLuN5PcMM9BjPrQTEU16SX1klmci8v/7X2ix78rjVP9zr+I00TglRvuK49bjIG8/Uuo9P2Spv+cY49Qaq62V/srxH9i+xHzO8a40VQkOxU0oZAQBEA4FpkUNg2lfmH+gsefwhpcFVJsPHL5SpP9f3auqPgWn5VN/s/VhQ+0/Y9ZY8ct/t2jqR0qjLUzfKL5V1QoVSN94t05w6m//7q2aW0hs6ZA/TQu5vX+oPzYomMPVNwnPjT+6TSXPWOL0+p4x3y7xheF/Wzf5p0Qemveph6puQ6eY7ZexDq5x647lDQntNMMc33ihT750sN/uC9/L7d6QNQbO8+WV54MGpcqsvoL1xwmrvZIr92EyB6Z//8mUyxNSFm4Uwe2DqC898PRgz8sYmJfz6pTSesR73cFaa71e2r4RrfRKYatbNv9x3rJTXYpNpv4LItj9yqFXZ5kpZ61sgNeHWern7/l86kzKlGep15Fvu7Sn6v+Zuk1c7jnrdul6ut8uV1/KPIy/KNc7jKb8zviE5aVWqhyoUI6WUEQBANBCYFjkEpn1l/oHO7KnKLYB3rfE04jNut1CBqe85xxbRxBWlYH8Ju9Sgv3zsVLljuNUr68YKGT7WvC31kO8WVl/AMWKJ1PjKg83//eUdm3K0VK30jTO4fotMChjDtJD725f6Q7OiCUx/+ZjyY1L6uKJB57xv62b/tPgCU9/57M0Ypquekkrn8fT3fHDQqnHDIZkxWR1b1Z10Ks1NJ2Xeg+q275ZpqzTL9UMzBaYmf/3iv2TZ88fl6vHN2pAzSrMHpr6QSxPIBZIlyEsRHL5lCgqzhYgEpin+dih4QiaPoV5HvuW+x7OqvpYeObcvYPKpOxbLwkOfW8tBMVFKGQEARAOBaZFDYNpX5h/oeB4vnyMznZmZX5YHpo7z3O7XN4Hpr2TmZPtxw4rpMnVZp/zSmfwiIb9c9bI8NGee3F5+V7+f/CRu9o+wS60jFTLh8RxnfW9YIhVOnSuTEVNblZnPP5CVL5yUBctWSdWdY+Qmz2Ri+b+/vM9pThhlz36ekEVPrJIJP/GNWajeClzA/e1L/aFZ0QSmnmuUUc9qrXEkNxyTRxc+JiPU3n/OOe/rutk/LcbA1PvjxjDfLPlHjXO+UEbeXC0zWlLLBwafvrskbnt4b2pM0U1vy8LFy2VMhVvmWW/ZL6T8J/dJ1cKX5XF7AidjnZqHleexA1NzrO+b75Q752yUBetT+5i8ptTOUWbaj09gatMXwWn2wFTkV2t+6QmovBMEZcAT5NHD1KRPA9MvDsuDSsD4nbub5BcbDjq9ORvmumXhXkcfBaZ3veibvd/gq4/k9Mtb5O57fbPs3/GMbPmjtQwUDaWUEQBANBR9YLr35EbZcrjZo+5i6F9m57HnrS0UNwSmfWVUPeAy2zeBqdE4NRuOTllm+/tYfnGzf4RdvzPqc9AkKsPkpuGjpWJElYx9aI3UrFF7d70uMyYEr+dRDT17E5j6b/XNpmfsxMLtb1/qD82KJjD1TUCXUef493Xd7J8WY2DasGmH3O0JM3W6n1XBPUWN7ZSr62RSWc/zmaj3xp+1poYKyGXomtuWy2POPvVvcw1MbXINTgszS75B904p84RTzbLj4xxug/5gr4xW1tPOCu8bw3T05nNWQeag0FM2fpO8YT2eokfealZD3hINTI+8KN9xHl8tOzzjjPbmdeRf7nlOz4RZYUmfgEutO1Ac6DICAIBMFH1gGhSQZnP9/iesLRQ3BKZ9ZS8CnU0dMjVtZl7bMhn+E3cm3r4KTM3QYeFj03MITYunB01c7Ddh1/ptMlkdJzDIm6fItKeVYMpY7+7K7MHUjVM3K8/Xm8D0g8wTwBj7N/Xhh92//ZPNFGh/+1J/aFY0gal5HZpzt6eXveqNP7nDvUap57xP62b/tCgDU8OVTzdKZcYJu3LoYWr4S+PzLfDz6+Y7ZLgTqHp7mLq9QzVWGMvaw0JkC/NvvFumqnWrnxs2MLXJFpwWLDCV/5Atj6qz2RuOWSm/2G/PeG/wzZfy6W9OycbVq+TGMfbEQ7+VZ9RZz+9YJgv3vyfnrYl80mfJf1o2KL0EMwWF3uDxMRn94m+S2+35x3vySsMyJSg0LdHA1PN4rczel5pZP9VL80UpV29vD/U68i//x75m9/GRdTJlw1vy+7+Zs+un+Opvf5DTHXtk7qxaGfmivUfmsBALZcSyPXLwN59bM+Qby37YKbPHu89DYFp86DIBAIBMFH1g+v99/aVMWnaj9gIY5Lj6H8sX//k3awvFDYFpX9ku991hN7TLZXRNZ9oyc+6vcBr+N01aK3Vq+YZDMuvBqTLSHmvP2Eb5qKlS9fghWe6M41cmYxa+4a7z5BPuLak3V8v9/uCyt+WGy1dtlKnTjP36ibvvyXEArR5aj1q3S2Lf2V/CroyBhE+nV5btppNSs3CZjB07WsqVINPs/TfyzoUydfFrqVtonXV6+f4yXLlmp0y/t8p5vhvLx8m/P9gqteZQEyt+6czEXv7gbs96SQuwv32pPzQrnsDUNCG1jy+Wfx81Qm5yjvud1rnbLHdZ5+3Gu1qcc963dbN/WqyBqenKNfuSkyi5n4ep43/H3cvkgUZ3iIUli2Y7deLG8l/IHGUbZti+ePkquXPsHc7ETTeW3yF33LtK5q05INPGWOe2YrHMd9Yx65r/3BufxcbnnXnrffJa4dv+pDvvlOHl9nu9TG7+iVk3/b2X+7/5BqY2QcFp4QJTg78el/l3ueFUZt3Q7sMdz/jCy2Cveea0Z+bzjEGhv9drRks0MP3zfpnsPJ7FUK+jF+XfnJZf5lqPnPV829O6VJ7pthaHokGXCwAAZCIWY5iG7WUal96lJgSmiPGyX4RdntnLb5NxC72T6Cxf/6p3opQiuIU5zvpDs+IKTENK3UxazIEp9r29DUxt/MFpQQNTg54/dMojd/t6muq8Y43sc8ae/Fxef8bf49PvY/LjJZ1yLtnz1CVzUPi5UV6nbEN1oYxdv1Xucf4u0cBUeuTdDY2Bx/47dy92Z54P9Tp6V96T2C9TcghN3R6j/onH/D4mozec9YTtUBzocgEAgEzEIjAN08s0Tr1LTQhMEeNlvwi7PLOX3yVVy44qve4S8ssnW2Wiekv0hNVpPT6x7/SHZrEOTKmbSQlMMYxRBaY2dnC6dqd2VqVo+eZLeffQHvnFoyvkx+OV8HTM43L9lKfk/vWvyon33FusU/TIJ28fkKbHn/Ks853xi+XWR7fIjrc/1YZd3S8ud8K+K+fvl99bjzt886l0vfS8/HSiNQHQHbVSbmzvleTz/0oarHD3O3dvkzdTayTJtt38y/8hry6xJyN6TK56Rn3WFL/f8Yxcaa3r368gsh6H1zfJVfbt9WOek11/th5P8rV8sH+L3H3/487zXjlxhdy9+oh88NUbstBa7zsLXpOPrTWyv47elht89Xs5uGGDsV+L3X03l737l/LTx3fIjtPW8AEWPR+fkQ1PrpJb7651jkW2+gP9H102AACQiVgEpia59jKNU+9SEwJTxHjZL8KuXCY8cSyTsbVv6beDfaI/NIt1YErdTEpgimGMOjAFAChGdNkAAEAmYhOY5tLLNG69S00ITBHjZf8Iu96Sh6feofTkC7JcRj64TX6p3Qb2lf7QLNaBKXUzKYEphpHAFACAwBQAwhObwNQkWy/TuPUuNSEwRYyX/SfsSsiiJ9bIPXdXSYUyOYsz8cm0RnlkFZOC9Qf9oVm8A1NT6iaBKYaRwBQAgMAUAMITq8A0Uy/TOPYuNSEwRYyX8Q+7MGr9oRl1KP4SmGIYCUwBoNTYe3JjsjOVqi4j8C+z89jz1hYAAGIWmJoEXQzj2LvUhMAUMV4SdmFY/aEZdSj+EphiGAlMAaDUCMoEshnXzAAA8iN2gamul2lce5eaEJgixkvCLgyrPzSjDsVfAlMMI4EpAJQaucxv4jfOmQEA5EfsAlMT/y9Kcf6liMAUMV4SdmFY/aEZdSj+EphiGAlMAaAUCdvLlN6lAOAnloGp+otS3H8pIjBFjJeEXRhWf2hGHYq/BKYYRgJTAChFwvQypXcpAOiIZWBqYv+iFPdfighMEeMlYReG1R+aUYfiL4EphpHAFABKlVx7mdK7FAB0xDYwNX9RmvLEv8X+lyICU8R4SdiFYfWHZtSh+EtgimEkMAWAUiWXXqb0LgWAIGIbmJp89Ndz1v/iC4EpYrwk7MKw+kMz6lD8JTDFMBKYAkApk62XKb1LASCIWAempQCBKWK8JOzCsPpDM+pQ/CUwxTASmAJAKZOplym9SwEgEwSmRQ6BKWK8JOzCsPpDM+pQ/CUwxTASmAJAqRPUy5TepQCQCQLTIofAFDFeEnZhWP2hGXUo/hKYYhgJTAGg1NH1MqV3KQBkg8C0yCEwRYyXhF0YVn9oRh2KvwSmGEYCUwCA9F6m9C4FgGwQmBY5BKaI8ZKwC8PqD82oQ/GXwBTDSGAKAODtZUrvUgDIBQLTIofAFDFeEnZhWP2hGXUo/hKYYhgJTAEAUti9TOldCgC5QGBa5BCYIsZLwi4Mqz80ow7FXwJTDCOBKQBACrOX6ZQn/o3epQCQEwSmRQ6BKWK8JOzCsPpDM+pQ/CUwxTASmAIAuHz013PW/wAAMkNgWuQQmCLGS8IuDKs/NKMOxV8CUwwjgSkAAABAeAhMi5y/f/lN8oswIsbDP//16+R7+zd/OK8tR/Srhmbm39Sh+GueWxP/uUfUadcXAAAAAMgdAlMAAIAiRg3NoLTg3AMAAAAAFAa+YQMAABQxhGalC+ceAAAAAKAw8A0bAACgiCE0K1049wAAAAAAhYFv2AAAAEUMoVnpwrkHAIALzWf/+R/YB/5Xz39aRxwA+gq+YQMAABQxhGalC+ceAAAuNMf/uBf7wPP//bl1xAGgr8j5G/bf/usT7S8d2Dd+8dVfrDPh5X/+53/k/PnziBgTe3p6ku/tr776SluO6FcNzcy/qUPx1zy3Jv5zj6jTri8AAIVAF+5h9P71vz62jriX//7v/9Ze+xGLTbMu9zdyDkxPfXRQ+8bFvvGdT9+wzoSX//qv/5KzZ88iYkw0PyxMPvnkE205ol81NDP/pg7FX/PcmvjPPaJOu74AABQCXdsVo/fDf7xnHXEvf/vb37TXfsRi06zL/Q0C0yKRwBSxNCTswrD6QzPqUPwlMMUwEpgCQCHRtV0xeglMMe4SmGLeEpgiloaEXRhWf2hGHYq/BKYYRgJTACgkurYrRi+BKcZdAlPMWwJTxNKQsAvD6g/NqEPxl8AUw0hgCgCFRNd2xeglMMW4S2CKeUtgilgaEnZhWP2hGXUo/hKYYhgJTAGgkOjarhi9BKYYdwlMMW8JTBFLQ8IuDKs/NKMOxV8CUwwjgSkAFBJd2xWjl8AU4y6BKeYtgSliaUjYhWH1h2bUofhLYIphJDAFgEKia7ti9BKYYtwlMMW8JTBFLA0JuzCs/tCMOhR/CUwxjASmAFBIdG1XjF4CU4y7BKaYtwSmiKUhYReG1R+aUYfiL4EphpHAFAAKia7titFLYIpxl8AU85bAFLE0JOzCsPpDM+pQ/CUwxTASmAJAIdG1XTF6CUwx7hKYYt4SmCKWhoRdGFZ/aEYdir8EphhGAlMAKCS6titGL4Epxl0CU8zb/hSYbqwpk2HDyqTq6YPa8gtlar+GyeTG/rVfF9SNNVJmHJNhkxvloKfsoDRONh43zmPNRvVxvNDGMuwKrIcYhf7QjMA0/hKYYhgJTAGgkOjarhi9/Scw3Sg1Zcb3+rIqefqgrvxCae3XsMnS2K/2C3O15APTI8eekLr54+W2W29KBlvDht0st955l8xe/ZTs/UC/DqYsZGCaOLNf1i99UKpGjZDy5HkZJmUVlVI1t0HaDnSnLd82L7XMxIaOtLILab/br8NPS1XyeJZLzcaEfpmke2XF+FTYW/5Iq5zSLmO5Y5GMNLdZViMbnce7ZGfTIqmpWSqtnb7naZuX3O6wiQ3SoT5+tkMaJqaO17w29XGjPnS2ytKaGlnUtFO6lMexb4xl2BVYDzEK/aFZVHXI/Gxoa1gg1RPcz4Zh5SNkQvUiWa/5bHBMHJc9zUvlwapRMqLcWs+4Do6YUC2L1h+Qbt06GMrIAtPEGdnf1iALqidwrmIsgSkAFBJd2zWs5ATZLVxgmpAz+9fL0gerZNSIcuv4l0lFZZXMbWiTA93+5dtkXnKZidLQ4S+7kPbX/cJcLenAtH3zDLktmfjrveWeBbKZi2GghQlME9K59hGpzHBezIZT1VJvcEZgmqu7pX5Uap8qardpyi07GmSifbzL5klbQrOM5e76Uanl1OBJWb+sZqN3nTwCU/s48uvchZHAFMPqD82iqEOJbYuyfDaMNK4dXenrJrbJosrUD0BBjpzXxo8xvTSSwJRzVTISmAJAIdG1XcNITpCbBQlME52y9pHK1J1gQZZXydKd6nc+AlMsjKUbmJ54XH5mXQRHzHhM1pzcmXr8dy/ImqcmywjrzThq6So54l8XkxYiMO1qm5fqrWhYfucCad7VKWessK676xVpa5grdyZ7nIyS+t3uegSmubuttiK5T8MmrJR2TbnpqbUPpJZJWiG12/TLqSHnqPrd7uOnWuWR5Hkqlxktx5TlDfMITPeuGJ/80CyrrJcdyuPYNxKYYlj9oVkUdejYqmopH1Mti5p3yYEuqzep2RtxfY2Msxs1ZbNk/SnfusdWSXX5GKle1Cy7DnRZPRRTPRdqxtnhXIUs3JKp1z1mM5LANKdzVSaz1p9KXxeLSgJTACgkurZrzpIT5Gz0gWmX0X4eaX3el8udC4zvA51nJJEs65auV9qkYe6dqbuMRtXLbmc9AlMsjCUamO6Wll/8W+qN+NPZ8mLar0O7Ze2iW1PlZdPkWX490hp5YHrYaChZH05lkxukPaBXY+L4dqmfPF6W7nUfIzDN3UTbPOsXu2pZdUy3TMLYb28Pnwkr2zXLGZ5aKw8kl8kUqvrMIzDFCyuBKYbVH5oVug51NExMnU/DB9aGCNMON8kUa72Mve4xq5EEpplU73x4YG3moWKw30tgCgCFRNd2zU1ygjBGHZgeXlVttVPLZHJDuxWU+k3I8e31Mnn8UtnrPEZgioWxNAPTD1bILCuYq27dql+mY66MSlbum+ThbZpyjDgwTciWhVbPx7IHZG2XbplgCUxD6IScQcGCfdv+RJk9e0LqnFSvkmNpyynha8VC2ZLhtn2PBKZFJ4EphtUfmhW8DrWvlAnm+TQMd711rzvD5rVpyjFXCx6Ynm2XlROsc8X7tuglMAWAQqJru+YkOUEoIw1ME1tkYUXq2Jc9sDbk8DsEplgYSzMwPfio/DRZccdJ/eua8qQr5WHrYjn+qTWacow0ME0YFxPreFcs3BLwa1KwnmAy0Smbls6UcRWpXpLJyaIWrNcMDp3SnUSkUiqsfRhWViGVmSaYsGbYTo7PaTxf64JJ1rrlMqZ2o9PzJVtgmji+R5oXVcsE/2DWTdvleEAA2X1gvSxSJsMoqxgn1YuCX1+6x2RVtbXuvLb0Y2334jFvc9hWKxXJ/XpA1vpvczW0b+9P306GGe/zCUwzzGje6/N3tlsOrF8gVfY5MCeQmdkg24/bt+eml1fNbZKdAaF+789P/zOSsOtgo0w2j1/yHJq/DDfIzHEVqfNqnq+qBcqkPenl46oXpU8gZplXHcgWmCYnCVrkmVwoNfFck1I3MEh/aFbwwFTpfTi58aB+Ga3uuM6eYUUwtIUPTJVwW/NZgMUlgSkAFBJd2zUnyQlCGWVg6t4Fmc8wSd5gMtG5SZbOHGe1C1Lt6wWBE0eaQ/+0ScMCo01eabU9DM3v/ZkmFd1YY2YNqbauOUHxgknWuuVjpHaj3SkpW2BqtHn2NHvajql20Vxp2n48IBMx26ZqG8V4feOYGLNQlmZgunlaqjIOmybP6sqTrpG6SalKe9OClZpyjDQw3V1v/VKnCdhy0A4mJ/xipdQETBihvc3/1HrnV8TUxXSUjBqlzqIccDuAHbbMXikNk33PpwQwmQLT7r0NUqVeGI3nHaVcpMurGtP2N9HeIJOt/TUv4uq+lk1/TtsLVKdz+2pFrWzzlZnjBCa3lwyD7SC7TOa1+T+43N4+6T1VM4Sf+QSmQetEcP5WTbfHyfE5cp60Hd0rTYHlxrEr0Pnpb0YSdtmB1sQ6aaod59Rzj2WTpWHvUdkUWF4tqw77ttvbOqALTLv3SkOV+iOGuU0ljC2vksZ2QtNM+kOzQgemidbZzvkK8xmS2FZrjZvNGKa9teCBaaJVZifPlfX5pFsGi0YCUwAoJLq2a06SE4QyysDUmUi4rEY2asozaweTE+QXK2sCJgnVtwlOrZ/ltjvsNvkot8NEsn2i+d5vt/Nnr3Tbf7Zu2z9TYNotexuqPB0zzDZMpdXpKznRdaN/fxPS3jDZ2l+7jeIGp9Of880dgr22JAPTrU+NSVXCshnynKY85W5pmpuqvMMeXaEpxygDU3eSofy6q9sXrNR5rZRHntklR80efYkz8nLTdGciqepVvotIcoKJO2Vu01bpPKNeCI0L2Er7YqQZ69MOW5IaF9/6rcnnS5zplF37jjjLBQamXUbDL3nLgbmutzdp94FmmTUytd6Y+t3KRdLtGTpx2V7lF6RUD8g77wvR42bvUhmT3Hf/8XbHL02FoKdk7QOp50wb3888dslt6MZC7aPANKLzN65mvew31zcnkGme5dSXsrLUL4eVjzRry6c0HVa2G+H56WdGGphajpzeIFuPmr/YdsvRrfVu0Jw85uYPBku15Wk90HtbB9LqYZe0zrZ6Tk+u9/Ym7T4gzbOsAH1MvewO6AWOfR2YnpL1s6wvlzkPD2LWqwaZbl1rmXm99xY6MHUbNITbcZDAFAAKia7tmovkBOGMLjB125zazgxZtYPJlGWVj8gzu44m22OJMy8rHWDS2wTJSUXvnCtNW93JppN275WVdscozfB03vxhstRvNZ8vIWc6d8m+I/ZywYFpV+vs1J2c5rqe3qRG29Fpb46R+t3Kdx6n/T1Rlu1Ver4abZT1C+6U+0LdZYW5WNqB6aTHZKum3PbZR83KaEhgqjXKwNSdsGOetGnKs+lcsMwLzs4uX3mXNE+3yme3pv2qFKjSuzLwtnLDTA3toMB079JUHSwzLr6HlcdtE1sWpi6gnh6gm2VBstfc7VK307t8eN3bUL0h8japTQa57oeJ3ePUOxOhEnJrP9T6KDDNZE7nr0wmr1TDTVMlfAkodz7QPfUpyvPTv4w6MB05rzVtyAn7PRFU7vzqPGGltCuPZzSXOuCvU/aPCbrerKbO+EohJjorQf2hWSEDU7eXqPF+bdQPf2K+bzfWTkj+cq/2QC4fYQ6BspOwNAILGpgmjM8mK9wum9yYR0MK+5sEpgBQSHRt11wkJwhndIGp2w7Mb0x5NzA1OzykDZ3W1SzTrfLZrbn/6OoME6Dp9eoGpiONtqs/f7ANCkz3ytIx5uNlRltc7YBj687v4um0tHlBqjfp7XWy07M8FkoCU025LRfCzPbHwDRoNndn+6F+scohwBtlXKwy9GbSB6budgNnc3ZuPVQvrm4PxpGzmns9JqY9/qhntmF1/FL/Y559cXui6sf96weBaS7bCwjfnPqSrdyzP9Gen/5ktIHpbGnVvWfsc5K1PMw1Inydcs5t4CzcCWmdndqmbqgNTOkPzQoWmJ7aKDVOkKYZdsXxmDw33f4hxKsZmgaPa4W5WrjA9JRsrLF6hgTcFofFJ4EpABQSXds1F8kJwtn/AtMJsrJdV+5uP9T3d6f9kt7+sNv5o+p2ZuiQFRCYOtvVzxNi6gw3pbZVnB6mI2VWM99d+8LSDkwzdrXnQpjNKAPTg42TU8d62GRpPKhfJpNBPTkdswRu5qQx255ZKjUPVjk9kNQxC/MN8PT75f4CVj7Cfi6/7lgkas+4UxsXuGOylI+R6kXNsit527K7TK66v5gZHwBWyGD3JvXefq/rjWo/FtTLLp/wM591UkZ+/rKUBwXwUZ6f/mS0gWlA4Jmt3D4nAeVR1QH7PWtO7uVux6szLi3jKAbqD80KEpgmOmWtPURCUI/gIBNn5MQrbbJ0RqV1m3eZVC5wJ+zD8BYmME1I51r7trSgXhhYjBKYAkAh0bVdc5GcIJzRBab2hMGGeU3sGNST0zVzXmBO/LRNnllaIw9WKd/7nflFggPTzAFswH457ZpyGaG0MTzaEw57ereeko0L7O+uw6R8TLUsaraGInSWwSgtycC0o7XKqqC5DeZcuXSVphwjnfTJuWjkd5tr/oFpQtpXuWOcBlmowDSrmhDAnIXdmYUvqdHQv3epbAo7c/eptfJAcn37mLs95/w9X9N6o9rhlhK2eu2rwLRA5y9LeaYey5Gdn35k/w5Mo60DTmCaVcKbTPpDs+gD0y7jXEXR61DZzrAxsnSvbhnMxUIEpl3G+9QZbkE3eRsWrQSmAFBIdG3XXCQnCGeUkz4538E1kxJntxeBaaI9eBJgx0IFptlNH8IvNT/GJGdyKMOySrl36aa0Ic2w95ZkYHp81ywZnqxcY6SuU1Oe9EmZd2uqAv6suU1TjpEGpk738mEyZule/TIZzHrBCghHTm2ssRpj5XLngvXyyokzSoMs/x6Ptvr9cgPTtO2GsPvoLmledK/bo3FkjWwM6NKvV5mkKLl/6eOX2vp7ozoz6c9rC2jA9k1gWrDzl6U8U2Bq2/vz03/sz4Fp1HXA+bKW1+1AaOsPzaINTJUJvYwviDWB40blaPtKmZCsQ8NkMoPl523UgWn33pXWZG9lUlnDpFxxk8AUAAqJru2ak+QEoYwyMHXmzcjrB+x8A1Nl2J/yO2XB+lfkhDqJbIb2STSBaUC7Jye75eiuZll0r9vjdGQNd0tFbWkGpm8+Lj+zKlV161b9Mu2zpTK5TKaLZWkbaWB69rA0TUmdk9xnOXbNNzDdWGP9MqMdr7BQgal7i3sUjfPE8fXWjPsZxkQN0An+zJn/7NBAN26npzdqcE9U174JTAt2/rKU5xKY2vbm/PQX+3NgGnUdcCaXyut2ILT1h2bRBaYJaW+wwtKMg+yH0Kl72b70YiajDEwT7Q1WWGpOAkdYGkcJTAGgkOjarjlJThDKKAPTs4ebZIp17CsWbgl5V0m+gelGqbG+b2jbaYUKTHfXy6jk4/kNR+g1IcfXWzPuZxgTFfOzNAPTP7bK0ntTFVw/oPNmaZr7b6nyn86VDWnlaBptYHpWTrXNs97oWRpI3XulaXqlZ2zPfANTez3txEVdm6TGCjajDUzdWe9yCdyy2yXN03XPk4POxfoBaWjQjV9q6/ZGnbCyKbAnqmvfBKYFO39ZysMEpr06P/3E/hyYRl0HElsWWteh4C9cmF1/aBZVYOreol0uVY1R3KKdkPaV1vs5zyFhMGVkgWmX0biwJvIqr2rMMJEXFrMEpgBQSHRt19wkJwhjpIHp2VPG93qrjZzlR/HuvU0yvVId2zPfwNReb5TU7/Yub9q1qcZqK0ccmCa2yEKrQ00k7cOuZpmuex7stSUamO6Vjs3TrO72N8ltc+tk49s7k48feadFnl4wSm5Klt0qD28L+GUJIw9MvWPJGQ2lOxdI865OOWM1lhJnOmVX8wK5MznhincypKwXrIBwZO9Sa2DvkfOkVRljsvtAszxS6Y4LEm1gatjR6N5q+Eiz7Fe7/huaE9i0NcyVqkWb3ccPNkpV5Qxp2HrUMyOee9tiPo19+zb8Mimzfl2b3aofC9AJCSsqUoFSxtfeN4Fpwc5flnJtYFqQ89M/7M+BafR1oEMaJ6fWK6t8RJr3q7f4GybOyP62BplbtUg2q4+jR39oFkUdOrV7qXPdDDOe5e76MVIxaa40PL9LDihDNnR3vSJtS93xb8smN+qvB5iTkQSmp3bLUvv9N7mBsDTGEpgCQCHRtV1zlZwgd6MNTA2VH01Tw201y65O+7tbQs507pLmBXemJkf2TIaUb2C6V5aOST0+cl6rMgZotxxofsQdWi3qwNSwo9EdXuqR5v1O5pHSnISqTRrmVsmize7jBxurpHJGg2z1TCqsDFWV1/ivmMmSDUzNX4daFtkXPJ03y6SmFjmiXRdNow9MDc1Zjx9xx+HQa1w8F23x9EDNNzD1X5STs9Q5M9KNk+nVqdtzIw9MDbvaapSLcJlUVPpmxDP0zMJ9sFEmW487M3gry+Z322LC2Ec3VMrYa9TpjZpS26PPsW8C04KdvyzlQYFp9Oenf9ifA9OC1AFjmzVK2FpWUWnNWDki9QXN1PMlDf36Q7Pe1yG3l3t2R8qiHe66B40vpPrlXMsqa6StS30+DGsUgak7fll2Ry7aod0GFocEpgBQSHRt19wlJ8jVyANTw0TnWk+nB63ld8qiLWoP1HwDU/XuJXO7qTbciGQHLeP74bjpUp28Wy36wDTZWaxGyT3KKqQy2d5wn9/fSUz9Tls+wr9sRENVoccSDkxNd8uOlx6TB6eMkOF2cFVeIT+d9rA88eoGLoJZLEhgmtT8RWW9LH2wyhM4lY+YINULGqTtgPqLSkp7HMPAMUE31qQuRppxCRPHt0vT3Cr3YmNcKKvmNsimzoR1UfJeqJJm2J5qtv3qPrpVmhZUywTldZrhzITq2bK0eU/aTHfmDOzmcal0ZsUrlxETqmXR+gOeXo1hTGxcIBVW/S+f/pxvFj7VHVJvf3iVVUq9Ekike1AaJ5vbDHPs8lmnQOcvS/mx56ZrywtxfvqDkQSmdqAcFDRmK9+xKPVlRlNekDrQfVS2Ni2Q6glqSGp8kTHO5+ylzbJH6c2K6fpDs97XoVOyfpb9vsqmNzC1B8VfOtu41lZWpM67qfmluOpB7bUWwxtFYHpq/Sz3/GSRwLS4JTAFgEKia7uGk5wgFwsRmCY17+hav1QerFIDwVS7akFDmxzo9q9jj0UaPCZocLs8Ice3N8ncKvc7f/mIKpnbsEk6E1b7VNP+yJo/JM22X8Z31K1NsqB6gvI6zY5UE6R69lJp3nPcd0eVOUO+eVwqnfa7+X12QvUiWa/JSLD3lnhgir2xcIEpIvYnIwlMsaT0h2bUofgbRWCKpSOBKQAUEl3bFaO3YIEpYj+RwBTzlsAUsTQk7MKw+kMz6lD8JTDFMBKYAkAh0bVdMXoJTDHuEphi3hKYIpaGhF0YVn9oRh2KvwSmGEYCUwAoJLq2K0YvgSnGXQJTzFsCU8TSkLALw+oPzahD8ZfAFMNIYAoAhUTXdsXoJTDFuEtginlLYIpYGhJ2YVj9oRl1KP4SmGIYCUwBoJDo2q4YvQSmGHcJTDFvCUwRS0PCLgyrPzSjDsVfAlMMI4EpABQSXdsVo5fAFOMugSnmLYEpYmlI2IVh9Ydm1KH4S2CKYSQwBYBComu7YvQSmGLcJTDFvCUwRSwNCbswrP7QjDoUfwlMMYwEpgBQSHRtV4xeAlOMuwSmmLcEpoilIWEXhtUfmlGH4i+BKYaRwBQAComu7YrRS2CKcZfAFPOWwBSxNCTswrD6QzPqUPwlMMUwEpgCQCHRtV0xeglMMe4SmGLeEpgiloaEXRhWf2hGHYq/BKYYRgJTACgkurYrRi+BKcZdAlPMWwJTxNKQsAvD6g/NqEPxl8AUw0hgCgCFRNd2xeglMMW4S2CKeUtgilgaEnZhWP2hGXUo/hKYYhgJTAGgkOjarhi9BKYYdwlMMW8JTBFLQ8IuDKs/NKMOxV8CUwwjgSkAFBJd2xWjl8AU4y6BKeYtgSliaUjYhWH1h2bUofhLYIphJDAFgEKia7ti9BKYYtwlMMW8JTBFLA0JuzCs/tCMOhR/CUwxjASmAFBIdG1XjF4CU4y7BKaYtwSmiKUhYReG1R+aUYfiL4EphpHAFAAKia7titFLYIpxl8AU85bAFLE0JOzCsPpDM+pQ/CUwxTASmAJAIdG1XTF6CUwx7hKYYt4SmCKWhoRdGFZ/aEYdir8EphhGAlMAKCS6titGL4Epxl0CU8xbAlPE0pCwC8PqD82oQ/GXwBTDSGAKAIVE13bF6CUwxbhLYIp5S2CKWBoSdmFY/aEZdSj+EphiGAlMAaCQ6NquGL0Ephh3CUzRUW3kICIiIiL2dwEA/Ojauhi9BKYYdwlM0VH3JRQRERERsb8KAOBH19bF6CUwxbhLYIqOui+hiIiIiIj9VQAAP7q2LkYvgSnG3aIOTCFa+PIJAABRwOdJ6cK5h76AegYAAAClCN98LhB8+QQAgCjg86R04dxDX0A9AwAAgFIk528+3JIfreqXT125X2bJRywNmeEcw6p+nph/U4fiL7PkYxh7O0u+Ws8AAPzo2q4YvdySj3GXMUzRUf3yqSv3S2CKWBoSdmFY1c8T82/qUPwlMMUwEpgCQCHRtV0xeglMMe4SmKKj+uVTV+6XwBSxNCTswrCqnyfm39Sh+EtgimEkMAWAQqJru2L0Ephi3CUwRUf1y6eu3C+BKWJpSNiFYVU/T8y/qUPxl8AUw0hgCgCFRNd2xeglMMW4S2CKjuqXT125XwJTxNKQsAvDqn6emH9Th+IvgSmGkcAUAAqJru2K0UtginGXwBQd1S+funK/BKaIpSFhF4ZV/Twx/6YOxV8CUwwjgSkAFBJd2xWjl8AU4y6BKTqqXz515X4JTBFLQ8IuDKv6eWL+TR2KvwSmGEYCUwAoJLq2K0YvgSnGXQJTdFS/fOrK/RKYIpaGhF0YVvXzxPybOhR/CUwxjASmAFBIdG1XjF4CU4y7BKboqH751JX7JTBFLA0JuzCs6ueJ+Td1KP4SmGIYCUwBoJDo2q4YvQSmGHcJTNFR/fKpK/dLYIpYGhJ2YVjVzxPzb+pQ/CUwxTASmAJAIdG1XTF6CUwx7hKYoqP65VNX7pfAFLE0JOzCsKqfJ+bf1KH4S2CKYSQwBYBComu7YvQSmGLcJTBFR/XLp67cL4EpYmlI2IVhVT9PzL+pQ/GXwBTDSGAKAIVE13bF6CUwxbhLYIqO6pdPXblfAlPE0pCwC8Oqfp6Yf1OH4i+BKYaRwBQAComu7YrRS2CKcZfAFB3VL5+6cr8XPjA9KI2Th8mwYWVSs1FXjohRGGXYlTi+SZZWj5OKMvO9O0zKR1RJ/bZT2mWL0YONk5Ovq6xmo7a8VFQ/T8y/CUzjL4EphpHAFAAKia7titF7wQPTg40y2fjePaysRjbqyhF7KYFp0t2y9+XH5L47bko2dO9sWq9ZJv6qXz515X6jDkxPtT4i5eYFL5PVq+SYs06HNExMPT6vzbstLIB7V8h4K+TyWiYVlROkelGz7OvSrBfCrp1NsqimRpa2dkpCU44XxsjCrsQ2qR1p1ZuyCqkcNUpGlA+TiQ0d+uWL0I6GianXN69NW14qqp8n5t9R1aHE8T3SvPRBqRo1wv28KB8hE6oXyfoD3dp1HLsPyHpz3coKKfOt27znONecXlqQwNQ8ZwvuTJ1rGkOxksAUAAqJru2an+QEmYw2MD0lrY+Up76fZbB61TF3nY4GmZh8fJ60ebaFGI0Epr9bJ0///N/lFuVNOP6pNfplY6765VNX7jfqwNQJGjJJYHrhbJuXfj78lldJY3tCv35W3fNJw7h/GVXYdWrtA6nzWzFbWu1wPXFGznR7lytmCUxTqp8n5t9R1KHEtkVSqf3Rxnak8VnQpV+3vVGqyu3lymXEqFEyalSl09PZfKyqsZ3QtBdGG5gm5Pj2BplRWWadH1MaQ3GSwBQAComu7RpacoKsRhuYKm3BDBKYYl9awoFp6teie26z3nzlI+S2W1P/JzC9wIHpxAbp0JSnS2DapzqBqe8DqbtLXllfI+Os4KGsepUcVstz1v1VsXxGixKM44U2qsB0d/2oVB2a3RrbYIrANKX6eWL+HUUdOraqWsrHVMui5l1yoMvqTZo4I/uV68+wioWyJeFf1/2sKJu8UvaqAX33UVk/b2Rq3WFTpOmwUoahjCwwNXuV1oyzegGXSWWlfX5oDMVJAlMAKCS6tmvukhPkaqEC05zvPiMwxQJbuoHpm4/Lz8w3V9kIuW/lCtn2uzVSN6m0L4Tql09duV8C0xIzKDC1PNw0xSqvllXH0suxeI0qMG2bl3q/xjlMJDBNqX6emH9HVYeCdK8/FVK7zVduj281bIKsbPeVmZ5aKw8ky4fJ7NZ8e8hjVIHpttqK5Lkov3NBaqiELJ89WJwSmAJAIdG1XXOWnCBnCUwx7pZuYPqbpTL3ocdk3Vu7rce4EKpfPnXlfglMS8xsjdb2lTIhWT5RGjo05Vi0EpjmLoFpSvXzxPy70IGp+4VZ83mwscbqrRj0Y85uqR+VWpfANH+jCkz3NsyUBesPSLf9GIFpLCUwBYBComu75iw5Qc4SmGLcLd3ANE0uhOqXT12532IITBPHt0vTgmqZMMIdQLp8xCipmtsk24/rG8Yba8wx01Iz7yc6W2XBJGuCkPIxUrvRO5t394E2aZhbJZUV9jhr5TJiQrUsUht7qlbDPTWDdrccWL9IqsdZ2zcnwalakGXiEmOdtgaZW+WOvVdWURk8aUniuOxpNp5jgjtBirl8ptcfaLZG6+56GZUs1wSm6utOdErrgknW/pfLmNqNcspaLuMM48Zr2d60wD1eWidL40Hvet0H1svSB6uSkwvp1/E/nzl2XpPnGJszuc9t2i7H0271LQ17F3YdlMbJ6cfc0TMucRTvqQVSZb/fzQl9ZjYodT293Hwv7AyYrKz76C7tBEOjquZK03b9JEFZA9PuA9LWMNcz8VD5CHPStPVyIEZjuaqfJ+bfBQ9MnevPKKnf7Ss7tkqqk2Vl8sDa9DFOE8a6Y5Ll3JLfG6MKTNMkMI2lBKYAUEh0bdf8JScIsv8Hpql23YLqCUpb0BzLPlPbbqPUmG3A5JwaCelsXSCTrHZJ+Zha2XhKXdbY/p5mWaRuP9mmD24r2O3dyY0Hrfat0S4IbLtoTGtLuBMw79GtVyJtj0JJYOrIhVD98qkr99vfA9OutprME4SUVUqNZoIQuxfc7JUNMtm3vnvxNi6Orcr2zRDFnETECWbLpLKmTbp823YafrNXyqrp9rhsPssmS4N24qQuaaupzD0s7N4rDVXu/lRU+iY5CTtBU5ZGq3NLbEWtbPOXK6+7YbI6iYehcr4Dw6ZEuzSmvRYlxEp+8JmPPSwtSg8yTx2wzpEbxKXCY/OxCUt2KOvMk5FWuRmuq8ds5CJ3uVKyd2HXMWl52DyOqRnx1XOR9NFWKzAv4HtqpFFnj+6VpsByo876vzDtXWqFaKa6SYL0EwxlCkwTx1ulxpnExt6m8mNGZY20BYS3xab6eWL+XdjANCHbaq1zqx3D9JRsrLHKjetrvfIF1jwn80amjv/I2m2xHVu3LyQwxTASmAJAIdG1XfOXnCDI/h2YZms7B333bpN5yfLZsrJhsm99tWNQt+xtqPJ0SjLbLmqnD92EonZbYWJdk9SO87WLbc22i65N0NWmtCU0Tm6Ug8rypdT2KJQEpo5cCNUvn7pyv/05ME20u2HnyOlLpW3/Geti1S1HdzVLjX1xKquWVb4eRc5tw8lyo3G99ah0Gw3yM527ZN8Re/srrYvzSJnVrPZ8M3/FqreeW9ObyWn4pcorH3lGdh01e5Qa23+5SaZbDXd/rzvTw6uqrQv2SJnesFWOWr8IdXcdkF3N5i9fVUpg2iWts1PjwJVNrvf+StV9QJpnWeHBmHrZnWuvyQyN1u69K53XXL3qsKcsqe91T65P7X/iTKfs2nfEWS4obDq1flbqtY+cJc1KD1yzB3G9FcCmf7DulaVj7OdTf0HslgPNs1KhaIXxWjy/Em6T2gpznQqZvV75VdD89a9hhoxZoOn5WgJGFXZluiU/qvfUuJr1sv+MUd/NyYDs82xYVmbWE/M916wtn9Lkq7fbamVk5b2yaP0r0qX++mrUhVZ7kiDNjwOZQv+V1vVq5Kxmzy+6aj0ue2BteihchKqfJ+bfBQtMu4/K1obp1nkMniXf/6NL5YwGed64bt6ZDPGNelO7qWR7kEclgSmG8YIGpqeXydBBA2SAse6gocvktPHQ139ol/nXD5FBxmMDBn9PZu3/NLWsQs9n78iOxklyyxXflsHmckkHyZChV0vl/BbpfO9L6bGWtfnr3snKsoPl2uaEVaJyWhq+N9haZoAMvrZZdEslmq91tzVoqCwzdxwAtOjarvlLThBk/w1ME9LuhJ1G23lpW+r7v1lmfHfc1ZxpwmI7MLXKjbb0VrO9brQdOnftkyPWcl2ts6XCXMb3Y7ynrTlsjNTv9nZQctoKSculapG9b91ytK3W2a+K2m2e9c6ePSyrqq0MY+R0aUhmFObj3dJ1YJc0m3dwVimBaYm1PQolgakjF0L1y6eu3G/BAtMMVq86pqwTFJiekvWzrIvJxJXSrmsEd62VBwIuRm5gGtT4drcf1CPJ6W3pDz6dhp8Z4u1Muzh1NU+3ymdLq2e/7SBvmIyp3619To927zhNIJw0sUUWWsFg2gQpQTr7bv86Zen0ABwpD63t1O+bEmqNnKfpJWgZFDbZ52TCynbP46YJ48MquY7vFzX3A9R/LE2ND5AJZllq6AXn8cNPS1VynenSzK9tjoUPTCN6T63c67ttX7kWBJSvfcDapzAz9zt1K30IiOyhv6Y3q+nhJpmS3GY8Jk1TP0/MvyMLTE9tlNoJ9vXH/oXcuCaZtz7tDAhLHbtkpxOu2t4uj6wLuG5hKAlMMYwXNDA9NNMJJwcMmCk7TtTKVVaAajto9hFrYZOvJdE23glZgx0kQ2d3yGdqatpVK0PUZX7cIh9YRQ6/Xi5XqMsM+LG0pC10TtbdoC5zg6w7ZxUBQBq6tmv+khMEWajANFjf9+SgwPTUeplltfUnGu1H3fe8rrUPWIGqvz2sBKZBPT2VjjnazkJnE7JlYarzkj9rcDOPkTIrre2ckJ11o1LlE1ZKu1q2rTYV0GpCWJ2l1vYolASmjlwI1S+funK/fR+Ylsn053IITBOtMtta54G13jFHVe2ZeP0XIzvUGVW3U9+IThgX0eQFWDNWnq0zAZLv4m03/PwXQFvnou8bBzTT+KAanWP5wFpnfFCvCWmdbW4vxC94SugZbLncuUjTU8ted1Sd7NRdsC3zCUxPGR92yXVCBab2JC++wNQJpv29UkvbggemBXxPOXUqW3nOPdtN7S9S6e9HfR1OGK89FdyOqt+tPK5qh/jBYzIXk+rnifl3ZIHpsedkuvUF2KsZmmYeA7prZ4PMHJP6gce8bUody+rOBa3Syfu9VxKYYhj7T2A6SAbpgtCZh6yFe+Rsyw2pnqc5eunsI5K64hn0HJKZnu3fLpt9nVc/3Xy7Up7ydv9C5/fIRHWZ7z+p7YUKACl0bdf8JScIss8D07Lp8lwOganToWbYA7LWczehqtshydvGtL/nj5K6nQHBpPO8wdt39sHXxnDaCkGdNQK+9+yut4LUnNospdf2KJQEpo5cCNUvn7pyv/32lvyg0NGnE7T5LkZ2qBMYJDrbt8fS1OgMquzrgWZfAANfY0AQE7LB6ART6liRPu2wQDvBks7AfUjImROvSNsidwyXtF6CWV93Sn3YdFaOPTfd+oVsnrQqwwuYtxPUWXVgzNK9nnXOnt0hi5JDHPh7FnbLgdUPWLdQzJL1vg+5jqfVsWgmydwG5RaOErXggWkh31NZyrNdd8yJn55vWCSzqyco+2P3bMw1MHWvVfb4Rum646MmB4FXtlmMqp8n5t+RBaY+E2dOyCttS2WGPT5TWaUs8E3OZ16j2le5t+1Pb7B+DOk+IOuN65bd47RscoP+jgTMSQJTDGP/CUz1Xv3s2dSyH22W2z2B52Apf/IN+fDLVDfSni/fk/bZV/kC1e/Lk06a2WM83SClbIBM3OPEqQbnZc9EdV3LiXvc0NWgx9hn9TmuWP5rqwQAdOjarvlLThBkf70lP7dcQbnTzPO9PbhjhKPz3cR356WqfRdmcvIod92g9q5jwGsKbEdpLb22R6EkMHXkQqh++dSV++23galzAcscmAY1wnIPTHPQ3wU+S3gTdIF2js1Pl8lez/J6nQtqVoNuI9CYtdGakPaV1n76u/Znfd0pAz9Auo3j8m/mdk3TJ30KGrD6QOMkax3DtEmf9ANxm6/j+Ha3J5q97J1zn5O96liWJWTfBaY5GPY9laU8+LrTJVtqx1khbZDhA9PsjpTabcUf0KufJ+bfhQpMHbuMa4Q9BvSYpZ7rZMIcj9Y6trphVtwxmIOHhMDsEphiGPtbYDroqtnSnhyDtEe+/PBteefDVCCaePL7nuUure1KG6dU5HPZM9EbiqqB5vk9Ez1lg2YeUrbRJbVD3DLHQTPlkPJEv15+hVI+RIzdAIAM6Nqu+UtOEGR/DUydNkeWtqe+bRImMM2uf4zUwPaurfY1ucfmp8v8nYR0ll7bo1ASmDpyIVS/fOrK/fbbwNS5dTdzYOr0MPX96pN7YJolkNWZNTjUX6Dd2wpyazAGBlO9MZdGq3PsA0LsLOc26AOko9EctLtMJtcskpkT3KC0fMQEqV603jOIteOpjVJjBigjZ8miBVVuUFpWIZXmeIeewbl1JuTM/jZpmHunG8xObsyxbsbLvgtMC/CeylIedN1J1Tnj8bJKmdGwVQ50qbd6B3+RyhaY5vwFsMhVP0/MvwsemBq2r5yQOvaeXsjuOLZlxjkJes/vXTomta7v8wBzl8AUw9ivAtMfPyWJr60yD/5xQ6+QoI6d/h6gA27fLM5N9Z9ultvVsiG14uSdaeOX2qqh6AfS8mOlbEiNnEhPbQFAQdd2zV9ygiD7a2DqfCfM2PZ0e5h677gME5iG/26SX2DqDqeXW/u+9NoehZLA1JELofrlU1fut98GpsdWSbW5HcPZrUG/lrgDMfsnkckamJ5aKw8kt+8f/zIHswaHARdoZ5Dn3AIlZ4wT/7ievTGXDwbnAh9lYGqPr5JpDJp07ZA5eNyW3O3eu8x6XRnG2IyxBQ9MC/meylKuv+4clMbJ5v4E1Z+wgWnQF7L4qn6emH/3RWDqHHvPecnxC2Mu1zfMKIEphrFfBabOeKV+DslMdbkBM41HAvigRX6sLuuZ3OlT2Xy7UqYEr+fW3eA8PqS20dPb1Oml6gtcvT1UAUCHru2av+QEQfbXwPTYqmrru4NuLgtLZxJk/8TSOQSmzvwi6RPAZlPfVlAMeE3O/CtZ2tMpS6/tUSgJTB25EKpfPnXlfvttYKo8HtgjUJklf0qT95b0rIHp2cPSNCW1TIVxodNPqhRg1uAw4AKtzPSnnSU/0S6rpk92wrzEloWhAtaczKHR6sxk7n/erK87pf4DxD4mFfLA6gO+Wc6DdetTnWxXxj3Nz51Sd7u5D/66VhoWPDAt5HsqS7n+uuNeQ3QTxyU6n5J7zHU076+gL0HOe6PCeP+ECP6LVfXzxPy74IGpcQ1caZ2zYRW1ss0pc8PvslnrA+uW08N0VL3s1pRjdglMMYylFZiaxT9WtjNAfpycBt87funEPZ97xzu1tuHvveodAxUAdOjarvlLThBkfw1M3cfLZHKjflvuLPlTpOmwWpZDYKqErTnvq2VQW8Ex4DU5s94HzJKfaF8l0ye732NLre1RKAlMHbkQql8+deV++29galxQjAZWKjAcJiOnN8jWzjOpkDFxRjq3NrgThPjHQzTMHpga299YY42JVy5VS7fKUd8t4eZEMc2LquXhVb4BlLMGh0EX6IRsqx2ZWjc5aYn9nOZt4+tlwZ3meJtq78cOaZxs3YZa+Yg077dev61xHPa3NcjcqkWyWX08kxkarYkznbK1YYZUWqFu2QNrpUtdJuvrTqn/ADkmz023xx1VtQfZniDVCxqkzT879o5FzmQuqs7A11UPytLmPd6Z8I3zWnHnAlnvOV4JOd46z9qWb2zWErHwgWkB31NZyvXXHeU27skrlbFrzfFtl0qVM7t67oGpM0SEUVZetVS2HvXV1+6jsqt5kVQ/vCq6XuEXUPXzxPy793Vot9SPqZBJcxvk+V0H5IQzEVu3dL3SJkun29fH9C/G7g85xrWz6WU547nmd8vRtloZZ127wn7pRVcCUwxjqQWmknhSvq+Wm7fse2bQT82e7x3vNPVYV+0Q5bGJQl4KkB1d2zV/yQmC7LeBqfFdvm2e1SPTajt3Wt8d/e3W9PHrcwhMDdXhux5p3u/7fmkP7VYlizarj2doK9gGvabENqm1x+sfOV0ath5NdSQy2/XrF8idZvtE/eG/xNoehbKEA9OV8rD1JsnsXbL8Td368VP98qkr99ufA9OcJmwxLjSr2tN/ncklMDUvgu2N7mzqbninTiqkmXEua3CY4QKdaJcGKwRNt0wqa9q8IWVXm9TYwbChO0OeOwZoqPH6nEZrZs0L8k7/BExZX3fKwA8QZ0IXdRZ1d2a/pMaHVY1nQpeE7G24W/7NLLMmfEpqz1hoWV7V6M6MvbHGqTP28XLPZ5lMbtBNEhV/+yIwLdh7Kkt50HUn0d7gTASUHPdW3Q/j2jE9ee0JEZgaJtoblbDVHIPXqpOVFe61KsphNC6g6ueJ+Xfv65DbUzRYzXXQNNkD3w5UDa3zaR77Ecr5GDl9FbPk98KoAtODRgPEOVcZrDAaOLr1sTgsjsD017L8CmW5AVeLPXm+n7QxTKd1+G6b929rmnScUcYvvfpZSW76/B6Z6Cxj9iY9I89e7f7tGRsVAALRtV1zl5wgV/tvYGrYtUVqxwW1nVPqv/vlFpiaeUNbTaX7HV77/TJ9uLG8A1NDT/vEb1pbuLTaHoWSwNSuKIESmAYZdWB68Omq5Bu3rOrpHN+0dgM6aNzDhBzf0yyLqicoFy0zhKmSuQ1t+omCDDfWpC6sacFMmqnenUsfVCYUMjQvRFUPLpKGNs3t43YgF3hh2ig1yXoZMB5K4rhsb5orVc5Fzng9VXP1z2XafVS2Ni2QamWipOTFfEK1zF7aLHvC3Kq+d4WMD3rPmIFkcj/8v65ZZn3dKe2GsneslYS0N1iTPmkCy8SZ/dI8ywpD1Nmx7ZB1pPFhkzaDfrcc3VpvfeCUyaz19m3XZg/CJlmg1pmcJ4mKr1EFppsXpMLq8gWbteUFeU9lKT/23PTA8u4D643rxzgnmC+rGCfVi5pln1GfUteJ9Pepvg67mvV1/dIHlfewYfL986AsynBdKjbVzxPz70jqUPKX8KUy23h/ptePpdK8J9N7tFsOtDUk39vquuYPIxOqFwRfQzFnCUwxjMURmPZ4b5E3/P7yX+c0S77utnlvT9Ehcvvt7m36Q5wZnrzjnQ66/XYZbv3fNHUrPwBkQ9d2zV1yglyNNjA9KE9Xmd/RyqTq6WztcMuDjTLZPBdBnYCMtvMesxel2hZ22q1B3/2ytMc9mm1KX9vR2P+KyglSPVv/3TRbWyHba0oc3y5Nc5W2kvF6quZq7ra0ly+RtkehLOHAFP2qXz515X6jDkwRte5dKmPMC3umsQWd2fntX+LcW6p1Y1CmdGcb5DbczEYVmGLpqH6emH9Th+JvVIEplobFEZiK9JyokSHqsgMulTEtb8iHX6Zi06///q60z77K27t0yEw5lJ6XpvdCdRwkMw+5Max/vFPXHwt5KUBu6NquGL3RBqaI/U8CU3RUv3zqyv0SmGJf6PQ2ynA7f6JtXuoXM+eXOPuXwUyTNLm3fWTvTVzaEnZhWNXPE/Nv6lD8JTDFMBZLYKrrPZrZS2Xmoc+tdX14xixVTY1V6vBr5VZ91SuWizVvPgBkQdd2xeglMMW4S2CKjuqXT125XwJT7AudMHTYSJmlHVC7WWZZA1q7g3a7YWjZ5HrtINdb6+2BuqtllWdmRPRL2IVhVT9PzL+pQ/GXwBTDWDyBqUHPWdk8fmhA71DFwT+SxUc/09yyb+OdFd/RP0GUdEntkPTl3Nv2ASAburYrRi+BKcZdAlN0VL986sr9Ephin5hol8YqZaImZUBtzziG6uRNhl1tNc7sh8lye5Brz6RX6YNjY7qEXRhW9fPE/Js6FH8JTDGMFzQwPd0g3xtsB5GD5XsNp62CTPTIZ+/skMZJt8gV3x7sBpmDhsjQqytlfkun/OFra9EMnD/yc+W5U+uPfNF/n32PdC27SoaovVEHl0vaYgAQiK7titFLYIpxl8AUHdUvn7pyvwSm2GcmB+xeKg9WeWe1NgeszjRhS/eBNmlYUC0T1EGukwNxV8mDYSe9KmEJuzCs6ueJ+Td1KP4SmGIYL2hgCgCxR9d2xeglMMW4S2CKjuqXT125XwJTxNKQsAvDqn6emH9Th+IvgSmGkcAUAAqJru2K0UtginGXwBQd1S+funK/BKaIpSFhF4ZV/Twx/6YOxV8CUwwjgSkAFBJd2xWjl8AU4y6BKTqqXz515X4JTBFLQ8IuDKv6eWL+TR2KvwSmGEYCUwAoJLq2K0YvgSnGXQJTdFS/fOrK/RKYIpaGhF0YVvXzxPybOhR/CUwxjASmAFBIdG1XjF4CU4y7BKboqH751JX7JTBFLA0JuzCs6ueJ+Td1KP4SmGIYCUwBoJDo2q4YvQSmGHcJTNFR/fKpK/dLYIpYGhJ2YVjVzxPzb+pQ/CUwxTASmAJAIdG1XTF6CUwx7hKYoqP65VNX7pfAFLE0JOzCsKqfJ+bf1KH4S2CKYSQwBYBComu7YvQSmGLcJTBFR/XLp67cL4EpYmlI2IVhVT9PzL+pQ/GXwBTDSGAKAIVE13bF6CUwxbhLYIqO6pdPXblfAlPE0pCwC8Oqfp6Yf1OH4i+BKYaRwBQAComu7YrRS2CKcZfAFB3VL5+6cr8EpoilIWEXhlX9PDH/pg7FXwJTDCOBKQAUEl3bFaOXwBTjLoEpOqpfPnXlfglMEUtDwi4Mq/p5Yv5NHYq/BKYYRgJTACgkurYrRi+BKcZdAlN0VL986sr9EpgiloaEXRhW9fPE/Js6FH8JTDGMBKYAUEh0bVeMXgJTjLsEpuiofvnUlfslMEUsDQm7MKzq54n5N3Uo/hKYYhgJTAGgkOjarhi9BKYYdwlM0VH98qkr90tgilgaEnZhWNXPE/Nv6lD8JTDFMBKYAkAh0bVdMXoJTDHuEpiio/rlU1ful8AUsTQk7MKwqp8n5t/UofhLYIphJDAFgEKia7ti9BKYYtwlMEVH9cunrtwvgSliaUjYhWFVP0/Mv6lD8ZfAFMNIYAoAhUTXdsXoJTDFuEtgio7ql09duV8CU8TSkLALw6p+nph/U4fiL4EphpHAFAAKia7titFLYIpxl8AUHdUvn7pyvwSmiKUhYReGVf08Mf+mDsVfAlMMI4EpABQSXdsVo5fAFOMugSk6ql8+deV+CUwRS0PCLgyr+nli/k0dir8EphhGAlMAKCS6titGL4Epxt2iDkz/9l+fyGf/+R8YkeqXT1253y+++ot1Jrz8z//8T7JxjIjxsKenJ/ne/uqrr7TliH7VzxPzb+pQ/DXPrYn/3CPqtOtLvqj1DADAj67titH7/32T+kHcz3//939rr/2IxaZZl/sbfPO5QPDlEwAAooDPk9KFcw99AfUMAAAASpGcv/n88e+/lff/9jZGpPrlExERERGxvwsA4EfX1sXo/fyrT60j7uU///M/k0OvIBa7Zl3ub+T8zYcxTKNV9yUUEREREbG/CgDgR9fWxehlDFOMu0z6hI66L6GIiIiIiP1VAAA/urYuRi+BKcZdAlPMW2bJRywNzQGvTczbEnTliH7VMMP8mzoUf81za+I/94g67foCAFAIdG1XjF4CU4y7BKaYtwSmiKUhYReG1R+aUYfiL4EphpHAFAAKia7titFLYIpxl8AU85bAFLE0JOzCsPpDM+pQ/CUwxTASmAJAIdG1XTF6CUwx7hKYYt4SmCKWhoRdGFZ/aEYdir8EphhGAlMAKCS6titGL4Epxl0CU8xbAlPE0pCwC8PqD82oQ/GXwBTDSGAKAIVE13bF6CUwxbhLYIp5S2CKWBoSdmFY/aEZdSj+EphiGAlMAaCQ6NquGL0Ephh3CUwxbwlMEUtDwi4Mqz80ow7FXwJTDCOBKQAUEl3bFaOXwBTjLoEp5i2BKWJpSNiFYfWHZtSh+EtgimEkMAWAQqJru2L0Ephi3CUwxbwlMEUsDQm7MKz+0Iw6FH8JTDGMBKYAUEh0bVeMXgJTjLsEppi3BKaIpSFhF4bVH5pRh+IvgSmGkcAUAAqJru2K0UtginGXwBTzlsAUsTQk7MKw+kMz6lD8JTDFMBKYAkAh0bVdMXoJTDHuEphi3hKY9m8P1V8jA4wG68ApbdpyxFyNMuxKnNggNTdfKRcPHJCsnxd96zqZve20dtlilPddSn9oRmAafwlMMYwEpgBQSHRtV4xeAlOMuyUdmHaefEaeWDFF7rrj3+SmYcNkmOFNt46Qu+bXyrq3dmvXQdeoA9PTbVPkEqOBZYYNAy76jtzx1Gva5bS++YLc952LUusOGCiXzdomCd1yRWj367ulqaZSrrv8W3KRfXwGXiyX/eBmua/uRek4k9Cu91rdD1PLTnpBW46Yq5GFXYltMuMSpQ5ffrl866IB8sO6EO/1fi7vu5T+0KwQgWn3wTVy3z+nrvs5BdTdB2WNeS297GIZaJ4j04u+JT+4eZY07T0Rm8+MC2VkgWnihOxtqpHK61LXh+R5GnCRfMv4zJu15qB069bBopPAFAAKia7tGkZygtyMNjA9JRtrRiaPtWn5mJnyXIduOb1dbQtkTHlq3WFllbJom76NjBjGkg1Md62dLLdYb0atZeOk7iAXw0xGHZg6QYPtxVNlc0K/rN99Nd/1rvvDOnlNs1xRmTgs6+77ZzckDXLgZTKiYX9aY5/gBqMyqrDr9OrbUnXy4vGy7k3r8cQZOdPtXa6Y5X2X0h+aRRqYJk7I9roRcpnVSzmX453YXy/XqeHb5ZfL5Zdf5vR0Nh+7rj79Ooq5G0lgmtgmsy4baJ0TvZcY5/pN3bpYVBKYAkAh0bVdc5WcIHejDUw7pGGi91hXLNyS43ezvbJ0jHfdiQ0dmuUQw1mygenaRbfK8LunSt2W52TvO9YF73cvyJqnJssI+43207mywbceuhYsMP3Bv8q/Xmw2jAbK6JYcbtVNbJapyeW/K6NHW9so9sA0sV/qr1N6zN4wS5p2H5K37GApcUYO714rNXd8xwpUr5H6Q8r6hgQ3GJVRhV0vz7k8VSfHr4ttMMX7LqU/NIuqDpm9SqdcaQVqAy+Ty+weyxmP92tS98PUcgOvqZV9akDf/bqsmXRJahsD/lVWHFXKMJSRBKbHG6Tsou/IzbOaZPeht6zepAk506Gc9wEXy9TN9BopdglMAaCQ6NquuUpOkLuFCkwnTJkiFeZxLpsl60/plvWa2LIwtfyYWTLL2gaBKUZhyQamwW6VZx/9t9SFcNhtsqBdtwyaFiww/WGdrLaDlbIGOa5ZVvV0y+jU7ZX/ukI2K9so3sD0tLRNsRvwl8jo1YczhkvdB5tk3GXDpeG493GCG4zKqMKuFyaZdTredZL3XUp/aBZNHdomM5I/jl0k/3xfk+w9kcitTh2ql2vMZQb8QGr3a8pPr5bbkuUDZPw6grh8jSQwzeTRFfKv1nm6eMY2/TJYNBKYAkAh0bVdey85gd9CBaYTG9ZK/ajU/6tXHdMsq3pK1s8qSy47pWmLsg0CU+y9BKYaj2ysTr7JTGdt1i+DhQ1MX9tXI99NNoyy9fg5Kiv+NdWAKms47t2Gdvn+b+LlOdZrHyjX1OV/iyjBDUYlgWnu8r5L6Q/NoqlD+2TRHffJmoPdzmM51am2KdaYpWVpPyylfFnmXJ7aDoFp/hY8MFV6CvO5VvwSmAJAIdG1XaOQnMBr4QLTDtm7dEzqWE9pksPa5S0PN8mU5DmpllXHvNvQLo8YQgJTnZunpd6cw26Sh7dpyjFpQQNTJQj9bs0+7fJJ7WB14GhpOe3fhm/Z7tdlt24iicuvk4krtssJ3Xipds+ka+rl0Nk3ZWfdHfKd5LoD5eIblxvPsVnus/4OHj4gIdtmpHqMZp+YxOwxZd12GGIMV5264GbzfdYEKaNb5LSyrGpi24zU5FsDp0ib/bgVOKT2v1sOrpklN19pTZxiTt5znTfEULVnDb+m/lBq7MEVE+W6b1nDDZgTrtxRJ9tPEFL0Z3sXdh2S+muMc22eb52+XuTdB1+UuonXyWUX27ffZpnsJa1u3pehfqWXXzdxhey0x1P1qZ1wzVjn8usmyort+kmCsgam3QflxTrjPaBMPHTRt34gN89aIwdjNJarPzSLKnT3m1Ngat7mbS5jXKdvW/1mWrn7IxW35PfGwgembrB9+ZyXNeVYTBKYAkAh0bVdI5GcwGMhA1M3CB0jS/fqlk9pB6tls9bLKf82fMt2H90lzUsflKpRI6Q8uW3D8hEyqmquNG0/rv1uf7BxcnK5yY0H5WzXTmmYOSa1blmF3Pe0uZ9PS1VyW5n287Csqk71gk1uR7sM9kcJTDVubhydevMMGyf1r+uXwUIHpmfl6Ip/Tf2dITi0x0S8eOrm5AUuODDdJzXfTTW0TC/6ljnhx+VKKBMwkcRrdfLD5PYeljpnnDvbSfLC2dPSMtraRtDwAc4Yq7mMyWrfctr7BqEuuHGGLwjsaZWQzVMvTq7nCVVfmJTa1vhaaRjuPw6WA6+Ruv3pwae9Hz98eIXMcMag83mJcSwDQiu88PYu7Douq36aer85P1SYoWNy0h3DqrVWPUvIiXVT3Il87GXscNN4/1w2RfMezaVumvXr9X2yIrB8hmzzX2OcXu6mukmCLpFJL6SHb5kC08SJdTLFmdDG3qYbxg68bEps3gf+0OyCBqbqMCfGdWqOEnab52SSNQ7qJTO25d2jHwsfmDo/5jGGaSwkMAWAQqJru0YhOYHXggamZw9L05TU38GTP+22bt2vkIVbzO8GGQLTvUtlTPLcmZbLiFGjZNSoSqkosx8bKfPaurzrGHY0TExtr65B5o20l7WcZ3bYcCecqqgNGDIox/AX+58EpmmultqfWm+Ae2tll3YZNC10YHr2dIuMToYTA2XSC5rGkTLZU82+1GPBgek2mXHJZXLDrDXS/pbaE9IMaSY5jbAZ29R1DO3A1PKS0U3SccbYl+63pH1vRzLoSWyeKhcny/W9kxIvTLJ6Yk6SF7L1GHXG2htgvGZNeQi1wY1zzAbIv6446lk+Vf6CTNIdczuUSjpQLhu3Qna/bh7HhJzZs0KG2xOvaEJjZz+SXiTXPfRi6hie7ZbXX5whV1oBFGPS9V+jCrsyhVuJ/bXWe+0SGd2k9iY13qPb58g1Vr1M6yHoq5tXTlmTql+JM9LRNNp6bw+QgQPNoNKsu9Z72Fee9n4ww5nLbpBZa9rdydZMEydknf3jycUzZJu6jmFgYJrYL7XW7cTmdUTtTZo4sV3mXJMKUgfetjoWM4D7Q7MLG5ga+ifSG1Ena5vuk3+27hC4csYG/V0GmLOFC0yNz4otdc7nDLPkx0MCUwAoJLq2a+8lJ/Bb2MD0rJxaP0vKzONdNk/aNN/T3Mmelsre5GMZAtNttTKy8l5ZtP4V6fJ8tz8urfNGps5rRW3ad3s7ME05UmY175czxr50d70ie149lVzmcNMUa/2FskWzn842JjZIh68M+7cEpj53Nd8lNyXfDLfKw9u2apfBlAUPTM+6t6frbiFXJ3s6aj0WHJhm0h0XLXnbuFqmBKYDr6mT/boGdcYQ0n0Ndi9Yb7lP5/l0k5Mcl4ay1POkedGUtA8RfXDj9iBVj5utE+76e/U6odRAuWbOzrTG6ptNFVb5eFkXtB/aCawSsvNha4KvH9TKfk8Z9hcLH5i6PbWDevk5Pc79obxaN2v3+W7bV3qAB5Svvs3apzAz9zvv02uk/pC3LCgwda5Xut6sps6ENkG9v4tLf2h2wQPTpOawKsOdkDzl/yPjmjNPrIe5GV1gelra7v+B0wvd7pl+0bfM4XPSP3+wOCUwBYBComu79lZygnQLHZieTbTJvGQP0DKZtT4VTrqqkz0dth7LEJhmsqNBJibP7WRpPOgtcwPTMpnc0K7/zuj0ILV7uqrl7j65+4nFIoGpaucCudPqkj3i0RXSrlsGHQsfmJ7N0HvTHuPUe5t7foGp2+j+Yd1r3jInGKmQpgy3yu6r+a7+eZ0emzneQphvYDrgh1L3mnf5oODGvdXYv06GcNcOpYJCTWe/M+xHUCDlBF7mEAeacrzgFjwwdd4nl8ucl5XHVffXyg909SRL3XTqX7byUNcMY3+T+5Lr+859bwUPtbFfan9gbrP3vcv7g/7QrD8Epm/urJM7vpPqZTrw4ss8Y1n/833r5LAuyMacjS4wPS5PDbd/6PBqhqb3BY1njEUlgSkAFBJd27VXkhNoLXhganyH3rKwIvlY2uRPdkhZNkvWn7IfzzMwPdsm88xtDZsoDR3eMicwnd4sXcrjXt3wtmxem7fN64SxU6TpsPI4FoUEpra/apIFP7sp9Wa4bZas/UCzDHrsi8BUHXvUM/mTb7KnzNtQNCd+WlsnM8ffLD+weq+oPViCA9MsYZ4TQrrDA5g6vco0t+5qdZ4vx9DECRtDBKZBx9QZAkEzNIH9PIGhUtgASTHXY4wXzIIHpk4dGCgXX+a+Lz06kyT5enVmq5tZyrNdM8yJn9bWzZTxN7s93txxR3Ot724vdjOo87wuR3d81LSe7kWoPzS7sIFpQvY32D1LL5HhddYkf90HZc2s69xhG4LuIsCcjC4w9Zk4I2+0vyg1Iy6zrgED5bL72gInLsTikMAUAAqJru2at+QEgRY+MDV0xh71jv/pnezJfjx7YGpO/PR8wyKZXT1BRiXHMTW1J4HKEJgmxyv1lqm6wweoAa67n8OqV8kxZXksDglMTT9okTrnIjhNnv2VZhlMs28CU6X3phM6ureV+3tCZgo/3tzsjpcZZN6BqTKrv9uDzL0dOONM/6qJdTLe2pecJn3KKzBVbm++fI68bD3mhLvfrZF9yrJJCUxL2r4LTHPQf0t7wQLTN2XzjCutgCbI8IFpdi+RGdty6I3ez/WHZhcyMHUnC9JP1NW9r9YaI5eJn3pjwQJTxzeN821P3Ob9cRKLTwJTACgkurZrXpITZLRPAlPdpEqJLbKwwnzMfwt8psC0S7bUjkuFmoHmH5i6+zRMHlhrDx9g77tuSAEsBglMP9ggTY/emnoTlE+Q+oO79cthmn0VmLpj+1m3tTs9IdMbTIHbeK3emTTGnOxjy6G3PLf02Y3u/ANTdVZ/K9jNsJ/BKrfdf3eOvJytt1Oegal6TFO9SbOEuwSmJW3fBabp9SerBQpMX6u/JhWWDrxMRtRtkUOeyeLC1nc3ME27xsRUf2h24QJT99o20FgmKAx1fpgbOEXaNOWY3cIHpobO0Bzx6IldyhKYAkAh0bVdQ0tOkNW+CUyN75W+SZWc3pzOZE/Zt9HRONnqAVopMxq2yoEu9bt9DrfkZwtM1eED7N6kdu9YX69TLB5LPDDdLM/aF8GycVLHRTCUfRaYKhOzmJM/7beDSc2kRUHbOFR/TepxpUelahSBqXpLuxnsOj02g4KcAJ31zElq6rOEK/kGpkqIkOyl6+x7QGBFYFrSFjwwPb1abkvWgYEypU15PBcLEpgekvprzP0J6ukdtr4r17Ap2b5sxUN/aHbhAtMcw2rnWsp1KF/7JDB1Pi9K58eHuEpgCgCFRNd2DSc5QS72VWB69tRaecA8F8memu3SNCW1XPokSkHbOCiNk1OPj6rfrTxuG0VgaugMH5Aar9QZNsA/rikWjSUcmO6WzU+NS810VzZCHt68WbMMZrLvAlM1RLxELrnE/Nc72ZNt0Dacx29bnT7uWeKwLB1mbrOXgaknhFwnTVZAkj5zfjZfk/prUtsxe7dNWXci+AKbd2Cqjq86VdY13ZZaVhNCJyUwLWkLHpgqQ1pcbJSFGpuwIIGpG7Ldtjr9OpM4vFSGmeuEqO9uD3SjnivjLsdVf2h24QJTN/w2f3ALqltOD9OAH9Uwu4UPTBOyv9Z6f+nG2saiksAUAAqJru2au+QEudpngakyqdKwkSNlZPLc6HptBm3Dfdy9Xd410fmU3GNus7eBqTJ8wJSmVqkfZf5fN3M+FoslG5juevEeGZF8U9wqs7gI5mVfBqZnE5tl6sWpRm/Si6fKZs3t6kHbcMLBgddI7T63+33ixHapuS41a7Jp7wJTZVb/gQOtgNc/u3+OvvmCTEoGw6bmMAI1snb3IXmr2yrvfksO7V4rNcPt8dzyCCqdY2rsa7J3aYZwl8C0pC18YGq8R9umWONMXiTX1WyR1+26bmlOvtQ062b56RO+23ALEpgqt3FfUyv7nH1JyIntNXKdM7t6iPp+uk2mWO/pi66rkS2vq7cBGZoT0jXNkpt/+oQcUh8vUv2h2YULTJWw2pzwacUeOeP57OiW1190x7em12L+RhGYvjznu3Lx1ROlbu1uOfTGGefHwu632uXFmuHKBF31AZ9FWCwSmAJAIdG1XXOVnCB3+y4wNdrZWxZKRfK8pKxYuEXTqShoG8os9pNXyl7lu/3x7Uulqtzebm8DU2X4gLKy1BAAFalhBHTLYv+3RAPTJ2XerfabIotlk2Xlm7ptYJ8GpobbZqQmejK9eIY14LPPwG0k9kud3WtzgDUTtzPrttGIHp5ar7eB6dmz22SGGuzqerTm6ps7pc6ZFTizF123PO2YZQ0qDdVjOmDAbbI6qOcbgWlJ2xeBabL3WP111uzzphfJt6wZ5C+72H7vasYtLEhganwp21/nTAQ0YODFcpm6H5cMl+HJHqjh6ntif70Sthrv229ZM+Q71yLDa+oJTAN1e4tm1tf70Lj+Nzg/Lhla59M89t9SzsclwxuYJb8XRhGYOsPnZHDgZVPkhTf162PxSGAKAIVE13bNTXKCMPZlYGq2s2utSZXMXpu12jtNgreRaG+QyWXW+mUVUjlqlFRW2L1Wp8v05Hq9D0zPHlsl1cl9TKkfAgCLxRINTFdL7U/dSpxRLoSBRh2YHlp+XTI0GHjdcn1gsK9W/skMMAb+k9QGTKLkbGP4U3LcX959UNbMulmutEMPo9F85c2zpOmVN+Vs25TkemlhzKF6uSa5bO4TgTi3dgYMGxDOhJzpeFHq7rtZfqCGKskG/3VSWbNCtna4vXBU7YZnxjET99XId61tZrpd1T4+wWFOm0xJhkvXSP0hb1nW/cjjGGPfGlVguvm+VG/ui+7brC1P1fc1UlN5nSckNYPF6ypnSt2LBz2TtSXNVjezlB9/anhgeffBNTLr5ivlYis4HXjxlXLzrCZ55c2z0jbF3L/w9T1xpkPW1FTKder7+aJvyeXXVcrMuhfloK9nbbHqD80uaGCatFsOvlgn9938A0/dGnjxZfKDm+/T1y0MZRSBabLH7+4mqRnv+8yz3iM1TXvlBKF2LCQwBYBComu75iY5QRijDUwPytNVZoBZJlVPH9SUn5W9K8Yne22WjV/hm+zJ1t3G9OeOpZV3H1gvi6rHSYUVnJZVjJPqRc2yr+usbKwx15ssjQe96xxsnJxatmaj5/FgleEDho2RpXt1y2CxWKKBKUZh1IFpXHRv/x8tLf19rEJnsqcowl2Mq4W6nRrjqz80ow7F32gCUywVCUwBoJDo2q4YvdEGpvHRnuwpfRZ/LDYJTDFvCUx1KrNhT3qh38+Gd3q1NdnTwEnyAr12MEDCLgyrPzSjDsVfAlMMI4EpABQSXdsVo5fAVOdua7KnoKEFsJgkMMW8JTDVeHSF/KvRSDRvCZ26ub/PhqfMTD51c78Pd/HCSdiFYfWHZtSh+EtgimEkMAWAQqJru2L0Epim605ONUWaDuuXweKRwBTzlsA0XWf80oBZ/PuVzvilxRDu4oWUsAvD6g/NqEPxl8AUw0hgCgCFRNd2xeglMPWrjF86pUkOa5fBYpLAFPOWwNSvPSHJQPmn2n2a8v6lMznNP9XKPk05oi1hF4bVH5pRh+IvgSmGkcAUAAqJru2K0Utg6nej1CQnlCqXR1pPacqx2CQwxbwlMEUsDQm7MKz+0Iw6FH8JTDGMBKYAUEh0bVeMXgJTjLsEppi3BKaIpSFhF4bVH5pRh+IvgSmGkcAUAAqJru2K0UtginGXwBTzlsAUsTQk7MKw+kMz6lD8JTDFMBKYAkAh0bVdMXoJTDHuEphi3hKYIpaGhF0YVn9oRh2KvwSmGEYCUwAoJLq2K0YvgSnGXQJTzFsCU8TSkLALw+oPzahD8ZfAFMNIYAoAhUTXdsXoJTDFuEtginlLYIpYGhJ2YVj9oRl1KP4SmGIYCUwBoJDo2q4YvQSmGHcJTDFvCUwRS0PCLgyrPzSjDsVfAlMMI4EpABQSXdsVo5fAFOMugSnmLYEpYmlI2IVh9Ydm1KH4S2CKYSQwBYBComu7YvQSmGLcJTDFvCUwRSwNCbswrP7QjDoUfwlMMYwEpgBQSHRtV4xeAlOMuwSmmLcEpoilIWEXhtUfmlGH4i+BKYaRwBQAComu7YrRS2CKcZfAFPOWwBSxNCTswrD6QzPqUPwlMMUwEpgCQCHRtV0xeglMMe4SmGLeEpgiloaEXRhWf2hGHYq/BKYYRgJTACgkurYrRi+BKcZdAlPMWwJTxNKQsAvD6g/NqEPxl8AUw0hgCgCFRNd2xeglMMW4S2CKeUtgilgaEnZhWP2hGXUo/hKYYhgJTAGgkOjarhi9BKYYdwlMMW8JTBFLQ8IuDKs/NKMOxV8CUwwjgSkAFBJd2xWjl8AU4y6BKeYtgSliaUjYhWH1h2bUofhLYIphJDAFgEKia7ti9BKYYtwlMMW8JTBFLA0JuzCs/tCMOhR/CUwxjASmAFBIdG1XjF4CU4y7BKaYtwSmiKUhYReG1R+aUYfiL4EphpHAFAAKia7titFLYIpxt6gD0+5PjidDU7wwnv3rGetMePnqq6/kD3/4AyLGxP/8z/9Mvrf/8pe/aMsR/aqhmfk3dSj+mufWxH/uEXXa9QUAoBDo2q4YvR9/ec464l7+/ve/a6/9iMXmF198YdXq/kPOgSkAAAD0P9TQDEoLzj0AAAAAQGHI+Rv2N//ztfz3/3yFF8ie//3f1pnw8n//7/+Vnp4eRIyJ/+f//J/ke/t//+//rS1H9KuGZubf1KH4a55bE/+5R9Rp1xcAgEKga7ti9P7P/+mxjrgX83uf7tqPWGzabZj+RM6BqdkNXDeWBvaNjGGKWBoy/iSGVQ3NzL+pQ/GXMUwxjIxhCgCFRNd2xehlDFOMu0z6hHlLYIpYGhJ2YVj9oRl1KP4SmGIYCUwBoJDo2q4YvQSmGHcJTDFvCUwRS0PCLgyrPzSjDsVfAlMMI4EpABQSXdsVo5fAFOMugSnmLYEpYmlI2IVh9Ydm1KH4S2CKYSQwBYBComu7YvQSmGLcJTDFvCUwRSwNCbswrP7QjDoUfwlMMYwEpgBQSHRtV4xeAlOMuwSmmLcEpoilIWEXhtUfmlGH4i+BKYaRwBQAComu7YrRS2CKcZfAFPOWwBSxNCTswrD6QzPqUPwlMMUwEpgCQCHRtV0xeglMMe4SmGLeEpgiloaEXRhWf2hGHYq/BKYYRgJTACgkurYrRi+BKcZdAlPMWwJTxNKQsAvD6g/NqEPxl8AUw0hgCgCFRNd2xeglMMW4S2CKeUtgilgaEnZhWP2hGXUo/hKYYhgJTAGgkOjarhi9BKYYdwlMMW8JTBFLQ8IuDKs/NKMOxV8CUwwjgSkAFBJd2xWjl8AU4y6BKeYtgSliaUjYhWH1h2bUofhLYIphJDAFgEKia7ti9BKYYtwlMMW8JTBFLA0JuzCs/tCMOhR/CUwxjASmAFBIdG1XjF4CU4y7BKaYt7EKTA/VyzVG427AwCnS5itrmzJQBhhl19Qf8jxeuh6S+muMYzXgIrlvs64c42Ysw662KTLQfM9fUy+HdOXYK/2hGYFp/CUwxTASmAJAIdG1XTF64xSYHmycLMOGDZOymo2+so1SUzbMKJssjQfVx7EULOnAtPPICqn7+V3y0zv+TW4y3hzmG+SmW0fIXfNrZd1bu7XroGt0gelmue8iM4AbKNfUv6Yptz0ta8ddlAwvB/5TrezTLmN5/CkZPtDc5jVSf8h+PCGH19XIPffMlBU73/Qu/1qd/NDY7oABk+QF9XHDFyaZjw+QH9b59u3NnbJi5j1yT806OZxQHi8C99V8N/mawvjdmn3W+q9J3Q9Tj016IX3bGD9jGXa9MClVt39YJ6/pyrFX+kOzqOpQ4kyHvFh3n9z8g2/JReb5M73oW/KDm2fJmoPd2nUcuw/KmppKue6yi1NhubJu094TktCtgzlbkMDUPGf3/XPqXGt+0MTilcAUAAqJru0aRnKC3IwsMN28QMrN41w2WRo7NOW2p1rlkXLzfJTJ+BV79ctYHntuupSZ25zcKAftxxOd0rq0RmoWNcnOLu/yHQ0Tk+d52Lw2z+Nnz7bJvGQdmCgNvn3r2tkki2pqZGlrJ98jY2rJBqa71k6WW5IVP8CycVJ3kIthJqMLTE/L6tusxmtZgxzXLmOYeEEmJUNQ0x9K3WuaZSxPr74ttdzASfKCE2Ya6yfXNfT3KssjMH2t7oepbQ0YKFPavOv0d3fMusTa99wlMC1dCUwxrP7QLIo6lNg2Sy5zPgN0XmJck3w/htnr7q+X65I/zJleJN+6/HK5/PLL5GJnexfJdfX7+bLbC6MNTBNyYnudjLgsdYdHyvTPZyxeCUwBoJDo2q65Sk6Qu5EFpqfWygPW8a1edUy/jGGibV4qBDWd2CAdmmVSnpK1D6SWK5vX5n6/M9a3z+PkxoOedcIHph3SMDG1rWFlNbLRsw7GxZINTNcuulWG3z1V6rY8J3vfsS54v3tB1jw1WUZYb6Jh99bKLt966BrlLfnHG8qsBtF4WRfUW/PlOXK503AaIGUNx/XLGQ2tFyZZjazbVstp5/F9UvtP5uMD5bLZO5TlDfMITE+vHZfq9XLRCFl13LtOUeocg8xhNIFp6UlgimH1h2ZR1CHzc+Ki79wss5p2y6G3rN6kiTPSsWaKXGkHnwNHS8tp/7ruNWvgNbWyr1sp635d1kyyf0D6V1lxVCnDUEYWmJq9SqdcafUCNj6vL7PPD4FpnCQwBYBComu75io5Qe5Gd0v+MVlVbR3b2a2BP2Dvrh+VWiZptaw6pl/ubKJN5iVvox8mD6w95T6+d4WMNx8vq5T6HcryhuED01PS+kh5cp3yGS1yzLMOxsWSDUyD3S0tv/i31Jtl2F2y/E3dMmga6RimTlh3sczYpik3dHt0Wo5fF3AxfVnmXJ5aJjhU9ZnPLflxk8AUAyQwxbD6Q7NC1yH18+G21ae95fYY1QN+ILX7lcdtT6+W26x1x69LpJdjTkYVmG6bcXHyXFz0z/elhkqw36sEprGSwBQAComu7dp7yQn8RjmGqRNYVtTKNk25p0en5ezWgO9tu+tlVHKZDKGqz3xuycf4S2Cqc/M06004Ruo6NeWYNNpJn9yQ8/I5L2vK7dv2B8r48WNSjaeLZ+gvpk7wF6K3EIEpgSkGSmCKYfWHZgWvQ/tr5Qfm+TRMu1bbE3wNKJMG7d0A7ucPgWn+RhWY7lt0h9y35qB0248RmMZSAlMAKCS6tmskkhN4jHTSJyfkHCX1uzXl9m37ZbNl9kPmcsOkonZb+nKGTvg5pUkOa8p1EpiiTgJTjR2tVak3y7AqefI3+mUw6sDU7VWiDTCc8Utvk9WvNUhZsvF0ucx52becoXN7v2Y7gTPe5xOYZphZ37zNc3dTjVRed7l8yzNu3nUyccV2OaEbdsDeXnJ81dT4bXdcaU1OMvBiuey6+5RJTdLLr7x5lqw73IvGfr6B6ZuvSNN91zmv86Jv/UDuqAt4jbaayVcGXnxZ5olbrNBj4BTzQ6xbDq65T677VmoSsOTELXfUyfYT9utPL79u4grZ+aZvm6bWcU9t96x0H1wjs26+0hrbcKBcfNl13sa7R/N5ZikT0BjLX3mzzApcPrX9msrr5LKL7bH5zOf4gdw8a40cVG8Vdjwk9deYy6UmMEuc2C4rJoY83r00krCrgPXbnQhIGZPS3OYPMpyLbIFp4oTsbVLPbaqOmvXIrWcYpD80K3hg6ly/NNf34/ZnxkC5bXX6GKeJl+fId5Pl3JLfG6MKTNMkMI2lBKYAUEh0bdcoJCfwGmlgenab1FaYx3aYTGzoSCt3xi99YK10rKpOnYdR9bLbt5x6e3/6doJnvM8nMA2eWd9o8x3dJc1LH5SqUSNSE1qZlo+QUVVzpWn7ce2dsvb2kuOrJo7L9oaZMq6iLPUcFZVStWC9HLDbi2nl46R6Uat0FrBNWIoSmKbZKsun3pSq0IxNktGoA1PztrtUeKbpBbRthlxsliXDFjewS+/1mZB141Nlup6qgeFnPoFp4Dr7pOa7qXVML/qWObnI5UpANkAumfSCvOlZx9De3g8flhUz7PHbfA68Rur2vS4bAsuNY5dvgz+PwHTMY3XKRCpeta/R0Dv5is6AyVfsRvP4WmkYHjBp1SXGuXh9n6wILJ8h2/wfIvbrnrRG9tVd58687TP99SRkf9011nkwQ0/zPLvB6fCn/MNBGMvXB28/6UXXSf1+fxhnH+8fysMrZrhjNfoMOt5RGEnYVaj6fbpFRjvHxD4P6g8VA+Waugz1SReYdu+TuuussN3ZphLGas8TqvpDs0IHpol1453zlT4J32lpm2JdE4w6Nme7OyN+4sQ6mXRJ6rxeMmNbwDAvmIsEphhGAlMAKCS6tmvvJSfwG21gmpC2eanwb1j1qrQxQbfVViTLkmFiR4NMNJfT9fpMtMrsZJmup2pw+JlPYBq4zt6lMia5jmm5jBg1SkaNqpQKa1zVYcNGyry2Lu86hvb2JtY1Se0461j4LJvcIHuPbgouN45drr1qMbsEpopH3mmRpxeMkpvMysbsd1mNOjB1g4+BMukFbxhhj09nh6Avz7k81YBKm1V/m8y42NyGfizUvglMjX245DK5YdYaabcnJkmakBPrJsklyXU0++dsL+Ulw+tky+vm+t3y+pY5co0V1gwcmApeL7quRlt+8dTN+TX6nefPPTBNetF18tCLHXLGDCK7X5cXnbBL8xrffMEJJwZeOUWadr9u9f5LyJmOF6XGCTovMdb1BVJOo9l0oFw5ZY10nDGWMSd9aRptHVf7+AyUy8Y1acv/dcVR73bt122sZ+63OW7emo4zyWNo9lxsGm3v08UydbOyT06vtR/KY/uU82z2nr3vn+VGXy+3N439T+2Due9Nsjt57owyc/9erJHh1nFJD3V7cbwjMtLA1DKy+m2eh4v+WSau2CKHzfPtlHXLvlo70Nb8CBMYmL4p68anersPvGaOtzepcW6d+vDdOfIyv+AG6g/NChuYnv7/t3e3MXLUd57A/WrmBfIbSxbyIltC1h4SaK3wxo6EtYeVMawdheDAocOcZUs4a5zIyF7kHJyjzWgxc5tgZDZnhVwGnAuZQwMoBmKIZWdt8xBAGLybeDPamwixUpRIIB3RgVbrzSTS7/qhuru6pnq6a6Z7bHd/PtL3hbuqH6a6pt31nX/VP8bvTP4gtWx3TOa9L1MnYyxVgq/6wsF46siu+EylWC/9Tu753z0dpT0IUZhKkShMgV7KO3ZdSPQE+eluYTod731/X3UU6ciDMdH0vax2/dJaCfpSjN1RLQhnzar//GhsLj9G7rVQF6kwLb2G27b8ZTz8/Z/EO+kzCKfejB88eFv1Pjmvr/54ldwWXz38XLxevv+F1+O5sR3VbXPzSIxUitdb495v5i3fHH/9bPqYSBaSwS5Mz34jdt75xdhSzpf+IvkA/Iv4T195II78zIdgu3S9MK1fp3RJLNuTvh7Jm3F4pHx7qhCqjTgtn6KfnhG5NpP+UOnAKufgd3EK07nSKL9aXxagPFrw6KyD91cO/IfKslbL6yXymtE4mbq949Sfv0BhuuLO+G72NOmpF+KB5HqAa0ZPNi2r/wzLtsbRvNPjp34cX6uNzs2W4fWD5qFYN/pK5jTrVGHSYnlt35o1WVib7Z5+TUN3jsf52u2Tu6qjRf/kgXghvX5uGqOOl5WeP3fkbf204OxkZfPf3t1KtwvTRdu/65fyyBl12KowfeVA9X1oNVp7ajJ2z/FHGakmW5r1sjCdKv1/UPtjxLqxzOd0U87FCwc31f94Us2fxN3fe9XI0i5EYSpFojAFeinv2LVQ9AQdpduFaf06pTdvjtH09+yffSfuK9+eKhlrI07Lp+i/V1uvlNpM+iMPTuR8v1ukwnSu1EfHznFZgPII1B9kT9t/Ob55V3lZq+WNEvmex06kbpeFZLAL0+MPxBcqO1wm5Q/Dv/p6HH3Xh+Fc6X5hmrr+6LVfix/Xbk9fv7RWjqaKkPRo1PpMyV/8bqPYSuXSF6adPN7WOJot7cqpHzS2Wz7Pg8r683demLaaIKX2My7Z/nTq9pMxuqZ6e/7EXtXU94Hsz1n7+VoUZvX3vt3ybEHWbruXcnJ0TfW+6YnG6iNMV8SdR1pfs7SS+oQ0+dfdrab2h4FSmkrd+W7v7qW7heli7t+NbTdrgrLa42X2h3afIeXR0LXLfsz6HZZ6sqVZzwrT8xOxszZqfd3BONnid7iccy8cjC/9aXWUafl6tOnrS39m19F4dY77SvsoTKVIFKZAL+UduxaKnqCjdL0wTV1/9I6xl+q3p69fWitH67c1jUZtzKR//1Pv1e/fyGVQmHbyePt/kPvH/IkHy/frYHmh1yNzZbAL00zO/vxoPH30/vjPtyY72q33xN+a/a5lelGY5pZ2tdGkTSMO80ajNm5rHqHXyKIWpuWJn546GHu3bow111avq5i+tmLhx2u3fKEHlXnbPjdzlFBJ6qVTU4H3dGyvPH6b2fVro4Szr6NFwdXp8vaF6RzbLXfbno+JXavq19q86k83xr4jL8UbeRM3dfje1EdRNr3G+W7v7qW7hWmLbbDA/bt8+YTnDh2IL29ZX/9dS193tNPCtF4+X3V16nGaU/sdrk0UJrOTLc16UphOvRrfrV0iYc7rN0/FycO1kaUrYlNtkrTy5TP2ra+POG1XuMrcUZhKkShMgV7KO3ZdSPQE+el+YZoqDbcdjlPJbbXRpE2n3+eNRq3fdl9852fJbU1Z3MK0PPHT/zr8cOy/7564o3Id03Jqk0AVf7x2yxWm3Y/CNCevnf56/Jfkgryfe+Bv41TOOtKjwnT6x/G15PTiWulZG92XHZU4azRqfdRp68JvsQrTc5OtJ+epZeAK0/rjtylMW72OFgVXp8u7X5iWU52Nf21qQq8lQ6tiw4Hm6yHWn7vNe5P/GhWmlbR8D9JlWOsULkzbZqj0GZW5Hq7Uky3Nul+Yniu9V42JnA6ezB99XU7jlP0Vpf1g9iz5F14ZrV8j18RP84/CVIpEYQr0Ut6xazeiJ2hOLwrT6ZfG4o5y6VcvPU/EY/eU/52dxGn2aNT6qNNU2dqcxSpM34lnR+9OrinaKgrTKyEK09y8FEf+a7KzjeyJ/5m7jvSmMJ2O5/ckE65sf7p04Jpz/dJassVabSRqq0KtlEUpTH86lhx8VycWefbMu02na8/nNXS0fKEHldntmbdOJfMs8KaOxtbK47cpTOsjTNfF2JnU7S0Krk6XL6QwbczA3WqdC/HGS0di34bGiNMVOyfqp3S3v3819RGm68biTP12hWklLfbv8xM7kzKsfFr1k3Hi7eqEXdXlc2y7FvtLvTDt0bYclGRLs+4WpqkJvYZWxc6cErSRxvWNq/+n5K2Tuobu0M6YyFku7aMwlSJRmAK9lHfs2p3oCdLpSWE6/XyMbi5v45F4cGIq9/qltdQLxKQgrY1E3Xb4VNN6jSxOYXrq8WQCppEtsefwc/H376QmCF7AiFWF6eJHYdoiT/y3ZGe7+SvxRM5y6V1hOlU6OKocCJevF1kv2fKua9g8GrXVSNR0FqMwPTO2rrJ+03VYUxnYwrT0n9+eymQ5c09O9PqhP6/eN3290HJaFFydLl9IYdr5hENT8daTW2dPSFafpGxNjJ5Mr5/O63Hoz8vrZCc9U5hW0mL/ntiZjO7NveZo8cI0v7SWosmWZt0rTKfi5MGkLG0xYrQ5jX1g1mduOgv9/BSFqRSKwhTopbxj125FT9BIbwrTqZh4cKSyjTePPh9TP9hf3d551+1sGo3aaiRqOotRmJ6Ox3eU12++DmsjCtMrKQrTvPzjt+L+zyc72+6/ieN560jPCtPp89+NL1YOjq6Nrx3Mu35pI7XRqEu2HopDrUaiprIYhWm9vMorcKZejW/eXPw1dLR8oQeV9cfvVWE6VdqWSbm1YmdM1MrEdFIz0i/bPdn8n2KLgqvT5e0L06G4fs/k7Bnszz8d25Oit7nIbJFzR2Jz5fFS27F+uYjmkafpNGbJXxa7J9OnFytMK2mxf9d+P3P/UHLumfhy8keVTgvTqcndSbnd7vdA5kq2NOtWYXqu9L7VRhSvHzvZcsRoI2dibF11Hxi6c7zFRF6pEaYt/tAl7aMwlSJRmAK9lHfs2pXoCZrSm8J0Ot576v7qNr5jLA7nXb+0ntpo1Jtj/5EjLUeiNrIYhencE09Nnf12fLnwa+hsucK0+xnMwvSf/nvcd+vtce/YaDz104k48X+S299/Pl545WA8sPVz1R3t5s/HA88/N/v+UknPCtPUbOFDQ9WCrdWIxMZo1GXVkmOodEA1x6Qdi1GYnh+/MzlVdF2MvtIYfj/11o/iwPrqDM1FX0NHyxd6UFl//F4VpqXUn6P03l6/M548UbtcwYV498STseszyfbJm8ClRcHV6fL2hWk1KzYdjGdfrZ7WfeGNZ1PvWfN2OTO2vnrJhTfSp1ikThXOjJCtP3+5mN35ZJx4N7nfhXfjxJO74jO1iYRGDsfrqfspTJO02L/rRdeK7XH0rUbRfOH0kbh7VePasp0WpuXtPbYuOYV71d1x5FT6FP9Spv4hTv3wYGxbvzcm07dLU7KlWTf2ofM/PlC/3Mm6g52UpdXUR62XJ3w6dDz+oen/iAvxxg8b15ye9bksHUdhKkWiMAV6Ke/YtaPoCQqlV4Vp/TT8m0dipHLN2HvisRM566VHo26uFqsjD07M8R1xMQrT9+L7+6qvaWTHY/FyfULgqXjzR9+Me2sThylMr4gM6AjTx+KB5GLNrbMxth8Zj9dy7y/l9K4wTZdL5cwxarQ+GjVJ7mm5jSxGYTo9dTIOJoVL+cB+2apr49pVy+qnkG7aVP3ZBrIwLZ9O226CnqHrY89kzmm2bQrRdsvbF6abY/vOxjVImzN7NFv90gulXHV18+zpuacKl/aLw5uSSWpaZOj6PTF5LnWfShSmlbTav889HdtXVLdP+X26ujyT/dW14v362DRSPcW+88K0lNJj7kyVrUPLViUz5F8dVyW3udbl3MmWZgvfhxp/SGufFbHvWOq+2d+9oWWxqvJ+pn9ny38sOWyW/AWkW4Vp+rN1rnQ04l8u2yhMgV7KO3btLHqCIulZYZoapVnJHKNG66NRk+SN6mxkMQrT6Zg6cTh21Pajkc2x5Y47Ysvmaol6821fja9WfjaF6ZWQAS1MX47XfjkeT3z7r2L3zi/G5+st/+di05fujHu/8fV44rUXcu8njfSyMJ3+6aOxvjbibtW+eL7lQeyb8Z0v1EYAXhVf+E51Zv1WqV3vcN3YmeZlZ8ZiXfkxckqQ+dxn+sLpeHLfxri+Nnt66QD9+o374shPzsX0xM5KKVfo8TpZfmxftYicb5FzprTNy6OshtbHo+nJlmaldorrUOycyFveOOAd2pn/YX3h9A/j4Lb1sao+u3y5WF4TG/cdiZdTowSbkmy3lteWbLP8zW9vyl/eVNSVZ73fFxuvTwrucrGyflsc+tFbOX+pLK97ILasXxXLktFpS666OtaU3ucnT6dHnWbuUxmdmLpP+TnWbIx9R15umlm/kYVv74WmK4VpD/fv8ujtQ6X9qV5+ld6H9dsOxjOvTiXbJmfbtdufLrwRzx7aFRvXpEvS6nu19cAc+6lUki3NFr4PNSZvap9MYVpJ9Xdv18Y1qc+dahm+ZuOuOPjD002T80nxKEylSBSmQC/lHbt2Gj1B5+ldYTodp/7HvXFrZduPxJaHn289avRn47Gn9j7duifGKzPrt8ozcaBSZO6Ix083Lzv9+I7KY4wceKbp9vndp3S8+/ffj4fvuzs2J8XpyOa7476HvxevvDMdzxwol6fFHq+T5ccevm3O5VI8A1uYysLT08JUZLHSbmSjdKcwlYFKtjSzD/V/ulWYymBEYQr0Ut6xq3Q/vSxMRS6HKExl3lGYSl9EYdo2yi4pmmxpZh/q/yhMpUgUpkAv5R27SvejMJV+j8JU5h2FqfRFFKZto+ySosmWZvah/o/CVIpEYQr0Ut6xq3Q/ClPp9yhMZd5RmEpfRGHaNsouKZpsaWYf6v8oTKVIFKZAL+Udu0r3ozCVfo/CVOYdhan0RWqTDV21KybzlouySwonW5rZh/o/ClMpEoUp0Et5x67S/ShMpd+jMJV5R2EqMhhRdknRZEsz+1D/R2EqRaIwBXop79hVuh+FqfR7FKYy7yhMRQYjyi4pmmxpZh/q/yhMpUgUpkAv5R27SvejMJV+j8JU5h2FqchgRNklRZMtzexD/R+FqRSJwhTopbxjV+l+FKbS71GYyryjMBUZjCi7pGiypZl9qP+jMJUiUZgCvZR37Crdj8JU+j0KU5l3FKYigxFllxRNtjSzD/V/FKZSJApToJfyjl2l+1GYSr9HYSrzjsJUZDCi7JKiyZZm9qH+j8JUikRhCvRS3rGrdD8KU+n3KExl3lGYigxGlF1SNNnSzD7U/1GYSpEoTIFeyjt2le5HYSr9HoWpzDsKU5HBiLJLiiZbmtmH+j8KUykShSnQS3nHrtL9KEyl36MwlXlHYSoyGFF2SdFkSzP7UP9HYSpFojAFeinv2FW6H4Wp9HsUpjLvKExFBiPKLimabGlmH+r/KEylSBSmQC/lHbtK96MwlX6PwlTmHYWpyGBE2SVFky3N7EP9H4WpFInCFOilvGNX6X4UptLvUZjKvKMwFRmMKLukaLKlmX2o/6MwlSJRmAK9lHfsKt2PwlT6PQpTmXcUpiKDEWWXFE22NLMP9X8UplIkClOgl/KOXaX7UZhKv0dhKvOOwlRkMKLskqLJlmb2of6PwlSKRGEK9FLesat0PwpT6fcoTGXeUZiKDEaUXVI02dLMPtT/UZhKkShMgV7KO3aV7kdhKv0ehanMOwpTkcGIskuKJlua2Yf6PwpTKRKFKdBLeceu0v0oTKXfozCVeUdhKjIYUXZJ0WRLM/tQ/0dhKkWiMAV6Ke/YVbofhan0exSmMu8oTEUGI8ouKZpsaWYf6v8oTKVIFKZAL+Udu0r3ozCVfo/CVOYdhanIYETZJUWTLc3sQ/0fhakUicIU6KW8Y1fpfhSm0u+5ogvTT//9d/H/Lv5fuUT5199XD4Cz/vjHP1ZKUxHpj/zhD3+o/G7//ve/z10ukk26NCv/2z7U/ym/t2XZ914kL7X9BaAX8o5dpfv59z/8W7LFm83MzOR+9otcaSnvy5ebjgtTAODyky7NGCzeewAA6A3fsAHgCqY0G1zeewAA6A3fsAHgCqY0G1zeewAA6A3fsAHgCqY0G1zeewAA6A3fsAHgCqY0G1zeewAA6A3fsAHgCqY0G1zeewAA6A3fsAHgCqY0G1zeewAA6A3fsAHgCqY0G1zeewAA6A3fsAHgCqY0G1zeewAA6A3fsAHgCpYuzWRwAwAAdI9v2ABwBcsrz2TwAgAAdI9v2ABwBcsrz2TwAgAAdI9v2AAAAAAACYUpAAAAAEBCYQoAAAAAkFCYAgAAAAAkFKYAAAAAAAmFKQAAAABAQmEKAAAAAJBQmAIAAAAAJBSmAAAAAAAJhSkAAAAAQEJhCgBcMucP3xBLlyyJJaUML98Q35tKFgAAAFwiClMA4JI5s7daltay90yyAAAA4BJRmAIAl4zCFAAAuNwoTAGAS0ZhCgAAXG4UpgDAJaMwBQAALjcKUwDgklGYAgAAlxuFKQBwyShMAQCAy43CFABIXIzfvj0RD21ZG6uXDycl5nAsX702tjw0Hmc/uJisl3Hxgzg7/lBsWbs6lg83ys+l11wXt2x/PI79/LelR843Z2H64YuxI/06drwYHyaLGj6Jk/cvj+Hk/sPLd8SLmZXOf2t1snw4Vn/rfOW2ix+cjfE9t8Q1S5PnXnpNrN3ySJxI/YwzH/0yjj2yJW6svYbh5XFjZp20uZ6nvj3bPAYAAHDpKUwBgIiZ6Zi8a2W11GuV4b1xZiZZv2ImPnr9kfhsrXScI0tvHY+pnI5wzsL0/fG4KbVsyU3j8X6yqOH9GL8ptc6Sm2I8s1LTc+w9EVMTd8XK+vqZDK+Oh177OH59fHesTpW/2XX2n/k4efSGQs+zZGXpZ539GAAAwKWnMAWAgfdxHN9WG8k5V5rLyI/P7J2jEJyd4Q1HZxWei16YDg/XR6O2zNKlsTTv9nRWjsY7TeXxPJ5n+d4480lyZwAA4LKhMAWAAffJmb2xPF3kDW+IR9/+dXxaKQQvxu/+5edx7KH/GMuX7o/XKvcomXknRlem7lM+DX33sfjn3yXDSC/+Nt4ez46wHI57f9LcEC56YZpk6a1/F2//tvxaL8YHx+7NLX6HV++OY7/6NGbKlyo4eyD+rGn58hh9p/r4NXnPM3zj/uT0+5n46N1HY0Nm1Oq24xpTAAC43ChMAWCgfRiTt6dLvOHYdrz9qeKf/OTephGUw7dPxm+SZQ0z8YtH/yz12KVsOx7pivBSFKbDG8Zjuml06G9iYlPzOktW7o3mM+ZnSo/TPAp3w9F/SZZVtX+eKG2P65rWWfvEdLIEAAC4XChMAWCgnYm9qQJvyZKvxKlMyZfntf3N5WHLkZLZ0nP5aKQHZl6KwrTpORLZIvMrORvh/fGbmta5KfNEnTxPaaWmdZbkrgQAAFxKClMAGGQdlZJZ7UvKhmwhu7d0S8PlUphmy9BO1lGYAgBAf1KYAsAgU5hWKEwBAIAahSkADDKFaYXCFAAAqFGYAsAg+3Aybk8XeB1dw/STOL4tfZ/8a35WZEvPtU9EepojhanCFAAALjcKUwAYaL+IR69LFXgtZsmf+ehU7F15e0x+WP13tjwc3nY8cu41a5b86x79RbKsau6SMTs6dVs0zy01Ex+d2hsrm9ZRmAIAAAujMAWAATf1d82l5pLhDfHo27+OT8uDRmc+jV+deCg+u7S8LFVG/mYiNqXvs2Q4btx/Iv75dxcri2c+/XW8PX7XAsvM7OjRJbHy3mPxq/ILm/ko3p31+OUoTAEAgIVRmALAoPvktdi/MlXitUxjhGne6NG5MxwbxqdL92rWrmTMlpS5GR6O4fq/FaYAAMDCKEwBgJiZnoy75ixNV8Zdk9nC8+N465HPxtLc9VMZXh1bJ6aiOva0WduScWY6xjcMN62TzvCNo/H6u0+krnWqMAUAABZGYQoAVF38IM6OPxRb1l5TL0GHl6+OW/aMx9kP8urOqosfnI3xh7bE2tXLUyM9l8Y1190S2x8/Fr/8qMWEUCXnD9/QKFyX3hCHzycL0sqn30/siVuuWdp47LVb4pETv6peNuDDF2Nr5ZIB5cfYGi/WR8FWdfIcH764tbHO8PL4xpvJgpRPTt4fy4cb6+zIPFFHP8v5w3FD7bWWfo4bclcCAAAuJYUpAAAAAEBCYQoAAAAAkFCYAgAAAAAkFKYAAAAAAAmFKQAAAABAQmEKAAAAAJBQmAIAAAAAJBSmAAAAAAAJhSkAAAAAQEJhCgAAAACQUJgCAAAAACQUpgAAAAAACYUpAAAAAEBCYQoAAAAAkFCYAgAAAAAkFKYAAAAAAAmFKQAAAABAQmEKAAAAAJBQmAIAAAAAJBSmAAAAAAAJhSkAAAAAQEJhCgAAAACQUJgCAAAAACQUpgAAAAAACYUpAAAAAEBCYQoAAAAAkFCYAgAAAAAkFKYAAAAAAAmFKQAAAABAQmEKAAAAAJBQmAIAAAAAJBSmAAAAAAAJhSkAAAAAQEJhCgAAAACQUJgCAAAAACQUpgAAAAAACYUpAAAAAEBCYQoAAAAAkFCYAgAAAAAkFKYAAAAAAAmFKQAAAABAQmEKAAAAAJBQmAIAAAAAJBSmAAAAAAAJhSkAAAAAQEJhCgAAAACQUJgCAAAAACQUpgAAAAAACYUpAAAAAEBCYQoAAAAAkFCYAgAAAAAkFKYAAAAAAAmFKQAAAABARcT/Byj7mFmWEHYjAAAAAElFTkSuQmCC"
    }
   },
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "\n",
    "The basis of any statistical analysis is the underlying data, and very often data are stored in **tabular format**:\n",
    " * Each **line** corresponds to an observation (individual, sample, ... ).\n",
    " * Each **column** correspond to a measured variable (height, sex, gene expression, ... ).\n",
    "\n",
    "In python, the most popular module to read and manipulate tabulated data is certainly **[pandas](https://pandas.pydata.org)**, a \"high-level\" module designed for data manipulation and exploratory analysis. A great strength of pandas is its **DataFrame** object which emulates many of the convenient behaviors and syntax of its eponym counterpart in the **R** language.\n",
    "\n",
    "![pandas_dataframe_and_series.png](attachment:pandas_dataframe_and_series.png)\n",
    "\n",
    "<br>\n",
    "\n",
    "To graphically represent data, we will rely on the **[seaborn](https://seaborn.pydata.org)** library.\n",
    "Seaborn is designed to work hand-in-hand with pandas DataFrame to produce **efficient data representation** from fairly simple commands. The seaborn official website proposes [very good tutorials](https://seaborn.pydata.org/tutorial.html) as well as a [gallery](https://seaborn.pydata.org/examples/index.html) with associated code to get you started quickly.\n",
    "\n",
    "<br>\n",
    "\n",
    "### Loading the pandas and seaborn modules\n",
    "\n",
    "By convention, pandas is imported as **`pd`** and seaborn as **`sns`**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import seaborn as sns\n",
    "\n",
    "print(\"All modules loaded successfully!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> *Note:* if you are missing some of the above modules, you should install them.\n",
    ">\n",
    ">    * Installation with **conda**: `conda install -c conda-forge pandas matplotlib seaborn numpy`\n",
    ">    * Installation with **pip**: `pip install --user pandas matplotlib seaborn numpy` \n",
    "\n",
    "<br>\n",
    "\n",
    "Making the plotted labels a bit bigger for presentation with a projector... you do **not need to run this cell**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib as mpl\n",
    "\n",
    "font = {\"family\": \"DejaVu Sans\",\n",
    "        \"weight\": \"bold\",\n",
    "        \"size\"  : 16}\n",
    "\n",
    "mpl.rc(\"font\", **font)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "### Alternatives to Pandas\n",
    "\n",
    "To this day, the **Pandas** library is certainly the the most popular and most used library for manipulation of tabular data in Python, which is why we present it in this course.\n",
    "\n",
    "However, there exists alternative, and in particular the [polars](https://pola.rs) library, which has been developed relatively recently and can be a good alternative when processing extremely large datasets.\n",
    "\n",
    "Here are some links comparisons between the pandas and the polars library:\n",
    "\n",
    "* Performance comparison:\n",
    "    * https://www.datacamp.com/tutorial/high-performance-data-manipulation-in-python-pandas2-vs-polars \n",
    "    * https://medium.com/cuenex/pandas-2-0-vs-polars-the-ultimate-battle-a378eb75d6d1 \n",
    "* Usability comparison\n",
    "    * https://www.confessionsofadataguy.com/replacing-pandas-with-polars-a-practical-guide \n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "# 1. Reading tabulated data <a id='1' />\n",
    "----------------------------------------\n",
    "\n",
    "In most cases, the data we want to work with is stored in a file on disk. The very first step is therefore to **load the data as a DataFrame**.\n",
    "\n",
    "## 1.1 Reading data from a file <a id='11' />\n",
    "\n",
    "* **`pd.read_table(<file path and name>)`** is the generalist pandas function to **read tabulated data files**. It's only required argument is the name (and optionally path) of the file to read from.\n",
    "\n",
    "> By default, python is searching for files in your current working directory. If the file you wish to load\n",
    "  is not located there, you need to specify its path, either absolute or relative to the working directory.\n",
    "  \n",
    "<br>\n",
    "\n",
    "**Let's now try to load the file `data/titanic.csv`**. As its name suggest, this file contains the popular dataset of the ill-fated [Titanic](https://en.wikipedia.org/wiki/Titanic) passengers, traveling from England to New York in April 1912.  \n",
    "* The file `titanic.csv` is located in a `data/` subdirectory of our current working directory. We must\n",
    "  therefore pass `data/titanic.csv` as argument to `pd.read_table()`.\n",
    "* The data file is named `titanic.csv` and, as its extension suggests, contains **C**omma-**S**eparated **V**alues.\n",
    "\n",
    "> *Note:* the dataset we are using here is *not* the complete list of people that were on the Titanic.\n",
    "> There were around 2240 people on board - precise numbers are disputed due to duplicate entries, people\n",
    "> traveling under pseudonyms, last minute cancellations and last minute replacements of people."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Import the pandas module, if not done yet.\n",
    "import pandas as pd\n",
    "\n",
    "df = pd.read_table(\"data/titanic.csv\")\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There seems to be a problem loading the data... there is a single column in our `DataFrame`, but we expected to have 8 columns!  \n",
    "Let's try to solve this in the first Micro-Exercise of this notebook, just below.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Tip:** it is often practical to **display only a small part of a DataFrame**. This can be done with the **`.head()`** and **`.tail()`** methods of `DataFrame`.\n",
    "\n",
    "* By default, `head()`/`tail()` returns the first/last 5 rows of a DataFrame.\n",
    "* To return a different number of rows, a value can be passed: e.g. `head(10)` returns the first 10 rows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.head()  # By default, head() returns the first 5 rows of a DataFrame."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-success\">\n",
    "\n",
    "### Micro-Exercise 1\n",
    "* Try to fix the cell just above (the loading of `data/titanic.csv`) by looking at the arguments of\n",
    "  the **`pd.read_table()`** function.\n",
    "  For this, you can use `help(pd.read_table)`, or the\n",
    "  [online help](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_table.html).\n",
    "* **If you have time:** try to find a pandas function that will read CSV files by default, i.e.\n",
    "  without having to pass any additional option.  \n",
    "  **Hint:** have a look at the pandas\n",
    "  [input/output functions](https://pandas.pydata.org/pandas-docs/stable/reference/io.html).\n",
    "    \n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "<center><b>Spoiler alert</b>: do not scroll or be spoiled!</center>\n",
    "\n",
    "-----\n",
    "\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you have just seen, **`pd.read_table()`** expects (by default) the input data to be **tab-delimited**.\n",
    "This is not the case of the `titanic.csv` file - which instead contains **comma-delimited** values (`.csv` stands for \"**C**omma-**S**eparated **V**alues\") - and therefore each line of the file was treated as a single field (column), creating a DataFrame with a single column.\n",
    "\n",
    "To load a CSV file, we can either:\n",
    "* Specify the separator value via the **`sep`** argument.\n",
    "* Use **`pd.read_csv()`**, a dedicated function to load CSV files that uses commas as default separator.\n",
    "\n",
    "```py\n",
    "df = pd.read_table(\"data/titanic.csv\", sep=\",\")  # Option 1: specify separator via the `sep` argument.\n",
    "df = pd.read_csv(\"data/titanic.csv\", sep=\",\")    # Option 2: use the `read_csv()` function.\n",
    "df.head()\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    \n",
    "### Additional material: header or not header, that is the question <a id='12' />\n",
    "\n",
    "Another important aspect of reading data is whether your dataset has a header or not.   \n",
    "By default, **`pd.read_table()` treats the first line of a file as its header**, unless you either:\n",
    " * Use the argument **`header=None`**.\n",
    " * Specify column names using the **`names`** argument. The length of the sequence passed to `names`\n",
    "   must match the number of columns in the file.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples:**\n",
    "\n",
    "* If a dataset has ne header, we pass `header=None` as argument to avoid that the first\n",
    "  row of data gets used as header.\n",
    "    ```py\n",
    "    df = pd.read_table(\"data/titanic_no_header.csv\", sep=\",\", header=None) \n",
    "    ```\n",
    "\n",
    "<br>\n",
    "\n",
    "* We can assign our own column names using the `names` argument of `pd.read_table()`.\n",
    "    ```py\n",
    "    df = pd.read_table(\n",
    "    \"data/titanic_no_header.csv\",\n",
    "    sep=\",\", \n",
    "    names=[\"name\", \"column2\", \"age\", \"column4\", \"blip\", \"bloop\", \"spam\", \"eggs\"]\n",
    ")\n",
    "    ```\n",
    " \n",
    "> *Note:* it is important that the length of the sequence passed to `names` matches the number of columns in the file, otherwise pandas will consider columns on the left as being part of the index (i.e. row names).\n",
    "    \n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## 1.2 Setting row names (the index) when loading a file <a id='12' />\n",
    "\n",
    "> **Vocabulary reminder:** in pandas, the row names of a `DataFrame` are called the **index**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Case 1: input file contains no row names\n",
    "\n",
    "* When a dataset does not contain any row names, pandas uses **default index** values:\n",
    "  **integer numbers starting from 0**, corresponding to row positions (first row is `0`, 2nd row is `1`, ...).\n",
    "* Not all dataset need a custom index. Oftentimes the default index is enough. In fact, unless there is\n",
    "  a good reason to give specific row names, it can often be advantageous to have the index correspond to\n",
    "  row positions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "### Case 2: input file contains row names (file has one less column names than data fields)\n",
    "\n",
    "* Depending on how a data file was produced, it may already contain row names.\n",
    "* If the **first row of a file contains one less field than the remaining rows**, pandas auto-detects\n",
    "  the file as containing row names and uses them as index.\n",
    "\n",
    "Let's see an example of this with the `data/titanic_implicit_index.csv` file.  \n",
    "Here is the \"raw\" content of our file (i.e. we simply read the content of the file, without importing it as a DataFrame):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with open(\"data/titanic_implicit_index.csv\", mode=\"r\") as f:\n",
    "    for x in range(5):\n",
    "        print(f.readline().strip())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As can be seen above, the 1st line of the file contains 7 elements, while all other lines contain 8 elements! This is because, in this file, the first field corresponds to row names rather than to an actual column. Since row names have no column name, **the first line of the file has one less field than the remaining lines**.\n",
    "\n",
    "> **Tip:** if you are using a Linux or MacOS machine, you could also use the following one-liner shell command\n",
    "> to display the first 5 lines of a plain text file:\n",
    ">\n",
    "> `!head -n 5 data/titanic_implicit_index.csv`\n",
    ">\n",
    "> The leading **`!`** is a special Jupyter Notebook syntax that indicates a call to a shell\n",
    "> program (here `head`). This allows you to run shell commands from a Jupyter Notebook.\n",
    "\n",
    "<br>\n",
    "\n",
    "Let's see how pandas handles this data file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_csv(\"data/titanic_implicit_index.csv\") \n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Let's have a look at the index (row names) values...\n",
    "# Note: with [:5], we only select the first 5 elements (values 0 to 4).\n",
    "df.index[:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "When pandas detects that a file has one less value in the first line than in the remaining lines, it **automatically uses the first, nameless, column as index**.\n",
    "\n",
    "<br>\n",
    "\n",
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    \n",
    "### Additional material: using `index_col` to manually specify a column to use as index\n",
    "\n",
    "Pandas can be instructed to use a specific column of an input file as index via the **`index_col`** argument of `pd.read_table()`.  \n",
    "The index column can be indicated either:\n",
    "* By position (*reminder:* column indexing is zero-based - the index of the first column is 0, not 1).\n",
    "* By name.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples:** use the first column (`index_col=0`) as index (row names).\n",
    "    \n",
    "```py\n",
    "df = pd.read_table(\"data/pbmc_data.countMatrix.50.txt.zip\", sep=\" \", index_col=0)\n",
    "df.head()\n",
    "```\n",
    "\n",
    "> *Notes:*\n",
    ">  * As can be seen in the example above, Pandas can **read data in compressed files such as `.zip` files**.\n",
    ">  * Removing the name of the index (`Name` in the example above) can be done\n",
    ">    with: **`df.index.name = None`**\n",
    ">  * Pandas also has a system of multiple, hierarchized indexing. This is, however,\n",
    ">    a more specialized and advanced feature. You can read more about it\n",
    ">    [here in the pandas doc](https://pandas.pydata.org/pandas-docs/stable/user_guide/advanced.html#multiindex-advanced-indexing).\n",
    "    \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## 1.3 Summary of `pd.read_table()` arguments <a id='13' />\n",
    "\n",
    "We have seen above a few of the most useful of the **optional** arguments of **`pd.read_table()`**:\n",
    "\n",
    "* **`sep`**: the separator between columns/fields in the file. The default value for this argument\n",
    "  is `\"\\t\"`, a tab.\n",
    "* **`header`**: the **row number to use as the column names** (all rows above it are skipped).\n",
    "  By default the first line of the file is used as header.\n",
    "  Use **`header=None` if the file does not contain column names**.\n",
    "* **`names`**: sequence of strings to use as **column names**. The length of the sequence should match the\n",
    "  of columns in the file.\n",
    "* **`index_col`**: column number or name to use as index (**row names**) of the DataFrame.\n",
    "\n",
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "### Additional material: more optional arguments of `pd.read_table()`\n",
    "\n",
    "`pd.read_table()` has many more optional arguments. Here is a small selection which may be of interest to you:\n",
    "\n",
    "* **`skiprows`**: allows to skip the specified rows (lines of the file) during import. This can be either\n",
    "  a sequence of lines to skip (0-indexed), or an integer number indicating how many lines to skip\n",
    "  at the start of the file.\n",
    "* **`na_values`**: takes a list. Allows you to define your own NA values. Ideal when your NAs are\n",
    "  encoded as something unusual (eg, `.`,` `,`-9999`,...).\n",
    "* **`true_values`**/**`false_values`**, each a list indicating which values should be converted to\n",
    "  `true` or `false`. E.g. you might have columns encoded with \"yes\"/\"no\" labels that you want to\n",
    "  change into `true`/`false`.\n",
    "* **`compression`**: your data is in a compressed format (zip, gzip, ...)? Not a problem!  \n",
    "  Note that common compression formats (such as `zip`, `gzip`) are automatically detected by pandas\n",
    "  and there is no need to add this option.\n",
    "* `parse_dates`/`infer_datetime_format`/`date_parser`: options to help you handle date parsing, which can\n",
    "  otherwise be a nightmare - [more on this here](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html).\n",
    "\n",
    "> You can learn (much) more using `help(pd.read_table)` or the\n",
    "  [online help](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_table.html).\n",
    "\n",
    "<br>\n",
    "\n",
    "**Example:** loading a dataset that contains (badly) \"encoded\" `True` or `False` values.\n",
    "* If we pass no option to `.read_table()`, the values in the dataset are interpreted as strings.\n",
    "    \n",
    "    ```py\n",
    "    pd.read_table(\"data/ugly_dataset.tar.gz\")\n",
    "    ```\n",
    "\n",
    "* By telling pandas which values are NA (`na_values`), `True` (`true_values`) or `False` (`false_values`),\n",
    "  the dataset can be loaded correctly.\n",
    "    \n",
    "    ```py\n",
    "    pd.read_table(\n",
    "    \"data/ugly_dataset.tar.gz\",\n",
    "    na_values=[\"NA\", \"missing\", \"not_available\"],\n",
    "    true_values=[\"true\", \"1\", \"2\"],\n",
    "    false_values=[\"false\", \"0\"]\n",
    "    )\n",
    "    ```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## 1.4 Reading other tabulated file formats <a id='14' />\n",
    "\n",
    "As you might expect, pandas is not limited to text, or csv/tsv-like files. It can read/write from/to many other file formats:\n",
    "\n",
    "* **`pd.read_excel()`**\n",
    "* **`pd.read_json()`**\n",
    "* **`pd.read_sql()`**\n",
    "* ... see [here for an exhaustive list of pandas reader and writer functions](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html).\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "# 2. Data manipulation: selecting rows and columns <a id='2' />\n",
    "---------------------------------\n",
    "\n",
    "Now that we know how to load files as a `DataFrame`, let's see what we can actually do with these!  \n",
    "Gathering basic information about a `DataFrame` is fairly easy, and we will illustrate this with the titanic data:\n",
    "\n",
    "<br>\n",
    "\n",
    "## 2.1 Accessing and setting row and column names <a id='21' />\n",
    "\n",
    "Accessing and setting column and row names of a `DataFrame` can be done with:\n",
    "* **`df.columns`**, for columns.\n",
    "* **`df.index`**, for rows.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Example:**\n",
    "\n",
    "* In the example below, the input file `data/titanic.csv` contains no row names, and therefore pandas used\n",
    "  default index values: numeric values starting with `0`(corresponds to row indices)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Loading the titanic dataset as a DataFrame.\n",
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* Let's look at the values of **`.columns`** and **`.index`**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Column names.\n",
    "df.columns"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Index values (i.e. row names).\n",
    "df.index"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "The `Index` and `RangeIndex` objects behave like other python sequences (e.g. `list` or `tuple`):\n",
    "* Their **indexing is zero-based**, i.e. the first element has index `0`.\n",
    "* **Slicing** is possible - we can access individual values or a range of values.\n",
    "* They are **iterable**: we can convert them to `list`/`tuple` or use them in a `for` loop."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the name of a specific column - here the 3rd column (index = 2).\n",
    "df.columns[2]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Convert the index values to a list object and print some of them.\n",
    "list(df.index[:10])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "The **`.columns`** and **`.index`** attributes can also be used to **set new values** for column names and index values (row names)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Change the column names to upper case.\n",
    "df.columns = [x.upper() for x in df.columns]\n",
    "\n",
    "# Change the row names.\n",
    "df.index = [f\"passenger_{i}\" for i in df.index]\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> *Note:* the **`Index` and `RangeIndex` objects are immutable**.  \n",
    "> It is therefore **not possible to modify the value of individual columns and rows**.\n",
    "> \n",
    ">   ```py\n",
    ">   df.columns[0] = \"NAME\"       # -> TypeError: Index does not support mutable operations\n",
    ">   df.index[3] = \"passenger_3\"  # -> TypeError: Index does not support mutable operations\n",
    ">   ```\n",
    ">   \n",
    ">   However, it is possible to change individual values with via the `.rename()` method:\n",
    ">   ```py\n",
    ">   df.rename(columns={\"Name\":\"NAME\", \"Age\":\"AGE\"}, inplace=True)\n",
    ">   df.rename(index={3:\"passenger_3\"}, inplace=True)\n",
    ">   ```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "    \n",
    "### Additional material: f-strings\n",
    "\n",
    "In the cell above, we used an **f-string** (formatted string literal) to create a string that includes\n",
    "a variable value.\n",
    "    \n",
    "* **f-strings** allow to include the value of a variable/expressions inside a literal string\n",
    "  by prefixing the string with `f` (or `F`) and writing the expressions inside `{}` as in `{expression}`.\n",
    "* **Example:**\n",
    "    ```py\n",
    "    var_1 = 2\n",
    "    var_2 = 5\n",
    "    print(f\"The sum of {var_1} + {var_2} is {var_1 + var_2}\") # -> The sum of 2 + 5 is 7\n",
    "\n",
    "    # With string concatenation, this would be written like:\n",
    "    print(\"The sum of \" + str(var_1) + \" + \" + str(var_2) + \" is \" + str(var_1 + var_2))\n",
    "    ```\n",
    "   \n",
    "  <br>\n",
    "    \n",
    "* f-strings do some basic formatting by default (e.g. converting a number to a `str`), but\n",
    "  **further formatting can be applied to them**. For instance, `floats` can be rounded with\n",
    "  `{var:.Xf}`, where `var` is the variable to round, and `X` the number of decimal places.\n",
    "    ```py\n",
    "    pi = 3.14159265358979323846\n",
    "    print(f\"Pi is approximately {pi:.3f}\")          # -> Pi is approximately 3.142.\n",
    "    print(f\"Pi with a single decimal is {pi:.1f}\")  # -> Pi is approximately 3.1.\n",
    "    ```\n",
    "\n",
    "<br>\n",
    "You can find more information about f-strings in the [python documentation](https://docs.python.org/3/tutorial/inputoutput.html#formatted-string-literals).\n",
    "    \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "Let's reset the changes we just made to the index and column names of our DataFrame.\n",
    "\n",
    "> *Notes:*\n",
    "> * The expression `df.columns.str.capitalize()` allows to apply the method `.capitalize()` of `str`\n",
    ">   to all column names at once. This is a powerful feature of DataFrame, which we'll discuss later.\n",
    ">\n",
    "> * To reset the index, we are using **`.reset_index(drop=True, inplace=True)`**.\n",
    ">   This resets the index to the pandas default index (row positions). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.columns = df.columns.str.capitalize()\n",
    "df.reset_index(drop=True, inplace=True)\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "If we only need the **number of rows/columns** (without their names), we can use:\n",
    "* **`df.shape`** returns a tuple with the numbers of rows and columns: `(row_count, col_count)`.\n",
    "* Alternatively, we can also query the length of the index or columns:\n",
    "  **`len(df.index)`** / **`len(df.columns)`**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"row count:\", df.shape[0])\n",
    "print(\"column count:\", df.shape[1])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Alternative approach to get row and column counts by using tuple unpacking.\n",
    "row_count, col_count = df.shape\n",
    "\n",
    "print(\"row count:\", row_count)\n",
    "print(\"column count:\", col_count)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "    \n",
    "### Additional material: values unpacking\n",
    "\n",
    "Value unpacking is frequently used in python to assign values to multiple variables in a single statement:\n",
    "* Any object that is an iterable (sequence) can be unpacked.\n",
    "* The number of variable to which values are assigned must match the length of the iterable.\n",
    "* To unpack multiple values into a single variable (as a list), the `*var` syntax is used (see example below).\n",
    "\n",
    "  **Examples:**\n",
    "    ```py\n",
    "    a, b, c = (1, 2, 3)               # Unpacking of a tuple\n",
    "    print(f\"a: {a}, b: {b}, c: {c}\")\n",
    "\n",
    "    a, b, c = range(3)                # Unpacking works with any iterable - here a \"range\" object.\n",
    "    print(f\"a: {a}, b: {b}, c: {c}\")\n",
    "    ```\n",
    "\n",
    "    ```py\n",
    "    #a, b = [1, 2, 3, 4, 5]           # Raises a ValueError: the number of items to unpack\n",
    "                                      # does not match the number of variables being assigned.\n",
    "\n",
    "    a, *b = [1, 2, 3, 4, 5]           # *b collects all remaining values into a list.\n",
    "    print(f\"a: {a}, b: {b}\")\n",
    "    ```\n",
    "\n",
    "<br>\n",
    "\n",
    "* When calling functions, values can be unpacked into arguments or key-word arguments for\n",
    "  the function by using the syntax `function(*arg)` and `function(**kwargs)`.\n",
    "\n",
    "  **Examples:**\n",
    "    ```py\n",
    "    arg_values = [11, 20, 3]\n",
    "    for x in range(*args):\n",
    "        print(x)\n",
    "\n",
    "    kwarg_values = {\"sep\": \"--\", \"end\": \"...\"}\n",
    "    print(*arg_values, **kwarg_values)           # Prints \"11--20--3...\"\n",
    "    ```\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## 2.2 Accessing single/multiples columns by name <a id='22' />\n",
    "\n",
    "Columns of a DataFrame can be accessed with the syntax:\n",
    "* **`df[\"column name\"]`** - to select a single column.\n",
    "* **`df.colum_name`** - to select a single column (does not work if column name contains a space).\n",
    "* **`df[[<column name>, <column name>, ... ]]`** - to select multiple columns.\n",
    "  Column names **must be passed as a `list`**.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples:**\n",
    "\n",
    "**Selecting a single column**. This returns a pandas **Series**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# (Re)Load the titanic dataset as a DataFrame and display it for reference.\n",
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df[\"Age\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "Alternatively, we can also use the syntax **`df.<column name>`**\n",
    "> *Note:* this only works if the column names does *not* contain any space."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df.Age"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Selecting multiple columns**. This returns a \"subset/slice\" of the DataFrame object.\n",
    "\n",
    "> **Important:** column names must be passed as a **list** object. Using other iterables will not work.\n",
    "> E.g. passing a tuple will raise an error.\n",
    ">  ```py\n",
    ">  df[(\"Age\", \"Sex\")].head()  # -> Raises an error!\n",
    ">  ```\n",
    ">\n",
    "> **Warning:** depending on the situation, subsetting a data frame can return a copy of\n",
    "> the DataFrame or the DataFrame itself.  \n",
    "> See the \"Copy or not copy\" section below for details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df[[\"Age\", \"Sex\"]].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "The colum selection syntax also allows to **add new columns** or **edit** them:\n",
    "* If the referenced column does not exist, it is created.\n",
    "* If the referenced column exists, it's values are overwritten."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.head(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "# The \"Citizenship\" column does not exist yet in the DataFrame: it gets created.\n",
    "df[\"Citizenship\"] = \"UK\"\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# The \"Citizenship\" column already exist: its values are overwritten.\n",
    "df[\"Citizenship\"] = \"USA\"\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Warning:** the number of values passed to a column must either:\n",
    "* Be a single value - in case the same value is given to all rows in the DataFrame.\n",
    "* A sequence of values (e.g. `list`, `tuple`) whose length matches the number of rows of the DataFrame.\n",
    "\n",
    "Otherwise a `ValueError` is raised."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The number of elements to assign to the column matches the number of rows.\n",
    "df[\"Citizenship\"] = [\"UK\", \"USA\", \"FR\"] * 297\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df[\"Citizenship\"] = [\"USA\", \"USA\", \"USA\"]  # Raises a ValueError."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## 2.3 Deleting columns and rows <a id='23' />\n",
    "\n",
    "**`df.drop()`** is used to delete columns or rows of a DataFrame.\n",
    "\n",
    "* `df.drop(columns=...)` to delete columns.\n",
    "* `df.drop(index=...)` to delete rows.\n",
    "* Alternatively, specify the column/row names to delete and use the **`axis`** argument:\n",
    "    * `axis=0` to **delete rows** - this is the default.\n",
    "    * `axis=1` to **delete columns**.\n",
    "\n",
    "<br>\n",
    "\n",
    "The optional **`inplace`** argument specifies whether the original DataFrame should be modified or not:\n",
    "* To return a copy of the DataFrame (with the columns dropped), pass **`inplace=False`**. This is the default.\n",
    "* To delete the column(s) in the original DataFrame, pass the option **`inplace=True`**.\n",
    "  \n",
    "<br>\n",
    "\n",
    "**Examples:**\n",
    "\n",
    "* **Delete a column** and **return a copy** of the DataFrame:\n",
    "  * With `inplace=False`, the original DataFrame (here `df`) is left unchanged.\n",
    "  * Note that `inplace=False` is the default value of the `inplace` argument, so it could also be omitted.\n",
    "  * An alternative way of doing `df.drop(columns=\"Citizenship\")` is: `df.drop(\"Citizenship\", axis=1)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a copy of the original DataFrame without the \"Citizenship\" column.\n",
    "df2 = df.drop(columns=\"Citizenship\", inplace=False)\n",
    "df2.head(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# The original DataFrame still has the column, because we used \"inplace=False\".\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* **Delete a column** from the original DataFrame (`inplace=True`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df.drop(columns=\"Citizenship\", inplace=True)\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* **Delete rows**.\n",
    "  > *Note:* since deleting rows is the default `axis` value, we can also do:\n",
    "    `df.drop([3,4,5], inplace=True)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df.drop(index=[3,4,5], inplace=True)\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> **Re-assigning index values**  \n",
    "> When deleting rows from a DataFrame that uses the default index values\n",
    "> (i.e. numbers starting from 0), the index gets out-of-sync with row positions.\n",
    "> This can be corrected by re-assigning values to the index:\n",
    "> * `df.reset_index(drop=True, inplace=True)`  \n",
    "> or\n",
    "> * `df.index = range(df.shape[0])`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.index = range(df.shape[0])\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "### [Additional Material] Deleting columns using `del` and `pop()`\n",
    "\n",
    "Columns of a DataFrame can also be deleted using the same methods as when deleting entries in a Python `dict`:\n",
    "\n",
    "* `del df[\"column name\"]`: deletes a column from the DataFrame.\n",
    "* `df.pop(\"col name\")`: deletes column and returns it as a panda Series.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## 2.4 Data types <a id='24' />\n",
    "\n",
    "Each column of a DataFrame has an associated **data type**, which controls the operations you may perform on it.\n",
    "\n",
    "The main types are:\n",
    "    \n",
    "* **`int64`**: integers.\n",
    "* **`float64`**: floats.\n",
    "* **`bool`**: booleans.\n",
    "* **`datetime64`**: date and time points.\n",
    "* **`category`**: categorical data with fixed possible values.\n",
    "* **`object`**: catch-all type (includes **strings**).\n",
    "\n",
    "> *Note:* [datetime64](https://pandas.pydata.org/docs/user_guide/timeseries.html) and [category](https://towardsdatascience.com/staying-sane-while-adopting-pandas-categorical-datatypes-78dbd19dcd8a) are fairly specific types, and we refer you to the provided links if you want to learn more about them.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# (Re)Load the titanic dataset as a DataFrame.\n",
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "\n",
    "# List the type of each column in the DataFrame.\n",
    "print(\"columns types:\\n\", df.dtypes, sep=\"\")\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "### Additional Material: `int64` vs. `Int64`\n",
    "\n",
    "In the example above, you might have noticed that the `Age` column gets detected as `float64` despite containing only integer numbers (while `Pclass` e.g. is correctly detected as `int64`).\n",
    "    \n",
    "<br>\n",
    "\n",
    "The reason for this is because, by default *pandas DataFrame* uses **`int64`** - the data type for integers\n",
    "provided by the *numpy* library (which is used by *pandas*) - and `int64` does not support **NA** values.  \n",
    "Since the `Age` column contains some missing values, which cannot be represented as `int64`, the column gets\n",
    "converted to a **`float64`** data type, which has support for NA values in the form of `numpy.nan` (`NaN`).\n",
    "\n",
    "<br>\n",
    "\n",
    "*Pandas* also has it's own integer data type, named `Int64` (notice the capital `I`), which has support for\n",
    "pandas own NA values: **`pd.NA`** (displayed as `<NA>`). Loading the `Age` column as in `Int64` is possible, if explicitly indicated:\n",
    "\n",
    "  ```py\n",
    "  pd.read_csv(\"data/titanic.csv\", dtype={\"Age\": \"Int64\"})\n",
    "  ```\n",
    "    \n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**To change the type of a column**, the simplest is to use the **`.astype()`** method.  \n",
    "In the case of the titanic data, we could make the following changes:\n",
    "* `Age` -> integer.\n",
    "* `Pclass` -> category.\n",
    "* `Survived` -> boolean."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.dropna(inplace=True)  # Remove rows with NA, as the regular \"int64\" data type has no support for them.\n",
    "\n",
    "df.Age = df.Age.astype(int)\n",
    "df.Pclass = df.Pclass.astype(\"category\")\n",
    "df.Survived = df.Survived.astype(bool)\n",
    "\n",
    "print(\"columns types:\\n\", df.dtypes, sep=\"\")\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Type-specific methods** can be applied to columns of the given type.  \n",
    "For instance:\n",
    "\n",
    "* **`.str`** to apply **string methods**\n",
    "* **`.cat`** to apply **category methods**.\n",
    "\n",
    "**Example:** convert a string column to lower case."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.Name.str.lower().head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Example:** rename values in column of type category."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df.Pclass.cat.rename_categories({1: \"I\", 2: \"II\", 3: \"III\"}).head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-success\">\n",
    "\n",
    "### Micro-Exercise 2\n",
    "\n",
    "A typical use case: you are given a badly formatted dataset and have to curate it.\n",
    "\n",
    "In this exercise, the badly formatted data comes in the form of a column of data (a pandas `Series`) that contains percentages followed by a `%` sign. To generate this data, copy-paste the following line in a new code cell:\n",
    "\n",
    "```python\n",
    "percent_column = pd.Series(np.random.randint(0,100,100), dtype=\"str\") + '%' \n",
    "```\n",
    "\n",
    "<br>\n",
    "\n",
    "**Your mission** is to get this column into usable numbers by:\n",
    "* Removing the trailing `%`.\n",
    "* Converting the values to integers.\n",
    "* **Hints:**\n",
    "  * Remember that you can use `.str.<method>` to apply a method of string to an entire columns/Series.\n",
    "  * Removing leading and trailing characters of a string can be done with the `.strip` method.\n",
    "\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "# 3. DataFrame subsetting <a id='3'></a>\n",
    "\n",
    "## 3.1 Accessing specific rows and columns <a id='31'></a>\n",
    "\n",
    "A very common operation to perform on *DataFrames* is to **create a subset** by selecting certain rows and/or columns.\n",
    "\n",
    "There are 2 methods in pandas to perform a selection on a DataFrame (here `df`):\n",
    "* **`df.loc[<row index values>, <column names>]`** - to select based on row (index) and column **names**.\n",
    "* **`df.iloc[<row positions>, <column positions>]`** to select based on row and column **positions**.\n",
    "\n",
    "<br>\n",
    "\n",
    "### Subsetting a DataFrame with the `.loc[]` indexer\n",
    "\n",
    "The **`.loc[]` indexer** selects rows and columns based on the **index values of the row** and the **names of the columns**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# (Re)Load the titanic dataset as a DataFrame.\n",
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.loc[2, \"Name\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Multiple rows/columns** can be selected by:\n",
    "* **Passing a sequence** (e.g. `list`, `tuple`) of row/column names: **`.loc[[0, 10], [\"Name\", \"Age\"]]`**.\n",
    "* **Passing a slice** of row/column names: **`.loc[0:10, \"Name\":\"Age\"]`**.\n",
    "  * **`value:`** selects all rows/columns **from `value` till the end**.\n",
    "  * **`:value`** selects all rows/columns **from the start until `value` (included)**.\n",
    "  * **`:`** with no values around **selects all rows/columns**.\n",
    "  \n",
    "    > *Note:* when selecting on rows only (i.e. select all columns), the `df.loc[<row selection>, ]`\n",
    "    > and `df.loc[<row selection>]` syntaxes are also possible. The `:` is not compulsory in that case.\n",
    "\n",
    "<div class=\"alert alert-block alert-danger\">\n",
    "\n",
    "**Important:** when using *slicing*, the **end element of the slice is included** (unlike every other time in python!).\n",
    "\n",
    "</div>\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples:**\n",
    "\n",
    "* **Select the first 3 rows** of the columns `Name`, `Age` and `Pclass`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.loc[0:2, [\"Name\", \"Age\", \"Pclass\"]]\n",
    "df.loc[:2, [\"Name\", \"Age\", \"Pclass\"]]   # Same as above, but omitting the \"0\" since it's the first index."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* **Select a range** of columns using *slicing*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.loc[:2, \"Name\":\"Pclass\"]  # Reminder: with `.loc[]`, the end element of the slice is included."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* I am free to select a column several time, in whichever order I wish. This can thus be used to\n",
    "  **re-order columns** in a DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Selecting all rows, re-arranging columns, and duplicating the \"Age\" column.\n",
    "df.loc[:, [\"Age\", \"Pclass\", \"Name\", \"Age\"]].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Selecting a single row/column** returns a pandas **Series** object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(type(df.loc[2, ]))\n",
    "df.loc[2, ]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> **Pandas Series**  \n",
    "> *Series* are the equivalent of *DataFrame*, but **1-dimensional** (so essentially they\n",
    "> are a **named vector** of values).  \n",
    "> \n",
    "> Their elements can be accessed in quite a similar way:\n",
    ">\n",
    ">    ```py\n",
    ">    row_5 = df.loc[4,:]\n",
    ">    print(row_4[0])      # Access an item of a Series by position.\n",
    ">    print(row_4.Age)     # Access an item of a Series by name.\n",
    ">    ```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "### Pitfalls with `.loc[]`\n",
    "\n",
    "**Because the index values often correspond to row positions** (as in our example DataFrame), it is easy to get the wrong impression that `.loc[]` also selects on row positions... but this is not the case.\n",
    "\n",
    "To illustrate this, let's load a DataFrame with **non-numeric Index values**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Load the titanic data set with the \"Name\" column as index.\n",
    "tmp = pd.read_csv(\"data/titanic.csv\", index_col=\"Name\")\n",
    "tmp.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "Let's now try to **select rows 2-5** of our *DataFrame*:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "tmp.loc[1:4, :]  # Oops... this raises a TypeError."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "With `.loc[]`, **we must pass Index/column names**. Positions are not allowed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "# Select all rows from \"Coleff Mr. Peju\" to \"Dooley Mr. Patrick\" (included):\n",
    "tmp.loc[\"Coleff Mr. Peju\":\"Dooley Mr. Patrick\", :]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> *Note:* you could get around this problem by querying the index at the desired positions:\n",
    ">\n",
    "> ```py\n",
    "> tmp.loc[tmp.index[1]:tmp.index[4], :]\n",
    "> ```\n",
    "> \n",
    "> But at this point it's a lot more convenient to **use the `.iloc[]` indexer**\n",
    "> (see the supplementary material section below for details):\n",
    ">\n",
    "> ```py\n",
    "> tmp.iloc[1:5, :]\n",
    "> ```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "### Supplementary material: the `.iloc[]` indexer\n",
    "\n",
    "The **`.iloc[]` indexer** is very similar to `.loc[]`, except that it selects based on row/column position rather than on index and column names.\n",
    "* As usual in Python, **position indexes are zero based**, meaning that the first row/column has position 0.\n",
    "* Unlike `.loc[]`, with **`.iloc[]`, the end index is excluded**, as usual when doing slicing in Python.\n",
    "\n",
    "  ```py\n",
    "  df.iloc[0:3, :]  # Selects the first 3 rows.\n",
    "  df.loc[0:3, :]   # Selects the first 4 rows.\n",
    "  ```\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples:**\n",
    "\n",
    "```py\n",
    "# Select the first 3 rows (positions 0 to 2).\n",
    "df.iloc[0:3, :]\n",
    "\n",
    "# Select the 6th, 7th and 8th rows (positions 5 to 7) and the last 2 columns.\n",
    "df.iloc[5:8, -2:]\n",
    "```\n",
    "\n",
    "    \n",
    "</div>\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-success\">\n",
    "    \n",
    "### Micro-Exercise 3\n",
    "\n",
    "Load the `data/titanic.csv` dataset with: `df = pd.read_csv(\"data/titanic.csv\")`.\n",
    "\n",
    "Then, using the **`.loc[]`** indexer:\n",
    "* **Select** all odd rows from the Titanic data frame, as well as the columns \"Name\", \"Age\" and \"Fare\".\n",
    "* **Re-order** the columns so that \"Age\" is first and \"Name\" is second.\n",
    "\n",
    "**Hint:** we will soon see how to perform conditional selections, but for now you can use the `range()` function to help you with this task.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Additional task, if you have time:**\n",
    "* Perform the same operation, but using the `.iloc[]` indexer.\n",
    "  See the supplementary material above for how to use `.iloc[]`.\n",
    "\n",
    "\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## 3.2 Conditional selection <a id='32' />\n",
    "\n",
    "Another, powerful, way of selecting rows of a *DataFrame* is by **passing a sequence of boolean values as row selection** to the `.loc[]` indexer. This allows to **filter via conditional selection**.\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    \n",
    "**Important:** Making **conditional selections is only supported by the `.loc[]`** indexer. It does *not* work with `.iloc[]`.\n",
    "\n",
    "> As a workaround for **`.iloc`**, one can call the index of a mask, or use the\n",
    "  [query method](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.query.html).\n",
    "  E.g. `df.query(\"Fare > 300\")`.\n",
    "\n",
    "</div>\n",
    "\n",
    "<br>\n",
    "\n",
    "**Example:** In the Titanic dataset, select all passengers older than 50 years."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "\n",
    "df.loc[df.Age > 50, :]\n",
    "#df.iloc[df.Age > 50, :]  # Raises a NotImplementedError."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Conditional selection** is frequently done by first creating a boolean **mask**, which is then applied to filter the *DataFrame*:\n",
    "* A **mask** is a vector of boolean values (`True`/`False`) that indicate whether\n",
    "  or not a rows satisfies to the defined condition.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Example:** crate a masks that filters for women in the Titanic dataset. Here the mask values are `True` if the corresponding value in the `Sex` column of the *DataFrame* is equal to `female`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "mask = df[\"Sex\"] == \"female\"   # This creates a vector (a pandas Series) of boolean values (True/False).\n",
    "mask.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "Now that the mask is created, we can use it to **filter our `DataFrame`** and keep only those rows corresponding to female passengers.\n",
    "\n",
    "> *Reminder:* `.shape[0]` returns the number of rows of a *DataFrame*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Number of female passengers:\n",
    "df.loc[mask,].shape[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.loc[mask, \"Name\":\"Pclass\"].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "### Combining conditions\n",
    "\n",
    "Selection conditions can be combined to produce more complex selection criteria.  \n",
    "* Conditions are combined using the **`&`** (logical AND) and **`|`** (logical OR) operators.\n",
    "* **Important:** each conditions must be surrounded by brackets: `( condition 1 ) & ( condition 2 )`.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples:**\n",
    "\n",
    "* Select men passengers with a fare > 200."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.loc[(df.Sex == \"male\") & (df.Fare > 200), ].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* Same as above, but in 2 steps: first we create a mask, then we apply it to the *DataFrame*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mask = (df.Sex == \"male\") & (df.Fare > 200) \n",
    "df.loc[mask, ].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* Select all people that are **either < 25 or women**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.loc[(df.Age < 25) | (df.Sex == \"female\"), :]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "### Conditional value assignment\n",
    "\n",
    "**Row value assignment operations can be combined with a selection operation**, allowing e.g. to modify the values of certain rows in a *DataFrame* based on a given condition.\n",
    "\n",
    "Let's imagine that, for some reason, the fares of class 3 passengers are not valid. We want to set them to `NA` values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df_copy = df.copy()  # Create a copy of the DataFrame, to avoid modifying the original one.\n",
    "\n",
    "# NA is represented using pd.NA\n",
    "df_copy.loc[df.Pclass==3, 'Fare'] = pd.NA\n",
    "df_copy.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-success\">\n",
    "\n",
    "### Micro-Exercise 4\n",
    "\n",
    "* From the Titanic dataset, create a mask to select passengers in first class (`Pclass` is `1`)\n",
    "  that are less than 18 years old.\n",
    "* What fraction of these passengers survived?  \n",
    "  **Hint:** apply the `.mean()` method to a column to compute its mean value.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Additional task, if you have time:**\n",
    "* Create a mask to select women and children (< 18 years). How many were onboard the ship?\n",
    "* Compute the median ticket price (`Fare` column) and age for men and women.\n",
    "  Use a `for` loop to avoid code duplication (alternatively, you could look into the `.groupby()` method).\n",
    "\n",
    "<div>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    \n",
    "### Additional material: copy or not copy?\n",
    "\n",
    "What happens if we select a subset of a DataFrame and modify it? Does the original data stay the same?\n",
    "\n",
    "This issue is quite complex, but as you are likely to encounter this warning at some point, we here provide a short primer on it. The following link also provides a more [in-depth explanation of view vs. copy](https://www.dataquest.io/blog/settingwithcopywarning).\n",
    "\n",
    "<div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_table(\"data/titanic.csv\", sep=\",\")\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.loc[df.Sex == \"male\", \"Age\"] = 999\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "    \n",
    "In the above example, pandas changes the values of the `Age` column in the original `DataFrame` object.\n",
    "\n",
    "In general, `pandas` avoids doing copies when it can... but let's try another example:\n",
    "\n",
    "<div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Assign the subset to a new variable.\n",
    "df_male = df.loc[df.Sex == \"male\", :]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Setting the age to 888 in the subset dataframe of males:\n",
    "df_male.Age = 888"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "What's this? **We get a warning!**\n",
    "* As can be seen below, the `Age` value for males has been modified in the `df_male` DataFrame, but not in the\n",
    "  original `df` DataFrame.\n",
    "\n",
    "<div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df_male.head(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-info\">\n",
    "\n",
    "In this case, the change is made to `df_male` only and not to the original DataFrame `df`.\n",
    "\n",
    "Sadly, it is not easy to know when you get a **view** or a **copy**.\n",
    "\n",
    "<br>\n",
    "\n",
    "![image.png](img/view_copy.png)\n",
    "\n",
    "<br>\n",
    "\n",
    " * **View:** pointer to the original DataFrame (or to a subset of it).\n",
    " * **Copy:** new DataFrame object (data is physically copied in memory).\n",
    "   Modifying a copy leaves the original data untouched.\n",
    "\n",
    "In general, **using `.loc[]` should return a view**, however that also depends on the evaluation order of some of the performed operations.\n",
    "\n",
    "<br>\n",
    "\n",
    "When you intend to make a copy, it is recommended to explicitly use the **`copy()`** method of DataFrame.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Explicitly create a copy of the DataFrame returned by .loc[]\n",
    "df_male = df.loc[df.Sex == 'male', : ].copy()\n",
    "\n",
    "# Now we don't get a warning anymore:\n",
    "df_male.Age = 888\n",
    "df_male.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "# 4. Operations on columns <a id='4' />\n",
    "\n",
    "## 4.1 Arithmetic and logical operations <a id='41' />\n",
    "\n",
    "A great strength of pandas *DataFrame* is that they allow to use **arithmetic operators directly on columns**.  \n",
    "And as we have seen when doing conditional selection, this also works with **logical operators**, such as `>`, `<`, `==`, or `!=`.\n",
    "\n",
    "> *Note:* the usual shortcuts to increment/decrement a variable also apply here:\n",
    ">\n",
    ">   ```py\n",
    ">   df[\"column\"] += x  # Increment the column by `x`.\n",
    ">   df[\"column\"] -= x  # Decrement the column by `x`.\n",
    ">   df[\"column\"] /= x  # Divide the column by `x`.\n",
    ">   df[\"column\"] *= x  # Multiply the column by `x`.\n",
    ">   ```\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples**:\n",
    "\n",
    "* In the Titanic dataset, **increase the age of all passengers by 1 year**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Print the DataFrame for reference.\n",
    "df = pd.read_csv(\"data/titanic.csv\").dropna()\n",
    "df.Age = df.Age.astype(int)\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Increase everyone's age by 1 year.\n",
    "df.Age = df.Age + 1\n",
    "df.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Examples using the Swiss 1880 census dataset:**\n",
    "* The `Total` column gives the total number of registered inhabitants in a given town.\n",
    "* The `Female` columns gives the number of women in a given town."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load the Swiss 1880 census dataset.\n",
    "df_census = pd.read_csv(\"data/swiss_census_1880.csv\")\n",
    "df_census.head(3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* To compute the **fraction of women in each town**, we can simply write:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df_census.Female / df_census.Total"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Better yet - we can very easily assign our result to a **new column**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df_census[\"Female_Fraction\"] = df_census.Female / df_census.Total\n",
    "\n",
    "# Display DataFrame subset of interest.\n",
    "df_census.loc[:, [\"town name\", \"Total\", \"Female\", \"Female_Fraction\"]].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* We can test whether the dataset is consistent: the total number of women + men should\n",
    "  equal the total population of a town.\n",
    "\n",
    "> **Tip:** you can **invert a mask** (or any vector of boolean values) by prefixing it with **`~`**:\n",
    ">\n",
    ">    ```py\n",
    ">    df.loc[~mask, :]\n",
    ">    ```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mask = df_census.Male + df_census.Female == df_census.Total\n",
    "\n",
    "# Display the rows with errors, where the number of women + men does not match the total population.\n",
    "df_census.loc[~mask, [\"town name\", \"Total\", \"Male\", \"Female\"]]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-success\">\n",
    "\n",
    "### Micro-Exercise 5\n",
    "\n",
    "Reload the Titanic dataset (`df = pd.read_csv(\"data/titanic.csv\")`), then perform the following task:\n",
    "   \n",
    "* Children under the age of 10 get a special discount of 50% on their fare.\n",
    "  Apply this by dividing by 2 the `Fare` of eligible passenger in the `df` DataFrame.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Additional task, if you have time:**\n",
    "* Load the Swiss census 1880 dataset: `df_census = pd.read_csv(\"data/swiss_census_1880.csv\")`.\n",
    "* Create a mask to filter the dataset for towns that have a majority of Italian or Romansh speakers.\n",
    "* In which cantons are these towns located, and how many are in each canton?\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## 4.2 Applying built-in summary functions <a id='42' />\n",
    "\n",
    "The pandas `DataFrame` and `Series` objects (reminder: a single column of a `DataFrame` is a `Series`) have a number of **built-in methods to compute summary statistics on a per column (or per row) basis**.\n",
    "\n",
    "* **`.count()`**: number of non-NA values.\n",
    "* **`.value_counts()`**: count the number of occurrences of each value (works better with categorical data).\n",
    "* **`.sum()`**, **`.mean()`**, **`.max()`**, **`.min()`**: sum/mean/max/min values.\n",
    "* **`.std()`**, **`.var()`**: standard deviation and variance values.\n",
    "* **`.round()`**: rounds values to the specified decimal.\n",
    "* **`.all()`/`.any()`**: returns `True` if all elements/at least one element are `True` (truthy), `False` otherwise.\n",
    "* **`.describe()`**: provide a summary of different statistics (mean, median, max, min, etc...).\n",
    "* ... and more\n",
    "\n",
    "**By default, these statistics are computed per column (`axis=0`).** To compute them per row, the `axis=1` argument must be passed.\n",
    "* `axis=0`: apply the operation on columns (this is the default value).\n",
    "* `axis=1`: apply the operation on rows.\n",
    "\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples:**\n",
    "* Compute the mean of an individual column (pandas `Series`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "\n",
    "# Average passenger age:\n",
    "df[\"Age\"].mean()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* Get the number of passengers in each class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df[[\"Pclass\"]].value_counts()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* Retrieve the maximum value of the `Age` and `Fare` columns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df[[\"Age\", \"Fare\"]].max()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "Sometimes what we want is not the maximum/minimum value itself but **the index at which the maximum/minimum value is found** (e.g. to retrieve the entire row corresponding to that max/min value).  We can get this using:\n",
    "* **`.idxmax()`** to retrieve the index of the row with the maximum value.\n",
    "* **`.idxmin()`** to retrieve the index of the row with the minimum value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Get the row of the passenger that paid the highest ticket price.\n",
    "print(\"Index of row with max value of 'Fare':\", df.Fare.idxmax())\n",
    "\n",
    "df.loc[[df.Fare.idxmax()], ]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> **Tip:** to prevent the selection of a single row to be converted to a *Series*, we can pass the\n",
    "> single element we select as a list with one element (in this case `[df.Fare.idxmax()]` instead\n",
    "> of `df.Fare.idxmax()`).\n",
    "> \n",
    "> ```py\n",
    "> df.loc[[df.Fare.idxmax()], ]\n",
    "> ```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## 4.3 Applying custom functions <a id='43'/>\n",
    "\n",
    "### Apply custom function to individual elements of a *DataFrame* or a *Series* (column of a DataFrame)\n",
    "\n",
    "* **`.map(<function to apply>)`**: applies a given function to each element of a `DataFrame`/`Series`.\n",
    "\n",
    "\n",
    "<br>\n",
    "\n",
    "**Example:**\n",
    "\n",
    "* Let's start by creating a custom function. **It is important that this function takes exactly 1 argument** (to be specific, no more than 1 positional argument, additional optional keyword arguments can be present)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math\n",
    "\n",
    "# Declare a custom function the computes the log10 of a value.\n",
    "def log10(x):\n",
    "    \"\"\"Return the log10 of the input value.\"\"\"\n",
    "    return 0 if x <= 0 else math.log10(x)\n",
    "\n",
    "# Test run of our custom function.\n",
    "for x in (0, 1, 10, 100, 1000):\n",
    "    print(f\"{x} -> {log10(x)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* Let's now **apply our `log10` function to (each element of) the `Fare` column** in the Titanic dataframe.  \n",
    "> *Notes:*\n",
    ">  * This does not modify the content of the DataFrame, but returns a pandas Series object.\n",
    ">  * This is only possible if the custom function - here `log10` - takes exactly 1 positional argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "\n",
    "df[\"Log10_fare\"] = df.Fare.map(log10)\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* **`.map()` also works on entire DataFrames**: it will apply the custom function to each element\n",
    "  of the *DataFrame*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df[[\"Age\", \"Fare\", \"Pclass\"]].map(log10).head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "> *Note:* if the custom function we want to pass is short and simple, we can write it as a\n",
    "> **lambda expression** (i.e. anonymous function) rather than defining a function for it.\n",
    ">\n",
    ">   ```py\n",
    ">   # The same log10 function as we used above.\n",
    ">   df[[\"Age\", \"Fare\", \"Pclass\"]].map(lambda x: 0 if x <= 0 else math.log10(x))\n",
    ">\n",
    ">   # A simple function that computes the square of a value.\n",
    ">   df[[\"Age\", \"Fare\", \"Pclass\"]].map(lambda x: x**2)\n",
    ">   ```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-info\">\n",
    "    \n",
    "\n",
    "### Additional material: applying custom functions to a column as a whole (function takes entire column as input)\n",
    "\n",
    "* **`.apply()`**: applies a custom function to the columns of a *DataFrame* as a whole.\n",
    "* The custom function must accept a single positional argument that expects a **sequence of values**.\n",
    "* **Warning:** the `.apply()` method also exists for `Series`, but it applies the specified\n",
    "  function to each element of the *Series*. In other words, it behaves just like `.map()` does on *DataFrames*.\n",
    "\n",
    "\n",
    "**Example:**\n",
    "    \n",
    "```py\n",
    "def sum_of_squares(values):\n",
    "    \"\"\"Computes the sum of squares of a sequence of values.\"\"\"\n",
    "    return sum([x**2 for x in values])\n",
    "\n",
    "\n",
    "df_subset = df.dropna()                                     # Create a new DataFrame with no NA values.\n",
    "df_subset[[\"Age\", \"Fare\", \"Pclass\"]].apply(sum_of_squares)  # Apply custom function by column.\n",
    "\n",
    "# Returns the following Series:\n",
    "#  Age       7.743160e+05\n",
    "#  Fare      2.843380e+06\n",
    "#  Pclass    4.071000e+03\n",
    "#  dtype: float64\n",
    "```\n",
    "\n",
    "* Functions can also be applied to **by row** by passing **`axis=1`**.\n",
    "\n",
    "```py\n",
    "df_subset[[\"Age\", \"Fare\", \"Pclass\"]].apply(sum_of_squares, axis=1) \n",
    "```\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "    \n",
    "### Important: vectorization vs. loops\n",
    "\n",
    "When processing data in a `DataFrame`, you should **avoid using loops** as much as possible.  \n",
    "Instead, use the pandas vectorization functions: `.map()`, `.apply()`.\n",
    "    \n",
    "* Here is an example of a simple benchmark, where the **vectorized version is 100x faster** than using a loop.  \n",
    "  *Note:* `%timeit` is a Jupyter \"magic function\" that allows to benchmark a line of code.\n",
    "\n",
    "```py\n",
    "# Define a function that updates a DataFrame using a loop -> an example of what NOT TO DO.\n",
    "def loop_method(df):\n",
    "    abbreviations = {\"S\": \"Southampton\", \"C\": \"Cherbourg\", \"Q\": \"Queenstown\"}\n",
    "    for index, value in enumerate(df[\"Embarked\"]):\n",
    "        df.loc[index, \"Embarked\"] = abbreviations.get(value, None)\n",
    "\n",
    "# Define a function that does the same `loop_method`, but using vectorization.\n",
    "def vectorized_method(df):\n",
    "    df.Embarked = df.Embarked.map({\"S\": \"Southampton\", \"C\": \"Cherbourg\", \"Q\": \"Queenstown\"})\n",
    "\n",
    "# Let's benchmark our two implementations.\n",
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "%timeit loop_method(df)               # -> 60.3 ms ± 1.38 ms per loop\n",
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "%timeit vectorized_method(df)         # -> 534 µs ± 23.2 µs per loop. More than 100x faster!\n",
    "```\n",
    "\n",
    "<div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-success\">\n",
    "\n",
    "### Micro-Exercise 6\n",
    "\n",
    "Here is a function that will expand the abbreviated value for \"Port of embarkation\" (column name `Embarked`) in the Titanic dataset to the full name of the city (\"C\" for \"Cherbourg\", \"Q\" for \"Queenstown\", \"S\" for \"Southampton\").\n",
    "\n",
    "```py\n",
    "def expand_port_of_embarkation(input_value):\n",
    "    \"\"\"Converts the abbreviated port of embarkation to its full name.\"\"\"\n",
    "    abbreviations = {\"C\": \"Cherbourg\", \"Q\": \"Queenstown\", \"S\": \"Southampton\"}\n",
    "    return abbreviations.get(input_value, None) if len(str(input_value)) == 1 else input_value\n",
    "```\n",
    "\n",
    "<br>\n",
    "\n",
    "Using the above function, your task is to add a new `Embarked_city` column to the DataFrame that contains the full name of the port of embarkation of each passenger.\n",
    "\n",
    "If needed, you can reload the Titanic dataset with: `df = pd.read_csv(\"data/titanic.csv\")`\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "\n",
    "# 5. Writing DataFrames to disk <a id='5'/>\n",
    "----------------------------------------------------------\n",
    "\n",
    "Just like when reading a file, **writing a DataFrame to disk** has several functions depending on the format in which the data should be stored.\n",
    "* **`to_csv()`**: write a DataFrame as comma-separated file, or any other separator-delimited format such as\n",
    "  tab-delimited. \n",
    "* **`to_excel()`**: write a DataFrame in Excel format.\n",
    "* **`to_html()`**: write a DataFrame in HTML format.\n",
    "* See [here for more writer functions...](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html).\n",
    "\n",
    "These functions take similar arguments as the reader functions. E.g. when using the `to_csv()` writer functions, some useful arguments are:\n",
    "\n",
    "* **`sep`**: the type of delimiter to use. By default, `sep=\",\"`.\n",
    "  To write a tab-delimited file e.g., one would set `sep=\"\\t\"`.\n",
    "* **`header=None`**: to not include the header in the exported file.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Example:** write the `df` DataFrame to a file named `my_data.csv` in the current working directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.to_csv(\"my_data.csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "<div class=\"alert alert-block alert-success\">\n",
    "\n",
    "# Exercises\n",
    "-----------------\n",
    "\n",
    "Exercises are located in the dedicated notebook `exercises_course1.ipynb`.\n",
    "\n",
    "* **Exercise 1.1**\n",
    "* If you have time: **additional exercises 1.2 and 1.3**\n",
    "\n",
    "\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "# Supplementary material - additional topics, not covered in class <a id='a' />\n",
    "---------------------------\n",
    "\n",
    "Pandas is a very large library, and we can only cover part of it during the class.\n",
    "Here is a **collection of additional topics that are useful to know**.  \n",
    "This section will not be covered in the course, but you can read it on your own if you are interested.\n",
    "\n",
    "Topics presented in the supplementary material include (but are not limited to):\n",
    "\n",
    "* **Sorting** operations on dataframes.\n",
    "* **Dropping rows** with missing values.\n",
    "* **Grouping data** by factor.\n",
    "* **Creating** DataFrames and Series **from scratch**.\n",
    "* **Concatenate**, **merge** and **join** DataFrames.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "## Annex 1 - Sorting operations on dataframes  <a id='a1' />\n",
    "\n",
    "DataFrames can be sorted using:\n",
    "\n",
    "* **`sort_values()`**: to sort rows based one or more column(s).\n",
    "  * The name of the column to sort on must be passed to the function.\n",
    "  * To sort on multiple columns, a list of column names must be passed.\n",
    "* **`sort_index()`**: to sort rows based on the dataframe index.\n",
    "\n",
    "Both functions take the optional arguments:\n",
    "* `ascending=True`: sort in ascending (`True`, the default) or descending (`False`) order.\n",
    "* `inplace=False`: if `True` the original DataFrame is sorted, if `False` a sorted copy\n",
    "  of the DataFrame is returned (this is the default).\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load dataset with Unique Molecular Identifier (UMI) counts per gene.\n",
    "df = pd.read_table('data/pbmc_data.countMatrix.50.txt.zip', sep=\" \", index_col=0)\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* Sort the `df` DataFrame in descending order of the first column.  \n",
    "> *Note:* to avoid having to pass the explicit column name, we use `df.columns[0]`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "df = df.sort_values(df.columns[0], ascending=False)\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* Sort the `df` DataFrame in descending order of the first 3 columns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "df = df.sort_values(list(df.columns[0:3]), ascending=False)\n",
    "df.head(10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* Sort the DataFrame by index values using **`sort_index()`**:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df.sort_index(ascending=True).head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## Annex 2 - Dropping rows with missing values (`NaN`) <a id='a2' />\n",
    "\n",
    "Datasets frequently contain rows with missing data, indicated as `NaN` or `NA` (stands for \"not a number\" - but it is used even if the column type is not numeric).\n",
    "\n",
    "In the titanic dataset for instance, `NaN` values are found in the columns `Age` and `Embarked`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "df.head(100).tail()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To remove rows with `NaN` values, the **`dropna()`** method of a DataFrame can be used:\n",
    "* By default, `dropna()` drops rows containing `NaN` values. Columns can be dropped by passing `axis=1`\n",
    "  to the function.\n",
    "* By default, the method returns a **copy of the DataFrame**. Use `dropna(inplace=True)` to modify\n",
    "  the original DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.dropna().head(80).tail()\n",
    "print(\"Number of rows in input DataFrame:\", df.shape[0])\n",
    "print(\"Number of rows after removing NaN values:\", df.dropna().shape[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## Annex 3 - Grouping data by factor <a id='a3' />\n",
    "\n",
    "When analyzing a dataset where some variables (columns) are factors (categorical values), it is often useful to group the samples (rows) by these factors.  \n",
    "This can be done using the method:\n",
    "\n",
    "* **`.groupby()`**: group data by one or more categorical columns.\n",
    "\n",
    "\n",
    "<br>\n",
    "\n",
    "**Example:** grouping by a **single factor**.\n",
    "\n",
    "* We earlier computed the proportions of women and men that survived in the Titanic dataset.\n",
    "  Using **`.groupby()`** can make this a lot easier.\n",
    "\n",
    "> *Note:* since a mean value can only be computed for numeric values, the argument `numeric_only` must be\n",
    "> set to `True` so that any non-numeric column gets skipped."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "df.groupby(\"Sex\").mean(numeric_only=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Example:** grouping by **multiple factors**.\n",
    "\n",
    "* Compute mean values by gender and passenger class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df.groupby([\"Sex\", \"Pclass\"]).mean(numeric_only=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-success\">\n",
    "\n",
    "### Micro-Exercise A3 - Grouping data\n",
    "\n",
    "* Make a copy of the `df` data frame with `df.copy()`. Name it `dfc`, as shown here:\n",
    "```python\n",
    "dfc = df.copy()\n",
    "```\n",
    "\n",
    "* Add a new column named \"Age_category\" to `dfc`. Make use of the `age_category` function defined below\n",
    "  to classify passengers into their respective age classes.\n",
    "```python\n",
    "def age_category(x):\n",
    "    age_classes = {\"child\": 12, \"teenager\": 17, \"adult\": 64, \"senior\": 200}\n",
    "    for label, threshold in age_classes.items():\n",
    "        if x <= threshold:\n",
    "            return label\n",
    "```\n",
    "\n",
    "* Compute survival rates by gender, age category and passenger class.\n",
    "\n",
    "<div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## Annex 4 - Creating DataFrames and Series from scratch <a id='a4' />\n",
    "\n",
    "### Creating DataFrames\n",
    "\n",
    "To create a new pandas DataFrame, we pass a `dict` (dictionary) to **`pd.DataFrame()`**, where:\n",
    "\n",
    "* The dictionary's **keys are column names**.\n",
    "* The dictionary's **values are the values for the given column**. The values can be either:\n",
    "    * A sequence - e.g. a `list` or a `tuple`.\n",
    "    * A unique value - in which case all values in the column will be identical.\n",
    "  \n",
    "By default, a numeric index is auto-generated with values starting at `0` (corresponding to row positions).  \n",
    "A custom index can be set by adding the `index` argument when instantiating the DataFrame, or the default index can be replaced by a custom index after the DataFrame is created."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "df = pd.DataFrame(\n",
    "    {\n",
    "        \"Color\": (\"red\", \"green\", \"pink\", \"green\"),\n",
    "        \"Speed\": [8, 7, 5, 5],\n",
    "        \"Jump\": [7, 8, 7, 5]\n",
    "    },\n",
    "    index=[\"Mario\", \"Luigi\", \"Peach\", \"Yoshi\"]\n",
    ")\n",
    "\n",
    "# Note: evaluating a DataFrame object at the end of a jupyter cell will render it nicely in the notebook.\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Creating a pandas Series <a id='1.2'></a>\n",
    "\n",
    "To create a new pandas **Series**, we pass a sequence (e.g. list, tuple, dict, generator) to **`pd.Series()`**:\n",
    "* The optional `name` argument allows to associate a \"name\" to the Series.\n",
    "* As with `pd.DataFrame()`, an optional `index` argument can be passed (by default the index\n",
    "  is set to numerical values starting from `0`).\n",
    "* Alternatively, a `dict` can be passed as input to `pd.Series()`, in which case the keys of the dictionary\n",
    "  are used as index values, and the values as values for the Series.\n",
    "  \n",
    "The basic characteristics of a Series (here named `s`) are:\n",
    "* Its **length**: retrieved with **`s.size`** or `len(s)`\n",
    "* Its **name**: retrieved with **`s.name`**.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Example:**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_player = pd.Series(\n",
    "    [\"Toad\", \"white\", \"10\"],\n",
    "    index=[\"Color\", \"Speed\", \"Jump\"],\n",
    "    name=\"Toad\",\n",
    ")\n",
    "\n",
    "new_player"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "### Adding a Series as a row to a DataFrame with `pd.concat()`\n",
    "\n",
    "**`pd.concat()`** is a method generally used to concatenate DataFrames (either along rows or columns). But it can also be used to add a Series as a new row to an existing DataFrame.\n",
    "\n",
    "Note that:\n",
    "* We are actually converting the Series to DataFrame with `.to_frame()`, and transpose it with `.T`.\n",
    "* The function does **not modify the existing DataFrame/Series** given in input, but **returns a new one**.\n",
    "* For the concatenation to work, the **index of the Series must correspond to the column names of the \n",
    "  DataFrame**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pd.concat((df, new_player.to_frame().T))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## Annex 5 - Concatenate, merge and join DataFrames  <a id='a5' />\n",
    "\n",
    "### DataFrame concatenation\n",
    "\n",
    "The **`.concat()`** method allows to **concatenate two or more DataFrames**.  \n",
    "The `axis` argument allows to specify whether the concatenation should be along rows or columns.\n",
    "\n",
    "* **`.concat([df1, df2, ...], axis=0)`**: concatenate rows of the DataFrames. This is the default.\n",
    "* **`.concat([df1, df2, ...], axis=1)`**: concatenate columns of the DataFrames.\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples:**\n",
    "\n",
    "* Let's start by creating a few small DataFrames."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df1 = pd.DataFrame(\n",
    "    {\n",
    "        \"Color\": [\"red\", \"green\", \"pink\", \"green\"],\n",
    "        \"Speed\": [8, 7, 5, 5],\n",
    "        \"Jump\": [7, 8, 7, 5]\n",
    "    },\n",
    "    index=[\"Mario\", \"Luigi\", \"Peach\", \"Yoshi\"]\n",
    ")\n",
    "df2 = pd.DataFrame(\n",
    "    {\n",
    "        \"Color\": (\"white\", \"yellow\"),\n",
    "        \"Speed\": [10, 3],\n",
    "        \"Jump\": [7, 3]\n",
    "    },\n",
    "    index=[\"Toad\", \"Bowser\"]\n",
    ")\n",
    "df3 = pd.DataFrame(\n",
    "    {\n",
    "        \"Strength\": [5, 10, 6],\n",
    "        \"Groove\": [7, 1, 10],\n",
    "    },\n",
    "    index=[\"Mario\", \"Bowser\", \"Yoshi\"]\n",
    ")\n",
    "\n",
    "print(df1)\n",
    "print(df2)\n",
    "print(df3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* We can now concatenate `df1` and `df2` by rows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pd.concat([df1, df2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `\"outer\"` vs. `\"inner\"` joining\n",
    "\n",
    "* By default, `.pd.concat()` uses the value **`join=\"outer\"`** to concatenate DataFrames.\n",
    "  This means that all rows/columns of both DataFrames are kept, and `NaN` values are inserted\n",
    "  in missing fields. In other words, it takes the **union** of both DataFrames."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pd.concat([df1, df3], axis=1, join=\"outer\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Using **`join=\"inner\"`** only keeps rows with an index that is present in both DataFrames.\n",
    "  In other words, it takes the **intersection** of both DataFrames."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "pd.concat([df1, df3], axis=1, join=\"inner\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "### Merge and join\n",
    "\n",
    "The **[`merge()`](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.merge.html)** and **[`join()`](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.join.html)** methods allow to combine DataFrames, linking their rows based on a common column (also referred to as a **key**).\n",
    "\n",
    "To illustrate these 2 methods, let's create 2 DataFrames that we can merge.\n",
    "> *Note:* this also illustrates how **a dataframe can be constructed from a dictionary** data structure.\n",
    "  The dictionary keys are treated as column names, and the list of values associated with a key is\n",
    "  treated as list of elements in the corresponding column. Note that all columns should have the same\n",
    "  number of elements (or a single element, in which case all rows of the column are assigned this same\n",
    "  element).  \n",
    "  If no index is specified, pandas uses its default indexing, i.e. row positions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df1 = pd.DataFrame(\n",
    "    {\n",
    "        \"key\": [\"b\", \"b\", \"a\", \"c\", \"a\", \"a\", \"b\"], \n",
    "        \"data1\": range(7)\n",
    "    }\n",
    ")\n",
    "df1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df2 = pd.DataFrame({\n",
    "    \"key\": [\"a\", \"b\", \"d\"], \n",
    "    \"data2\": range(3)\n",
    "})\n",
    "df2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Let's now merge the two data frames**, with the default application of the **`.merge()`** method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pd.merge(df1, df2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "How has python interpreted our call to `.merge()`?\n",
    "\n",
    "1. It has assumed that we want to merge on the basis of the common `key` column.\n",
    "2. It has identified the values of `key` which occur in both dataframes.\n",
    "3. It has generated a dataframe with all combinations of rows from dataframes 1 and 2 that are \n",
    "   associated with a particular `key` value.\n",
    "\n",
    "We can be more precise by specifying how to merge the dataframes, using the **`on`** option:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pd.merge(df1, df2, on=\"key\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**By default, `.merge` performs an \"inner\" operation**, taking the intersection of the key sets. However, we can specify the way we want to merge by passing `\"outer\"`, `\"left\"`, `\"right\"` to the **`how`** argument. This determines which set of keys to consider (the union of the two sets, all of those that occur in df1, all of those that occur in df2). Missing values show up as `NaN`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pd.merge(df1, df2, on=\"key\", how=\"outer\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Merging can also be done based on the index values**. Let's illustrate this using another dataset:\n",
    "\n",
    "* First let's create 2 DataFrames to merge: `df_A` and `df_B`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "df = pd.read_table('data/pbmc_data.countMatrix.50.txt.zip', sep=\" \", index_col=0)\n",
    "\n",
    "# Split the columns based on whether or not they start with \"AAAT\".\n",
    "mask = df.columns.str.startswith(\"AAAT\")\n",
    "AAAT_cols = df.columns[ mask ]\n",
    "nonAAAT_cols = df.columns[ ~mask ]\n",
    "\n",
    "df_A = df[AAAT_cols]\n",
    "df_B = df[nonAAAT_cols]\n",
    "\n",
    "df_A.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df_B.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "* Merge the two DataFrames based on the index:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "merged_df = pd.merge(df_A, df_B, left_index=True, right_index=True)\n",
    "merged_df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## Annex 6 - Mixed selection by names and positions for `.loc[]` and `.iloc[]` <a id='a6' />\n",
    "    \n",
    "A frequent situation is that we want to select rows based on a certain condition, e.g. `df[\"Age\"] <= 35`, \n",
    "and columns based on position , e.g. `1:3` to select the second and third columns. The problem is then the following:\n",
    "* **`.loc[]`** does not support column selection by position: it requires index values, i.e. column\n",
    "  and row names.\n",
    "* **`.iloc[]`** does not support boolean results (`True`/`False`) for row selection: it requires to get\n",
    "  a position.\n",
    "  \n",
    "Possible solutions to mixed indexing are:\n",
    "* Use the **`.columns` attribute** to get the names of columns, which can then be used with `.loc[]`.\n",
    "  ```python\n",
    "  df.loc[ df[\"Age\"] <= 35, df.columns[1:3] ]\n",
    "  ```\n",
    "* If the **index values correspond to row positions (0, 1, 2, ...)**, the `.index` attribute can be \n",
    "  used to get row positions and use them with `.iloc[]`:\n",
    "  ```python\n",
    "  df.iloc[ df[df[\"Age\"] <= 35].index, 1:3 ]\n",
    "  ```\n",
    "* With `.iloc[]`, use the **`.query()` method** to select rows:\n",
    "  ```python\n",
    "  df.iloc[:, 0:6].query(\"Age <= 35\")\n",
    "  ```\n",
    "\n",
    "<br>\n",
    "\n",
    "**Examples:**\n",
    "    \n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Select passengers younger than 35 and the 5 first columns:\n",
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "df.loc[df[\"Age\"] < 35, df.columns[0:5]].head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Same as above, but using the \"iloc[]\" indexer:\n",
    "df.iloc[:, 0:6].query(\"Age < 35\").head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## Annex 7: more ways to add rows to a DataFrame <a id='a7' />\n",
    "\n",
    "Several options exist to add or edit rows of a DataFrame:\n",
    "\n",
    "* As we have already seen, the easiest way is to **assign a sequence of values to a new row**\n",
    "  (or an existing one to overwrite it).  \n",
    "  **Important:** the sequence must have the same length as there are columns in the DataFrame.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "df = pd.read_csv(\"data/titanic.csv\")\n",
    "\n",
    "# Add a new row to the DataFrame.\n",
    "df.loc[len(df),:] = [\"Bob\", \"male\", 27, 3, 1, 0, 10, \"S\"]\n",
    "df.tail()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "A row can also be added by **assigning a `Series` to a new row** (or an exiting row, to overwrite it).  \n",
    "When using this method:\n",
    "* The names used in the Series' index must match with the column names.\n",
    "* Missing fields are allowed.\n",
    "* The order of fields has no importance, since they are named.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_passenger = pd.Series({\"Name\": \"Alice\", \"Sex\": \"female\", \"Embarked\": \"C\", \"Fare\": 95})\n",
    "df.loc[len(df),:] = new_passenger\n",
    "df.tail()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "Another option is to **concatenate a DataFrame** with another `DataFrame` or `Series` using  **`pd.concat()`**, which takes a list of `DataFrame` or `Series`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "df = pd.concat(\n",
    "    [\n",
    "        df,\n",
    "        pd.DataFrame(\n",
    "            {\n",
    "                \"Name\": \"Chuck Norris\",\n",
    "                \"Sex\": \"fluid\",\n",
    "                \"Age\": pd.NA,\n",
    "                \"Pclass\": 2,\n",
    "                \"Survived\": 2,\n",
    "                \"Family\": pd.NA,\n",
    "                \"Fare\": 0,\n",
    "                \"Embarked\": \"S\"\n",
    "            },\n",
    "        index=[df.shape[0]])\n",
    "    ]\n",
    ")\n",
    "df.tail()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "**Adding a row at specific location** is possible, if a little hacky as you first have to add the row at the\n",
    "end of the DataFrame, and then re-order the rows.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.loc[890.5,:] = [\"Bob Jr.\", \"male\", 2, 3, 1, 1, 10, \"S\"]\n",
    "df.sort_index(inplace=True)\n",
    "df.reset_index(inplace=True, drop=True)  # With drop=True, the index is reset to the default index values.\n",
    "df.tail()\n",
    "\n",
    "# Alternatively: df = df.sort_index().reset_index(drop=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "<br>\n",
    "\n",
    "[Back to ToC](#toc)\n",
    "\n",
    "## Annex 8 - Wide and long format <a id='a8' />\n",
    "\n",
    "Most dataset are usually stored in so-called **wide format**, because it is more efficient and avoids duplication of information in the table. However, it can sometimes be interesting to go from wide to long or long to wide, because some operations are easier on one format or the other.\n",
    "\n",
    "**Wide format:**\n",
    "\n",
    "| Id     | mol1   | mol2    |\n",
    "| ------ |:------:| -------:|\n",
    "| a      | 1.0    | 10.0    |\n",
    "| b      | 2.0    |   20.0  |\n",
    "| c      | 3.0    |    30.0 |\n",
    "\n",
    "**Long format:**\n",
    "\n",
    "| Id     | Value  | Attr    |\n",
    "| ------ |:------:| -------:|\n",
    "| a      | 1.0    | mol1    |\n",
    "| a      | 10.0   | mol2    |\n",
    "| b      | 2.0    | mol1    |\n",
    "| b      | 20.0   | mol2    |\n",
    "| c      | 3.0    | mol1    |\n",
    "| c      | 30.0   | mol2    |\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_table(\"data/pbmc_data.countMatrix.50.txt.zip\", index_col=0,sep=' ')\n",
    "\n",
    "## data in wide format.\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "The conversion to the **long** format is done using the **`.melt()`** method of DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df[\"gene\"] = df.index\n",
    "df_long = pd.melt(df, id_vars=[\"gene\"])  # Convert to long format, with gene as identifiers.\n",
    "df_long.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<br>\n",
    "\n",
    "Having the data in long format now allows us to do this, which was a bit difficult otherwise:  \n",
    "> *Note:* running the cell below can take a few seconds (notice the \"[ \\* ]\" to the left of the Jupyter Notebook cell, indicating that the cell is computing)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import seaborn as sns\n",
    "\n",
    "df_long[\"logVal\"] = np.log10(10**0 + df_long[\"value\"])\n",
    "\n",
    "g = sns.catplot(\n",
    "    x=\"logVal\", y=\"variable\",\n",
    "    orient=\"horizontal\" , data=df_long, \n",
    "    kind=\"bar\", aspect=2, height=7\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.13.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}